# Factuarea API > Factuarea is a multi-tenant invoicing SaaS for Spanish businesses. The REST API (`https://api.factuarea.com/v1`) authenticates with API keys (`fact_live_*` prefix, fine-grained scopes), uses UUID v7 as opaque identifiers, returns normalized JSON envelopes (`data` + `meta`), and is fully compliant with Spanish tax law: **VeriFactu** (Royal Decree 1007/2023, AEAT real-time invoice registration), **FacturaE** 3.2.x (XML for B2G public-sector invoicing), and **Modelos 303/347** (quarterly VAT and informative declarations). All write endpoints support **idempotency keys**; events are delivered as **HMAC SHA-256 signed webhooks** with dual-secret rotation and exponential retries. This file follows the [llms.txt](https://llmstxt.org) convention. For a single-file dump of every page as clean Markdown (no MDX components, no layout chrome, no JavaScript), fetch `/llms-full.txt`. ## Getting Started - [Factuarea API](https://docs.factuarea.com/): The Factuarea REST API to automate your multi-tenant invoicing SaaS for Spanish businesses. - [Authentication](https://docs.factuarea.com/guides/authentication): API keys with fact_live_ / fact_test_ prefixes, fine-grained scopes, grace-period rotation and IP allowlist. ## Core concepts - [Pagination](https://docs.factuarea.com/guides/pagination): Cursor pagination with starting_after and ending_before. No ?page=, Stripe-style semantics. - [Idempotency](https://docs.factuarea.com/guides/idempotency): Idempotency-Key header with 24h TTL. Retry POST without duplicating resources. - [Error handling](https://docs.factuarea.com/guides/errors): Normalized error envelope, type and code catalog with stable anchors, and retry strategy. - [Rate limits](https://docs.factuarea.com/guides/rate-limits): Per-minute and monthly quotas per tier. X-RateLimit-* headers and recommended back-off. - [Versioning](https://docs.factuarea.com/guides/versioning): Flat-versioned /v1 policy with Factuarea-Version header. Stability and deprecation commitments. ## Webhooks and events - [Webhooks](https://docs.factuarea.com/guides/webhooks): Signed POST notifications with HMAC SHA256. Verification, exponential retries and secret rotation. - [Events](https://docs.factuarea.com/guides/events): Read-only event objects with an opaque id. Historical query via the API and webhook delivery. - [Create a webhook endpoint](https://docs.factuarea.com/api-reference/webhooks/public-api.v1.webhook_endpoints.create): 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. - [Delete a webhook endpoint](https://docs.factuarea.com/api-reference/webhooks/public-api.v1.webhook_endpoints.delete): Delete a webhook endpoint. In-flight deliveries are not cancelled but no new deliveries are queued. - [List all webhook endpoints](https://docs.factuarea.com/api-reference/webhooks/public-api.v1.webhook_endpoints.list): List your webhook endpoints with cursor-based pagination. - [List webhook deliveries](https://docs.factuarea.com/api-reference/webhooks/public-api.v1.webhook_endpoints.deliveries.list): List delivery attempts for a webhook endpoint with cursor-based pagination. Each delivery captures the HTTP response status, body (truncated), duration, and retry schedule. - [Ping webhook endpoint](https://docs.factuarea.com/api-reference/webhooks/public-api.v1.webhook_endpoints.ping): Send a test event (`webhook.ping`) to the endpoint to verify it is reachable and the signature handshake works. The synthetic delivery appears in `GET /webhook_endpoints/{webhook_endpoint}/deliveries`. - [Replay webhook delivery](https://docs.factuarea.com/api-reference/webhooks/public-api.v1.webhook_endpoints.deliveries.replay): Re-queue a webhook delivery. A new delivery attempt is created (with `attempt: 1`) for the same event/endpoint pair. - [Retrieve a webhook endpoint](https://docs.factuarea.com/api-reference/webhooks/public-api.v1.webhook_endpoints.show): Retrieve a webhook endpoint by its `uuid`. The signing secret is never exposed in this representation. - [Retrieve webhook delivery](https://docs.factuarea.com/api-reference/webhooks/public-api.v1.webhook_endpoints.deliveries.show): Retrieve a single delivery attempt by its `uuid`, including the full event payload that was delivered. - [Rotate webhook secret](https://docs.factuarea.com/api-reference/webhooks/public-api.v1.webhook_endpoints.rotate_secret): Rotate the signing secret of a webhook endpoint. The new secret is returned **once** in this response. The previous secret remains valid for a 24-hour grace period (see `previous_secret_valid_until`) to allow zero-downtime rotation. - [Send a test event](https://docs.factuarea.com/api-reference/webhooks/public-api.v1.webhook_endpoints.test_event): Trigger a test delivery of a real catalog event type to this endpoint, marked `test: true` in the delivered envelope. Unlike `ping` (a synthetic `webhook.ping`), this records a real `Event` (visible in `GET /events`) and queues a signed, retried `WebhookDelivery`. Optionally pass `type` to choose which subscribed event to simulate. The delivery reaches only this endpoint. - [Update a webhook endpoint](https://docs.factuarea.com/api-reference/webhooks/public-api.v1.webhook_endpoints.update): Update a webhook endpoint (URL, description, enabled events, status, IP allowlist). - [List all events](https://docs.factuarea.com/api-reference/events/public-api.v1.events.list): 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]`. - [List event types](https://docs.factuarea.com/api-reference/events/public-api.v1.event_catalog.list): 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). - [Retrieve an event](https://docs.factuarea.com/api-reference/events/public-api.v1.events.show): Retrieve a single event by its `id` (format `evt_`, an opaque identifier). Useful for auditing and replaying webhook payloads. Returns `404 not_found` if the event does not exist or belongs to another company. ## Spanish tax compliance (VeriFactu, FacturaE, Modelos) - [Activate a company certificate](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.certificates.activate): 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. - [Find a VeriFactu record by AEAT CSV](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.records.find_by_csv): 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`. - [Find a VeriFactu record by hash](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.records.find_by_huella): 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. - [Find a VeriFactu record by invoice number](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.records.find_by_invoice_number): 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. - [Force-create VeriFactu record for invoice](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.invoices.verifactu_create): Creates the VeriFactu alta record for an already-issued invoice and enqueues AEAT transmission. Use when automatic creation on send was skipped. - [Get VeriFactu event summary](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.events.summary): Return an aggregated summary of your VeriFactu SIF events grouped by type and outcome. Useful for dashboards. Returned as `{ "data": VeriFactuEventSummary }`. - [Get VeriFactu stats](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.stats): Aggregated KPIs of your VeriFactu records: total count, counts per status (pending, submitted, accepted, rejected, error), breakdown by record and invoice type, and last transmission timestamp. Accepts optional `date_from`, `date_to`, and `environment` filters. Returned as `{ "data": VeriFactuStats }`. - [List AEAT access records](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.aeat_access.list): 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. - [List company certificates](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.certificates.list): List the FNMT (PKCS#12) certificates uploaded for your company. The certificate password is never exposed in this representation. - [List declaración responsable history](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.declaracion.history): 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. - [List VeriFactu events](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.events.list): List the VeriFactu SIF events of your company (alta/anulación transmissions, retries, AEAT responses) with cursor-based pagination. - [List VeriFactu record activity timeline](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.records.activities): Return the audit timeline for a single VeriFactu record (creation, transmission attempts, AEAT acceptance/rejection). Paginated with a page-number cursor. - [List VeriFactu records](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.records.list): 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`. - [Retrieve a VeriFactu event](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.events.show): Retrieve a single VeriFactu SIF event by its `id` (UUID v7). Returns 404 if the event does not exist or belongs to another company. - [Retrieve a VeriFactu record](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.records.show): 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. - [Retrieve an AEAT access record](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.aeat_access.show): 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. - [Retrieve invoice VeriFactu record](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.invoices.verifactu_get): 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. - [Retrieve the active certificate](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.certificates.active): Return the currently active FNMT certificate used to sign VeriFactu transmissions. Returns 404 if no certificate has been uploaded yet. - [Retrieve the current declaración responsable](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.declaracion.current): Return the current (latest) version of the producer-level VeriFactu Declaración Responsable. Read-only: the declaration is global to the producer of the system (Factuarea), not per-company. Returns 404 `declaracion_not_found` if none has been published. - [Retrieve VeriFactu config](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.config): Return the VeriFactu configuration of your company (mode, environment, enrollment status). The certificate password is never exposed. Returned as `{ "data": VeriFactuConfig }`. - [Retry a VeriFactu event](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.events.retry): 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. - [Retry VeriFactu transmission](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.records.retry): Requeues a failed VeriFactu record for transmission to AEAT. Conflict (409) if already accepted, 422 if retry limit exceeded. - [Revoke a company certificate](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.certificates.revoke): Revoke (delete) a company certificate so it can no longer sign VeriFactu transmissions. Returns 404 if the certificate does not exist within your company. - [Subsanar a rejected VeriFactu record](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.records.subsanar): Correct (subsana) an AEAT-rejected VeriFactu record: regenerate the correctable content from the source invoice keeping the original `huella`, reset the transmission round and re-queue the AEAT transmission (202). Returns 422 `record_not_rejected` if the record is not rejected, or `requires_annulment` when the correction affects fingerprint fields (annul + new alta required instead). - [Update VeriFactu settings](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.settings.update): Update the VeriFactu settings of your company (e.g. mode/environment). Returns 422 `business_rule_violation` when a transition is locked by AEAT compliance (for example, once VeriFactu mode has been enabled it cannot be silently disabled). - [Upload a company certificate](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.certificates.upload): Upload an FNMT certificate (PKCS#12, `.p12`/`.pfx`) as `multipart/form-data` with `certificate_file` and `certificate_password`. The file is validated by magic bytes (ASN.1 DER) and capped at 100 KB; the password is encrypted at rest. The uploaded certificate is activated automatically (previous ones are deactivated). The `Location` header points to `/v1/verifactu/certificates/active`. - [Validate the VeriFactu hash chain](https://docs.factuarea.com/api-reference/verifactu/public-api.v1.verifactu.chain.validate): Recompute the VeriFactu hash chain (`huella`) for your company and compare it against the persisted values without mutating data. Returns whether the chain is intact and, if not, the first corrupted record. Rate-limited to 1 request/minute and rejected with 422 `dataset_too_large` for datasets over 50,000 records. - [Download FacturaE XML](https://docs.factuarea.com/api-reference/facturae/public-api.v1.invoices.facturae): Stream the FacturaE 3.2.2 XML for the invoice (B2G compliance), XSD-conformant with full tax breakdown. With an active signing certificate the body is signed XAdES-EPES and served as `.xsig`; without one it is returned unsigned as `.xml`. The `X-Facturae-Signed` header distinguishes the two. Draft invoices return 422. - [List invoice FACe submissions](https://docs.factuarea.com/api-reference/facturae/public-api.v1.invoices.face_submissions.list): Lists the FACe submission history of an invoice (flat array, newest included). Returns `data: []` when the invoice has never been submitted. - [Request FACe submission cancellation](https://docs.factuarea.com/api-reference/facturae/public-api.v1.face_submissions.cancel): Requests the cancellation (anulación 4200) of a FACe submission with a mandatory `reason`. Only allowed while the submission is in a cancellable state (`submitted`, `registered_rcf`, `accounted`); otherwise returns 422 `face_submission_not_cancellable`. The submission transitions to `cancellation_requested` until FACe confirms. - [Retrieve a FACe submission](https://docs.factuarea.com/api-reference/facturae/public-api.v1.face_submissions.show): Retrieves a FACe submission by its `id` (UUID). The `status` field reflects the latest known FACe processing state (`submitted`, `registered_rcf`, `accounted`, `paid`, `rejected`, `cancellation_requested`, `cancelled`, `error`) — the system polls FACe periodically, so a plain GET is the way to track progress (there is no refresh endpoint in v1). - [Submit invoice to FACe](https://docs.factuarea.com/api-reference/facturae/public-api.v1.invoices.face_submissions.submit): Submit an issued invoice to FACe (the Spanish B2G entry point). Requires the client's three DIR3 codes and an active signing certificate; the FacturaE 3.2.2 XML is signed XAdES-EPES and presented to FACe, returning the registry number. No request body — the DIR3 codes are read from the client. Test keys simulate the submission without contacting FACe. - [Download tax report file](https://docs.factuarea.com/api-reference/tax-reports/public-api.v1.tax_reports.download): Downloads the generated file for a tax report. Adds `X-Tax-Report-Hash` header for integrity verification. - [Find a tax report by period](https://docs.factuarea.com/api-reference/tax-reports/public-api.v1.tax_reports.find_by_period): 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. - [Generate Modelo 130](https://docs.factuarea.com/api-reference/tax-reports/public-api.v1.tax_reports.generate_130): 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). - [Generate Modelo 303](https://docs.factuarea.com/api-reference/tax-reports/public-api.v1.tax_reports.generate_303): Generates the Spanish Modelo 303 (quarterly VAT) for the given year and quarter in the requested format (txt_aeat, pdf, excel). - [Generate Modelo 347](https://docs.factuarea.com/api-reference/tax-reports/public-api.v1.tax_reports.generate_347): Generates the Spanish Modelo 347 (annual third-party operations > 3,005.06 EUR) for the given year. - [List tax report activities](https://docs.factuarea.com/api-reference/tax-reports/public-api.v1.tax_reports.activities): Returns the cursor-paginated activity timeline (generation, download, etc.) of a single tax report generation. - [List tax report history](https://docs.factuarea.com/api-reference/tax-reports/public-api.v1.tax_reports.history): Returns the paginated history of generated tax reports for the company. Optional filters: type, year. - [Preview a tax report](https://docs.factuarea.com/api-reference/tax-reports/public-api.v1.tax_reports.preview): Computes the breakdown of a tax report without persisting a generation or writing files. Ideal for interactive UIs that confirm totals before commit. - [Retrieve tax report stats](https://docs.factuarea.com/api-reference/tax-reports/public-api.v1.tax_reports.stats): Returns aggregate KPIs of the generated tax report history: totals by type and format, accumulated file size, and the current fiscal quarter/year. ## API Reference — Account and authentication - [Create an API key](https://docs.factuarea.com/api-reference/account/public-api.v1.account.api_keys.create): Create a new API key and return its plaintext `secret` exactly once — store it now, it cannot be retrieved later. Requesting a scope above the holder's plan or outside the catalog returns 422. Pass `environment: test` to mint a sandbox key (`fact_test_`) with no real-world side effects; omit it for a live key (`fact_live_`). - [List available personalization templates](https://docs.factuarea.com/api-reference/account/public-api.v1.account.personalization.templates): 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/account/personalization`. - [List your API keys](https://docs.factuarea.com/api-reference/account/public-api.v1.account.api_keys.list): List the API keys of the authenticated company with cursor-based pagination. Each key exposes its `prefix`, `scopes`, `tier`, `environment` (`live`/`test`) and lifecycle timestamps. The plaintext secret is never returned — it is shown once, at creation or rotation. - [Retrieve account billing details](https://docs.factuarea.com/api-reference/account/public-api.v1.account.billing): Returns the subscription billing snapshot of the authenticated company: base plan subscription (status, trial, current period end, pending plan change), gestoría seats subscription (quantity, active managed companies, per-seat cost with VAT, recurring total, next invoice) and default payment method. Managed companies (plan `gestionada`) receive `managed: true` without the master's billing data. Amounts are integer cents; unresolved amounts are `null`, never a misleading 0. - [Retrieve account details](https://docs.factuarea.com/api-reference/account/public-api.v1.account.show): Stripe-like account endpoint: returns the authenticated company together with its plan, add-ons, and the metadata of the API key in use (environment, scopes). Use it to introspect what the current key can do. - [Retrieve an API key](https://docs.factuarea.com/api-reference/account/public-api.v1.account.api_keys.show): Retrieve a single API key of the authenticated company by its `id` (UUID v7). The plaintext secret is never included. A key belonging to another company returns 404 `api_key_not_found` (anti-enumeration). - [Revoke an API key](https://docs.factuarea.com/api-reference/account/public-api.v1.account.api_keys.revoke): Revoke an API key immediately and irreversibly. Subsequent requests authenticated with that key fail with 401. You may revoke the key currently in use — doing so cuts off your own access. Revoking a key of another company returns 404 `api_key_not_found`. - [Rotate an API key secret](https://docs.factuarea.com/api-reference/account/public-api.v1.account.api_keys.rotate_secret): Invalidate the current secret of an API key immediately, generate a fresh `prefix` + `secret`, and return the new secret in plaintext exactly once. Any request made with the previous secret stops authenticating right away. Irreversible. - [Update account personalization](https://docs.factuarea.com/api-reference/account/public-api.v1.account.personalization.update): 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. - [Verify account against the AEAT census](https://docs.factuarea.com/api-reference/account/public-api.v1.account.verify_census): Check the persisted company name + tax ID pair against the AEAT census (VNifV2) to anticipate VeriFactu 4104 rejections. No request body: the endpoint always verifies the account's persisted fiscal data. Fail-open — if AEAT is unreachable the call returns 200 with `status: unavailable`. Test keys (`fact_test_`) return deterministic statuses per magic NIF without contacting AEAT. ## API Reference — Contacts - [Bulk create clients](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.bulk_create): Create up to 500 clients in one call, each entry a full client payload. With `dry_run=true` it validates every row without persisting and returns a per-row classification (`results[]`, including duplicate `external_id`/`tax_id` and a non-blocking AEAT census warning); with `dry_run=false` it creates only the valid rows and reports the rest in `failures[]`. Returns the `BulkCreateResult` shape. - [Create a client](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.create): Create a new client (customer) for your company. The returned object includes the generated `uuid` you should store for subsequent operations. - [Delete a client](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.delete): Delete a client. Returns 422 if the client is referenced by any document (invoice, quote, etc.). - [Delete multiple clients in bulk](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.bulk_delete): Delete up to 200 clients in one request. Returns a `BulkPartialSuccessResult` with `total`, `successful` and `failed` counts plus a `failures` list (`id` + `error_code` + Spanish `error_message`); clients with associated documents are reported in `failures`. - [Download the client import template](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.import_template): Download the CSV template (Spanish headers + two example rows) to fill in before uploading it to `POST /v1/clients/import`. The content is static and accesses no company data. Returns a `text/csv` stream as an attachment. - [Find a client by external ID](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.find_by_external_id): Look up a client 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/e-commerce). Distinct from the fiscal `tax_id`. Returns the matching client or 404 if no client uses that external_id within your company. - [Find a client by tax ID](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.find_by_tax_id): Look up a client by their Spanish tax identifier (NIF/CIF/NIE). Returns the matching client or 404 if no client uses that tax_id within your company. - [Get client stats](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.stats): Aggregated KPIs for the authenticated company: total client count, active count, count with sales invoices, count with quotes, and totals by document type. Returned as `{ "data": ClientStats }`. - [Import clients from a file](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.import): Import clients in bulk from a CSV/XLSX file as `multipart/form-data`; processing is synchronous and the response carries the per-row outcome. Upload with `dry_run=true` first to validate without persisting, fix the reported `failures[]`, then re-upload with `dry_run=false` to create only the valid rows. `mapping` maps your column headers to the target fields (`name` and `tax_id` are mandatory). Download the header template from `GET /v1/clients/import-template`. ```json { "dry_run": true, "mapping": { "Nombre": "name", "CIF": "tax_id", "Email": "email" } } ``` Limits: file ≤10 MB and under 200 rows; a larger file returns 422 `client_import_too_large`. - [List all clients](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.list): List your clients with cursor-based pagination. Supports filtering by `is_active`, `created_at[gte|lte]`, and `name[in]`. - [List client activity timeline](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.activities): Return the audit timeline for a client combining its own domain events plus invoice, quote, delivery note, proforma and purchase invoice events that reference it. Paginated with page and per_page query params (default 50). - [Retrieve a client](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.show): Retrieve a client by its `uuid`. Returns 404 if the client does not exist or belongs to another company. - [Search clients](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.search): Search clients by free-text query against `name`, `tax_id`, `vat_id`, `email`, and `phone`. Returns a flat array (no pagination) capped at 50 results. - [Update a client](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.update): Update a client. Only fields included in the payload are modified; omitted fields retain their previous values. - [Verify a client against the AEAT census](https://docs.factuarea.com/api-reference/clients/public-api.v1.clients.verify_census): Check a third-party name + tax ID pair (the recipient of an invoice) against the AEAT census (VNifV2) to anticipate VeriFactu 1239 rejections before invoicing. Stateless and informational: nothing is persisted on the client. Fail-open — if AEAT is unreachable the call returns 200 with `status: unavailable`. Test keys (`fact_test_`) return deterministic statuses per magic NIF without contacting AEAT. - [Bulk change supplier active state](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.bulk_status): Move up to 50 suppliers (by id) to the target `new_status` (`active` or `inactive`). Idempotent with respect to the target: a supplier already in the requested state counts as `successful` without flipping. Returns a `BulkPartialSuccessResult`; suppliers not found come back in `failures[]`. - [Create a supplier](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.create): Create a new supplier (vendor) for your company. The returned object includes the generated `uuid`. - [Delete a supplier](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.delete): Delete a supplier. Returns 422 if the supplier is referenced by any purchase invoice. - [Delete multiple suppliers in bulk](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.bulk_delete): Delete up to 200 suppliers in one request. Returns a `BulkPartialSuccessResult` with `total`, `successful` and `failed` counts plus a `failures` list (`id` + `error_code` + Spanish `error_message`); suppliers with associated contracts are reported in `failures`. UUIDs from other tenants are ignored. - [Find a supplier by external ID](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.find_by_external_id): Look up a supplier by its `external_id` (sent in the JSON body), the persistent integration key that maps it to a record in a third-party system (ERP/CRM). Distinct from the fiscal `tax_id` and from the request-level `Idempotency-Key`. Returns the matching supplier or 404 if no supplier uses that external_id within your company. - [Find a supplier by tax ID](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.find_by_tax_id): Look up a supplier by its Spanish tax identifier (NIF/CIF/NIE/VAT). Returns the matching supplier or 404 if no supplier uses that tax_id within your company. - [Get supplier stats](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.stats): Aggregated KPIs for the authenticated company: total supplier count, active count, count with contracts, and amount totals by status. Returned as `{ "data": SupplierStats }`. - [List all suppliers](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.list): List your suppliers with cursor-based pagination. Supports filtering by `is_active`, `created_at[gte|lte]`. - [List supplier activity timeline](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.activities): Return the audit timeline for a supplier combining its own domain events plus purchase invoice and contract events that reference it. Paginated with page and per_page query params (default 50). - [Retrieve a supplier](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.show): Retrieve a supplier by its `uuid`. - [Search suppliers](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.search): Search suppliers by free-text query against `name`, `tax_id`, `vat_id`, `email`, and `phone`. Capped at 50 results. - [Toggle supplier active state](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.toggle_active): Flip a supplier between active and inactive. Inactive suppliers are hidden from line-item selectors on new purchase invoices. - [Update a supplier](https://docs.factuarea.com/api-reference/suppliers/public-api.v1.suppliers.update): Update a supplier. Only fields present in the payload are modified. ## API Reference — Catalog - [Bulk change product active state](https://docs.factuarea.com/api-reference/products/public-api.v1.products.bulk_status): 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[]`. - [Create a product](https://docs.factuarea.com/api-reference/products/public-api.v1.products.create): Create a new product in your catalog. - [Delete a product](https://docs.factuarea.com/api-reference/products/public-api.v1.products.delete): Delete a product. Returns 422 if the product is referenced by any document line. - [Delete multiple products in bulk](https://docs.factuarea.com/api-reference/products/public-api.v1.products.bulk_delete): 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 are reported in `failures`. Decrements the plan usage counter accordingly. - [Download a product gallery image binary](https://docs.factuarea.com/api-reference/products/public-api.v1.products.gallery.download): 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. - [Download the product video binary](https://docs.factuarea.com/api-reference/products/public-api.v1.products.video.download): Stream the raw binary of the product video. Returns 404 if the product has no video or the file is not on disk. - [Find a product by external ID](https://docs.factuarea.com/api-reference/products/public-api.v1.products.find_by_external_id): 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. - [Find a product by SKU](https://docs.factuarea.com/api-reference/products/public-api.v1.products.find_by_sku): 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. - [Get product sales analytics](https://docs.factuarea.com/api-reference/products/public-api.v1.products.sales_analytics): 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. - [Get product stats](https://docs.factuarea.com/api-reference/products/public-api.v1.products.stats): 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 }`. - [List all products](https://docs.factuarea.com/api-reference/products/public-api.v1.products.list): List products in your catalog with cursor-based pagination. - [List product activity timeline](https://docs.factuarea.com/api-reference/products/public-api.v1.products.activities): 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). - [List products below the stock threshold](https://docs.factuarea.com/api-reference/products/public-api.v1.products.low_stock_report): Return products whose current stock is below their configured low-stock threshold. Useful for inventory alerts. - [Remove a gallery image from a product](https://docs.factuarea.com/api-reference/products/public-api.v1.products.gallery.delete): Delete a gallery image by its 0-based index. Remaining images shift positions to fill the gap. - [Remove the product video](https://docs.factuarea.com/api-reference/products/public-api.v1.products.video.delete): Delete the video associated with the product and release the storage. Idempotent: returns 204 even when no video was attached. - [Retrieve a product](https://docs.factuarea.com/api-reference/products/public-api.v1.products.show): Retrieve a product by its `uuid`. - [Search products](https://docs.factuarea.com/api-reference/products/public-api.v1.products.search): Search products by free-text query against `name` and `sku`. Capped at 50 results. - [Toggle product active state](https://docs.factuarea.com/api-reference/products/public-api.v1.products.toggle_active): Flip a product between active and inactive. Inactive products are hidden from line-item selectors on new documents. - [Update a product](https://docs.factuarea.com/api-reference/products/public-api.v1.products.update): Update a product in your catalog. - [Update product stock](https://docs.factuarea.com/api-reference/products/public-api.v1.products.update_stock): 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. - [Update stock for many products](https://docs.factuarea.com/api-reference/products/public-api.v1.products.bulk_update_stock): Apply a stock operation to multiple products in one request (up to 500). UUIDs that do not belong to your company are ignored silently. - [Upload a gallery image to a product](https://docs.factuarea.com/api-reference/products/public-api.v1.products.gallery.upload): 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. - [Upload a video to a product](https://docs.factuarea.com/api-reference/products/public-api.v1.products.video.upload): Attach a video file (mp4, mov, avi or webm; up to 50 MB) to the product. Replaces any existing video. - [Calculate a tax over a base amount](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.calculate): Apply the referenced tax to a base amount and return the breakdown: base, tax_rate, tax_amount, total_amount and the full tax object. - [Calculate totals for a set of lines](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.calculate_totals): 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. - [Check whether a tax is in use](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.is_in_use): Return whether the tax is referenced by existing documents. Useful for safe-deletion checks before calling DELETE. - [Create a tax](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.create): Register a new tax with name, unique code, type (vat, retention, surcharge or other), rate and scope (sale, purchase or both). The ISO-2 country code is required. - [Delete a tax](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.delete): Delete a tax. Fails with 409 if the tax is referenced by existing documents. System taxes (is_system=true) cannot be deleted. - [Get default taxes for a document type](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.defaults): 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. - [Get tax stats](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.stats): 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 }`. - [List active taxes](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.active): Return the active taxes available to your company, combining system-wide defaults plus company-specific definitions. - [List all taxes](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.list): List the tax rates available to your company (Spanish IVA, IRPF, recargo, etc.). - [List taxes applicable to purchases](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.for_purchases): Return the taxes available for purchase documents (supplier invoices). - [List taxes applicable to sales](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.for_sales): Return the taxes available for sales documents (invoices, quotes, proformas, delivery notes). - [List taxes filtered by type](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.by_type): Return taxes filtered by category via the type query param (vat, retention, surcharge, other). Defaults to vat when omitted. - [Mark a tax as the default for its type](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.set_default): Promote a tax to the system-wide default for its category (vat, retention or surcharge). If another tax was the default for the same type it is demoted automatically. - [Retrieve a tax](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.show): Retrieve a tax rate by its `uuid`. - [Retrieve the tax catalog](https://docs.factuarea.com/api-reference/taxes/public-api.v1.tax-catalog.show): Return, in a single document, the Spanish tax knowledge you need to build a compliant invoicing form: indirect tax regimes (IVA, IGIC, IPSI) with their legal rates and their VeriFactu L1 code, header-level operation regimes with the legal wording each one requires, exemption causes with their AEAT code, legal wording and article of the Spanish VAT Act, the system IRPF withholding rates and the closed matrix of legal VAT/equivalence-surcharge pairs. It replaces the hardcoded table every integration ends up maintaining by hand. The catalog carries no data of the authenticated company: two different companies receive byte-identical bodies for the same language, and `retention_rates` never includes the custom taxes a company creates through `POST /v1/taxes`. Withholding rates are published in POSITIVE, so apply them as a deduction from the taxable base. This is the catalog of what the platform supports, NOT an exhaustive normative list of every regime, exemption or withholding rate Spanish law defines. Use it to know what you can send to this API; do not read it as tax advice or as a substitute for the legislation. Every entry carries its `label` (and, in the two normative blocks, its `description`) in Spanish, English and Catalan at once. `Accept-Language` only picks the language reported in `primary_language`; it never filters the payload, so one cached document is enough to render a multilingual selector. The response is cacheable: it ships `ETag` and a public `Cache-Control`, and sending the validator back in `If-None-Match` returns 304 with no body. Two languages produce two different `ETag`s, because the negotiated language travels inside the body. - [Set tax default for a document type](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.set_default_for_document): Assign a tax as the default for a specific document type (invoice, quote, proforma, delivery_note, purchase_invoice, recurring_invoice). - [Toggle tax active state](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.toggle): Flip a tax between active and inactive. Inactive taxes are hidden from selectors but stay available for already-issued documents. - [Update a tax](https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.update): Partial update of a tax: name, code, rate, applies_to, country and description. System taxes (is_system=true) are not editable. - [Archive a series](https://docs.factuarea.com/api-reference/series/public-api.v1.series.archive): Archive a series so it stops appearing as available for new documents. Fails with 409 if the series is the default and the only active series of its type. Returns 204 on success. - [Bootstrap the default series of a company](https://docs.factuarea.com/api-reference/series/public-api.v1.series.bootstrap): Leave a company able to issue documents in one call: for every document type of the public surface (`invoice`, `quote`, `delivery_note`, `proforma`) that has no active series, create its default series with the canonical code and name. No request body. **What comes back** - One entry per document type, with a `status` of `created`, `existing` or `no_default`. - `no_default` means the type has active series but none marked as default — archiving the default demotes it without promoting a replacement — and the company still cannot issue that document. - Treat `no_default` as work still to do, not as success: the active series arrive in `candidates` and you resolve it with `POST /v1/series/{id}/default`. **Why it does not choose for you** Picking which series numbers a company's documents has registry consequences only you can decide, so the bootstrap never promotes one for you. **Calling it twice** - Idempotent by business rule: a second call creates nothing, fails nothing and reports the state again. - INDEPENDENT of the `Idempotency-Key` header: with the header, a repeated key replays the original body — `created` entries included — instead of reporting the current state. - [Create a series](https://docs.factuarea.com/api-reference/series/public-api.v1.series.create): Create a document numbering series. Optional `number_format` sets the numbering mask (e.g. `{code}-{YYYY}-{00000}`) and `initial_number` (≥1) starts the counter to continue an existing numbering. The same code may be reused across document types (multi-series). A series is immutable once created per AEAT (`PUT` returns 405), so these can only be set here. - [Find a series by code](https://docs.factuarea.com/api-reference/series/public-api.v1.series.find_by_code): Look up a series by its `code` (JSON body, case-insensitive). A `code` is not unique across document types (multi-series), so pass `document_type` to resolve the exact `(code, document_type)` series. If you omit it the code is matched across all types: a single match is returned, but an ambiguous code returns 422 `document_type_required_for_ambiguous_code` rather than silently picking one. Returns 404 if none exists. - [Get series stats](https://docs.factuarea.com/api-reference/series/public-api.v1.series.stats): Aggregated KPIs for your document numbering series: total series count, active and archived counts, and a breakdown by document type. Returned as `{ "data": SeriesStats }`. - [Get the default series for a document type](https://docs.factuarea.com/api-reference/series/public-api.v1.series.default): Return the default numbering series for the given document type (invoice, quote, proforma, delivery_note). Returns 404 when no default is configured. - [List active series by document type](https://docs.factuarea.com/api-reference/series/public-api.v1.series.active): Return all non-archived series for the given document type within your company. - [List all series](https://docs.factuarea.com/api-reference/series/public-api.v1.series.list): List your document numbering series with cursor-based pagination. - [List series activity timeline](https://docs.factuarea.com/api-reference/series/public-api.v1.series.activities): 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). - [Mark a series as default for its type](https://docs.factuarea.com/api-reference/series/public-api.v1.series.set_default): 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. - [Retrieve a series](https://docs.factuarea.com/api-reference/series/public-api.v1.series.show): Retrieve a series by its `uuid`. Series are **immutable** for fiscal compliance (AEAT VeriFactu — legal numbering continuity): `PUT`, `PATCH` and `DELETE` on `/v1/series/{uuid}` return `405 Method Not Allowed` with `error.code = "series_immutable"` and header `Allow: GET, POST`. To "delete" a series use `POST /v1/series/{uuid}/archive`; to change the numbering, create a new series and mark it as default. - [Unarchive a series](https://docs.factuarea.com/api-reference/series/public-api.v1.series.unarchive): Return an archived series back to the active pool. Does not change the current default of its type. Returns 204 on success. ## API Reference — Sales documents - [Annul an invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.annul): Withdraw an issued invoice **with a documented reason**. `reason` is required here (3–500 characters); that is the only difference from `POST /v1/invoices/{id}/void`, which performs exactly the same operation and persists a placeholder when you omit it. Prefer this endpoint whenever the reason has to be traceable — the text you send is kept in the invoice audit trail and, when the company is enrolled in VeriFactu, becomes the `motivo` of the AEAT cancellation record. The invoice moves to `annulled` and `voided_at` starts reporting when that happened. The status is terminal and the operation is **irreversible**: there is no transition back to `sent` or `draft`, and the correlative number of the series is neither released nor reused. **Effect on AEAT.** With VeriFactu enabled, annulling queues an *anulación* record to AEAT **asynchronously**: a `200` means the invoice is annulled in Factuarea, not that AEAT has already processed it — poll the invoice for its VeriFactu status. The original *alta* record is not deleted or rewritten; AEAT keeps both entries, the issuance and its cancellation. With VeriFactu inactive the annulment is purely internal and nothing is transmitted. **Annul or correct?** Annulment withdraws the whole document and only works before payment; it produces no amending document, so it never restates an amount. A corrective (`POST /v1/invoices/{id}/corrective`) creates a **new** invoice that amends the original and is the only path for an invoice that is already `paid` or that is only partly wrong. Limits: only `sent` or `overdue` can be annulled. A `draft` is not annulled but deleted; `paid`, `cancelled` and `annulled` return 422. An invoice that **is** a corrective can never be annulled — issue a new corrective of the original instead. Use `GET /v1/invoices/{id}/can-annul` to check eligibility, and whether a VeriFactu cancellation record will be created, before posting here. - [Assign a real invoice number](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.assign_real_number): Promotes a draft to a definitive invoice by assigning its real series number. In VeriFactu-enabled companies the same happens automatically on send. - [Bulk change invoice status](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.bulk_status): Transition several invoices to a new status in one call, each through the same Aggregate guard, with partial success (a rejected id never aborts the batch). `new_status` is `sent` or `paid`; when `paid`, `payment_date` is required and propagated as the real payment date of every invoice (never `now()`). Returns a `BulkPartialSuccessResult` with `total`, `successful`, `failed` and a per-id `failures` list (`resource_not_found` or `invalid_status_transition`). ```json { "ids": ["0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f60"], "new_status": "paid", "payment_date": "2026-06-30" } ``` Limits: `ids` accepts 1–50 entries; `payment_date` is required when `new_status` is `paid` and must not be in the future. - [Bulk create invoices](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.bulk_create): Create up to 100 invoices in one call, each entry a full invoice payload. With `dry_run=true` it validates every row without persisting and returns a per-row classification (`results[]`, including duplicate `external_id` and a non-blocking AEAT census warning); with `dry_run=false` it creates only the valid rows and reports the rest in `failures[]`. Returns the `BulkCreateResult` shape. - [Bulk delete invoices](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.bulk_delete): Delete several invoices in one call with partial success — each id is evaluated independently and one failure never aborts the batch. Only draft invoices are deleted; an issued invoice comes back as a `resource_not_deletable` failure (use `void` instead). Returns a `BulkPartialSuccessResult` with `total`, `successful`, `failed` and a per-id `failures` list. ```json { "ids": ["0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f60", "0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f61"] } ``` Limits: `ids` accepts 1–100 UUID v7 entries per call. - [Bulk download invoice PDFs](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.bulk_pdf): 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. - [Bulk send invoices](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.bulk_send): 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). - [Check annulment eligibility](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.can_annul): Validates whether the invoice can be annulled and whether a VeriFactu anulacion record will be created. Call before posting to /annul. - [Check simplified invoice eligibility](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.simplified_eligibility): Determines if an invoice may be issued as simplified (F2) under Real Decreto 1619/2012 art. 4 based on amount and counterparty data. - [Create a recurring invoice from an invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.create_recurring): 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. - [Create an invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.create): Create a sales invoice. It is created in `draft` by default; pass `options.issue_directly: true` to issue it immediately (assigning the correlative number and freezing the document per AEAT), or issue it later. VeriFactu *alta* is transmitted to AEAT asynchronously — a `201` does not mean AEAT has accepted the invoice yet, so poll it for the AEAT status. ```json { "client_id": "0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f60", "lines": [{ "description": "Consulting", "quantity": 1, "unit_price": 1000, "tax_rate": 21 }], "options": { "issue_directly": true } } ``` Limits: at least one line is required; send an `Idempotency-Key` (≤255 chars, remembered 24 h) for safe retries; a duplicate `external_id` upserts the existing invoice instead of creating a new one. - [Delete an invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.delete): Delete a draft invoice. Issued invoices cannot be deleted (use `void` instead). - [Download invoice PDF](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.pdf): Download the PDF representation of an invoice. Returns the binary PDF stream (`application/pdf`). - [Download payment receipt PDF](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.payment_receipt): Streams the PDF receipt of a paid invoice. Returns 422 if the invoice is not in `paid` status. - [Duplicate an invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.duplicate): Create a new draft invoice by copying the lines, client, and metadata from an existing invoice. The new invoice gets a fresh `uuid` and number. - [Email quarterly ZIP to accountant](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.quarterly.send_email): Generates the quarterly ZIP and emails it to the recipient, typically the tax accountant. - [Export invoices to a spreadsheet](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.export_excel): Export a selection of invoices to a spreadsheet (`xlsx` or `csv`) and stream it back as an attachment. Narrow it with the filters (`invoice_ids[]`, `client_id`, `series_id`, `status`, `date_from`, `date_to`, `search`) or omit them to export everything. `format` picks the layout: `SUMMARY` (one row per invoice) or `ITEMS` (one row per line). ```http GET /v1/invoices/export?format=SUMMARY&status=paid&date_from=2026-01-01&date_to=2026-03-31 ``` Limits: the selection is capped at 5,000 invoices; a wider one returns 422 `export_limit_exceeded`. - [Find an invoice by external ID](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.find_by_external_id): 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 `uuid`. Returns the matching invoice or 404 `invoice_not_found` if no invoice uses that external_id within your company. - [Find an invoice by number](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.find_by_number): Looks up a single invoice by its number, with optional `year` to disambiguate across fiscal years. Returns 404 if not found and 422 if the number is ambiguous and no `year` is supplied. - [Generate corrective invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.corrective): Issue a corrective invoice (*rectificativa*, RD 1619/2012 art. 15) that amends a previously issued invoice. Returns `201` with the **new** invoice: `is_corrective: true`, `corrective` pointing at the original, and a number derived from the original's in the same series (`F-2026-0042-REC1`, `-REC2`… for successive correctives). Flow: the original must already be issued (`sent` or `paid`) → the corrective is born **already issued**, never as a draft → when VeriFactu is enabled its *alta* is transmitted to AEAT **asynchronously**, so a `201` does not mean AEAT has accepted it yet. The original is never modified: it keeps its number, its status and its own VeriFactu record. A corrective is an additional document, not an edit. **Full vs partial.** `correction_type: full` is a substitution (VeriFactu nature `S`): the `lines` you send are the *final correct amounts*, and omitting `lines` entirely turns it into a full cancellation, where every original line is copied back negated and prefixed `[ANULACION]`. `correction_type: partial` is a correction by differences (nature `I`): `lines` is required and each one is a delta — typically negative — prefixed `[AJUSTE]`. In a partial correction a line only moves stock if it declares its own `product_id`; in a substitution the product is inherited from the original line at the same index. **AEAT R code.** By default it is derived from `correction_reason`: `error_fundado` → R1, `concurso` → R2, `incobrable` → R3, everything else → R4; a corrective of a simplified (F2) invoice is always born R5 regardless of the reason. `correction_code` overrides that derivation, but is validated against the legal matrix — original F2 → only `R5`; original F1/F3 → only `R1`–`R4`. Any other combination returns 422 with the legal `allowed_values`. Limits: `draft`, `overdue`, `cancelled` and `annulled` originals return 422 (an `overdue` invoice must be paid or voided first); a corrective can never itself be corrected — issue a new corrective of the original instead. List every corrective of an invoice with `GET /v1/invoices/{id}/correctives`. - [Generate quarterly ZIP archive](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.quarterly.download_zip): Builds a ZIP with all invoice PDFs of the given quarter. Returns ZIP metadata (path, processed counts, errors). - [Generate temporary PDF link](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.pdf_link): Returns a temporary URL to the invoice PDF instead of streaming the bytes. Convenient for embedding in emails or messaging apps. Dual contract: 200 with the URL when the PDF is already materialized; 202 with `status: pendiente` when generation was enqueued (the PDF renders on the `pdf` queue) — retry until you get the 200. - [Get invoice statistics](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.stats): 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). - [List all invoices](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.list): List your sales invoices with cursor-based pagination. Supports filtering by `status[in]`, `client_id`, `series_id`, `issued_on[gte|lte]`, and `total[gte|lte]`. - [List corrective invoices](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.correctives): Returns all corrective invoices associated with the original invoice. Used to reconstruct the original → rectificativa tree. - [List invoice activity](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.activities): Returns the cursor-paginated activity timeline (audit log) of a single invoice: status transitions, emails, reminders, and metadata changes. - [List invoice payments](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.payments_list): List the payments registered against an invoice, ordered by payment date. Returns an empty array when no payments have been registered yet. - [List invoice statuses](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.statuses): 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. - [List payment methods](https://docs.factuarea.com/api-reference/invoices/public-api.v1.payment_methods.list): 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. - [List quarters with invoices](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.quarterly.available): Returns the quarters that have at least one invoice, with breakdown by invoice type (F1/F2/F3/R5). Useful to populate "quarter to export" selectors. - [Mark an invoice as sent](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.mark_sent): Transitions a draft invoice to `sent` without dispatching email. Useful when the document was delivered through an external channel. - [Mark invoice as paid](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.mark_paid): 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`. - [Preview a payment reminder email](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.reminder_preview): Renders the HTML, subject, and resolved recipients of the reminder email without sending it. Same override fields as send-reminder. - [Preview an invoice draft PDF](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.pdf_preview): 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. - [Register a payment](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.payments_create): Register a partial (or full) payment against an invoice. The invoice transitions to `partially_paid` while the cumulative paid amount is below the total, and to `paid` once it reaches it. Returns 422 if the invoice is in a status that does not accept payments. - [Reschedule an invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.reschedule): Move the issuance date of an already scheduled invoice. The invoice **stays `scheduled` throughout** — unlike `unschedule` followed by `schedule`, it never returns to `draft`, so it is never editable or deletable in between and there is no window in which the sweep could find it unscheduled. **What you can change:** `scheduled_for`, and only that. `scheduled_action` is preserved — a schedule created as `issue_and_send` still emails the client at the new date, and one created as `draft` still does not. To change the action you have to `unschedule` and `schedule` again. The content of the invoice (lines, client, series, totals) is untouched by this call: use `PATCH /v1/invoices/{id}` while it is still a draft for that. Limits: only an invoice in `scheduled` can be rescheduled — a `draft` (never scheduled) or an already issued invoice returns 422 — and the new `scheduled_for` must be strictly in the future (422 otherwise). Everything documented under `schedule` about what happens when the date arrives (number assigned at that moment, snapshots frozen, asynchronous VeriFactu *alta*, email only with `issue_and_send`, per-invoice retry on failure) applies unchanged to the new date. - [Retrieve an invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.show): Retrieve a sales invoice by its `uuid`. - [Retrieve invoice public link](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.public_link_get): Returns the shareable public URL of the invoice (/d/{uuid}) along with its status, expiration, and the plan-allowed maximum extension days. - [Schedule an invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.schedule): Reserve the issuance of a draft invoice for a future instant. The invoice moves to `scheduled` and **nothing fiscal happens yet**: it keeps its `BORRADOR` placeholder number, no series counter is consumed and nothing is registered with VeriFactu. Scheduling never burns numbering. **What happens at `scheduled_for`.** A sweep runs every minute and, on the first pass at or after that instant, it: (1) assigns the definitive correlative number of the series **at that moment**, not when you scheduled — so a document scheduled today and issued next month takes the number that corresponds to next month; (2) freezes the recipient and issuer snapshots as of that instant, which is what the PDF and the fiscal XML will show; (3) moves the invoice to `sent`; (4) queues the VeriFactu *alta* to AEAT **asynchronously** when the company is enrolled; and (5) emails the client **only** when `scheduled_action` is `issue_and_send` and the client has an email on file — with `scheduled_action: draft` the invoice is issued but never delivered, and `issue_and_send` without a recipient email still issues it, silently skipping the delivery. **Time zone.** `scheduled_for` is an ISO 8601 date-time. If it carries an explicit offset (`2027-01-15T09:00:00Z`, `…+01:00`) that offset is honoured; without one it is read in the account's server time zone, `Europe/Madrid`. Resolution is minute-level: expect issuance within about a minute of the instant you asked for, never before it. **If the scheduled issuance fails**, each invoice is isolated in its own transaction: the failing one stays `scheduled` with its date in the past, the error is logged, the rest of the batch is unaffected and the next sweep retries it. A successful issuance is never repeated, because `scheduled → sent` can only happen once. Limits: only a `draft` can be scheduled (any other status returns 422) and `scheduled_for` must be strictly in the future (422 otherwise). While it is still `scheduled` you can call `unschedule` to return it to `draft`, or `reschedule` to move only the date. - [Send a payment reminder](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.send_reminder): Emails a payment reminder to the customer for this invoice. Accepts optional `email`, `subject`, `message`, `cc`, `bcc` overrides. - [Send invoice by email](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.send): Send an invoice to the client by email. Uses the email on file unless overridden in the payload. - [Substitute simplified invoices with full invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.substitute_simplified): Groups N simplified invoices (F2) under a single substitutive full invoice (F3) with complete recipient data. Marks the originals as substituted. - [Unschedule an invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.unschedule): Cancel a scheduled issuance. The invoice returns to `draft`, `scheduled_for` and `scheduled_action` are set back to `null`, and it becomes editable and deletable again as any other draft. Unscheduling leaves **no fiscal trace**, because nothing fiscal had happened yet: no correlative number of the series was consumed (the invoice still carries its `BORRADOR` placeholder), nothing was registered with VeriFactu and no email was sent. This is not an annulment and it does not appear in any AEAT record. **Window of use.** It only applies while the invoice is `scheduled`. A `draft` that was never scheduled returns 422, and so does an invoice the sweep has already issued: from that instant on it is `sent`, it owns a definitive number and — where VeriFactu applies — an AEAT record, so the way back is no longer `unschedule` but `void`/`annul` to withdraw it (only while it is unpaid) or `corrective` to amend it. In practice the race is real: an invoice whose `scheduled_for` has just elapsed may already have been issued when your call lands. If you only want to move the date, use `PATCH /v1/invoices/{id}/reschedule` instead — it avoids the round trip through `draft` and the window in which the document is editable. - [Unsend an invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.unsend): Clear the delivery marker (`sent_at`) of a `sent` invoice while keeping its `sent` status. The correlative number and VeriFactu record stay intact — the invoice is not reverted to draft and remains immutable per AEAT. Use it to undo an accidental mark-as-sent. Idempotent: a no-op when `sent_at` is already null. - [Update an invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.update): Update a draft invoice. Once an invoice has been issued (status `issued`), most fields become immutable per AEAT compliance. - [Update invoice public link](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.public_link_update): Applies an action to the public link: `revoke`, `activate`, `extend` (with `extend_days`), or `reset` to the plan default. - [Void an invoice](https://docs.factuarea.com/api-reference/invoices/public-api.v1.invoices.void): Withdraw an issued invoice. The invoice moves to `annulled`, `voided_at` starts reporting when that happened and the status is terminal: voiding is **irreversible** and there is no way back to `sent` or `draft`. **Void or correct?** Void when the whole document should never have existed and has not been paid — the invoice is withdrawn as a whole and no amending document is produced. Issue a corrective (`POST /v1/invoices/{id}/corrective`) when the invoice was already paid, or when only part of it is wrong (amount, recipient, partial return): a `paid` invoice can never be voided, and voiding never fixes a figure. What voiding does **not** do: the correlative number of the series is neither released nor reused (the series counter only moves forward), the original invoice is not deleted, and its VeriFactu *alta* record is not withdrawn. When the company is enrolled in VeriFactu, an AEAT cancellation (*anulación*) record is queued **asynchronously** with your `reason` as its `motivo` — a `200` means the invoice is annulled on our side, not that AEAT has already processed the cancellation. With VeriFactu inactive the annulment is purely internal. Limits: only an invoice in `sent` or `overdue` can be voided. A `draft` is not voidable (delete it instead), and `paid`, `cancelled` and `annulled` return 422. An invoice that **is** a corrective can never be voided — to undo a wrong corrective, issue a new corrective of the original. Note the inverse is allowed: having correctives does not block voiding the original. Call `GET /v1/invoices/{id}/can-annul` first if you need to check eligibility without attempting the change. `reason` is optional here and a placeholder is persisted when you omit it. `POST /v1/invoices/{id}/annul` is the very same operation with `reason` required — prefer it whenever the reason must be documented. - [Accept a quote](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.accept): Mark a quote as accepted by the client. Sets `accepted_at` to the current timestamp. - [Bulk change quote status](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.bulk_status): 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[]`. - [Bulk delete quotes](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.bulk_delete): 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. - [Bulk download quote PDFs](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.bulk_pdf): 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. - [Bulk send quotes](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.bulk_send): 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). - [Convert quote to invoice](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.convert): Convert an accepted quote into a sales invoice. The new invoice references the source quote via metadata; the quote moves to status `converted`. - [Create a quote](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.create): Create a new sales quote in `draft` status. Quotes can later be converted to invoices via `POST /quotes/{quote}/convert`. - [Delete a quote](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.delete): Delete a quote. Returns 422 if the quote has been converted to an invoice. - [Download quote PDF](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.pdf): Download the PDF representation of a quote. - [Duplicate a quote](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.duplicate): Create a new draft quote by copying the lines, client, and metadata from an existing quote. - [Find a quote by external ID](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.find_by_external_id): 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. - [Get quote stats](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.stats): Aggregated KPIs for the authenticated company: total quote count and amount, count per status, expired count, and converted count. Returned as `{ "data": QuoteStats }`. - [List all quotes](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.list): List your sales quotes with cursor-based pagination. Supports filtering by `status[in]`, `client_id`, `issued_on[gte|lte]`. - [List quote statuses](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.statuses): 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. - [Reject a quote](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.reject): Mark a quote as rejected by the client. Sets `rejected_at` to the current timestamp. - [Retrieve a quote](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.show): Retrieve a sales quote by its `uuid`. - [Retrieve quote public link](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.public_link_get): Returns the shareable public URL of the quote (/d/{uuid}) along with its status, expiration, and the plan-allowed maximum extension days. - [Send quote by email](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.send): Send a quote to the client by email. - [Update a quote](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.update): Update a draft quote. Once accepted/rejected/converted, the quote becomes immutable. - [Update quote public link](https://docs.factuarea.com/api-reference/quotes/public-api.v1.quotes.public_link_update): Applies an action to the public link: `revoke`, `activate`, `extend` (with `extend_days`), or `reset` to the plan default. - [Accept a proforma](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.accept): Mark a proforma as accepted by the client. Returns 422 if the proforma is in a status that cannot transition to `accepted`. - [Bulk change proforma status](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.bulk_status): 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[]`. - [Bulk delete proformas](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.bulk_delete): 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. - [Bulk download proforma PDFs](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.bulk_pdf): 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. - [Bulk send proformas](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.bulk_send): 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). - [Convert proforma to invoice](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.convert): Convert a proforma into a final sales invoice. The new invoice references the source proforma; the proforma moves to status `converted`. - [Create a proforma](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.create): Create a new proforma invoice in `draft` status. Proformas can later be converted to final invoices. - [Delete a proforma](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.delete): Delete a proforma. Returns 422 if the proforma has been converted to an invoice. - [Download proforma PDF](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.pdf): Download the PDF representation of a proforma. - [Duplicate a proforma](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.duplicate): Create a new draft proforma by copying lines, client, and metadata from an existing proforma. - [Find a proforma by external ID](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.find_by_external_id): 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. - [Get proforma stats](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.stats): 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 }`. - [List all proformas](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.list): List your proforma invoices with cursor-based pagination. - [List proforma statuses](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.statuses): 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. - [Reject a proforma](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.reject): Mark a proforma as rejected by the client. Returns 422 if the proforma is in a status that cannot transition to `rejected`. - [Retrieve a proforma](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.show): Retrieve a proforma invoice by its `uuid`. - [Retrieve proforma public link](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.public_link_get): Returns the shareable public URL of the proforma (/d/{uuid}) along with its status, expiration, and the plan-allowed maximum extension days. - [Send proforma by email](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.send): Send a proforma to the client by email. - [Update a proforma](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.update): Update a draft proforma. Once converted, the proforma becomes immutable. - [Update proforma public link](https://docs.factuarea.com/api-reference/proformas/public-api.v1.proformas.public_link_update): Applies an action to the public link: `revoke`, `activate`, `extend` (with `extend_days`), or `reset` to the plan default. - [Bulk change delivery note status](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.bulk_status): 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[]`. - [Bulk delete delivery notes](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.bulk_delete): Delete several delivery notes in a single request. The body takes an `ids` array of `uuid`s. Returns a `BulkPartialSuccessResult` with `total`, `successful`, `failed` counts and a `failures` list (`id` + `error_code` + Spanish `error_message`) for those that could not be deleted (e.g. signed or invoiced). Supports `Idempotency-Key` for safe retries. - [Bulk download delivery note PDFs](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.bulk_pdf): 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. - [Bulk send delivery notes](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.bulk_send): 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). - [Cancel a delivery note](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.cancel): 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. - [Convert delivery note to invoice](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.convert): Convert a delivery note into a sales 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. - [Create a delivery note](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.create): 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. - [Delete a delivery note](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.delete): Delete a delivery note. Only `draft` notes without an assigned number can be deleted; any other state returns 409 `invalid_status_transition`. - [Download delivery note PDF](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.pdf): Download the PDF representation of a delivery note. Returns the binary PDF stream (`application/pdf`). Pass `?download=1` for `Content-Disposition: attachment` (file download); otherwise it is served `inline`. The response carries an `ETag`; resend it via `If-None-Match` to receive `304 Not Modified` when the document is unchanged. - [Duplicate a delivery note](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.duplicate): Create a new draft delivery note by copying lines, client, and metadata. - [Find a delivery note by external ID](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.find_by_external_id): 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. - [Forget delivery note signature PII](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.signature_audits.forget): 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 numeric primary key of the signature audit record. - [List all delivery notes](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.list): List your delivery notes with cursor-based pagination. - [List delivery note statuses](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.statuses): 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. - [Mark delivery note as delivered](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.mark_delivered): 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. - [Retrieve a delivery note](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.show): Retrieve a delivery note by its `uuid`. - [Retrieve a delivery note public link](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.public_link.get): 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). - [Retrieve delivery note stats](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.stats): Return aggregated KPIs for your delivery notes: total count, accumulated amount, per-status breakdown, count pending signature, and count converted to invoice this month. - [Send a delivery note](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.send): Send a delivery note to the client by email. Uses the email on file unless overridden in the payload. - [Sign a delivery note](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.sign): Record a handwritten signature on a delivery note, typically captured from the recipient on delivery. The signature must be a base64-encoded PNG (≤2 MB); other formats return 422. Signing sets `signed_at`/`signed_by` but does not change the status. The signature audit log retains hashed recipient PII for 5 years (Spanish LSSI-CE); use the `signature-audits/{auditId}/forget` endpoint to honor a GDPR erasure request. - [Update a delivery note](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.update): Update a draft delivery note. Once signed or invoiced, the delivery note becomes immutable. - [Update a delivery note public link](https://docs.factuarea.com/api-reference/delivery-notes/public-api.v1.delivery_notes.public_link.update): 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. - [Activate recurring invoice](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.activate): Activate a paused recurring invoice. The next invoice will be generated according to the schedule. This is a semantic alias of `POST /recurring_invoices/{recurring_invoice}/resume` — both map to the same handler and behave identically; neither is deprecated. - [Bulk delete recurring invoices](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.bulk-delete): 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. - [Cancel recurring invoice](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.cancel): 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. - [Create a recurring invoice](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.create): Create a recurring invoice template that auto-generates invoices on a fixed cadence (weekly, monthly, quarterly, yearly). - [Delete a recurring invoice](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.delete): Delete a recurring invoice template. Future invoices stop being generated; existing invoices remain. - [Find a recurring invoice by external ID](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.find_by_external_id): 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. - [Generate an invoice from a recurring template](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.generate): Trigger immediate invoice generation from the recurring configuration, outside the scheduled cycle. - [List all recurring invoices](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.list): List your recurring invoice templates with cursor-based pagination. - [List recurring invoice activity](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.activities): 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. - [List recurring invoice execution logs](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.logs): Return paginated history of generations, failures and other events for this recurring template. - [Pause recurring invoice](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.pause): 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`. - [Preview upcoming recurring invoice dates](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.preview): Return the next scheduled run dates with their due dates and estimated totals. Defaults to 5 occurrences. - [Resume recurring invoice](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.resume): Resume a paused recurring invoice. This is a semantic alias of `POST /recurring_invoices/{recurring_invoice}/activate` — both map to the same handler and behave identically; neither is deprecated. - [Retrieve a recurring invoice](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.show): Retrieve a recurring invoice template by its `uuid`. - [Retrieve recurring invoice stats](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.stats): 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. - [Skip the next recurring invoice generation](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.skip): 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. - [Update a recurring invoice](https://docs.factuarea.com/api-reference/recurring-invoices/public-api.v1.recurring_invoices.update): Update a recurring invoice template. The cadence and lines apply to invoices generated after the update; previously generated invoices are unaffected. ## API Reference — Purchases - [Attach a file to a purchase invoice](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.attach_file): Upload the original PDF document for a purchase invoice as `multipart/form-data`. Replaces any previously attached file. Returns the updated purchase invoice. - [Bulk change purchase invoice status](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.bulk_status): Transition up to 50 purchase invoices (by id) to `paid` in one call, each through the document state guard. The required `payment_date` is propagated as-is to every invoice (never `now()`). Returns a `BulkPartialSuccessResult`; invoices that could not transition (not found or already paid) come back in `failures[]`. - [Bulk delete purchase invoices](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.bulk_delete): Delete up to 100 purchase invoices 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. - [Create a purchase invoice](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.create): Record an invoice received from a supplier. - [Delete a purchase invoice](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.delete): Delete a purchase invoice. - [Download a purchase invoice payment receipt](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.payment_receipt): Stream the PDF payment receipt for a paid purchase invoice. Returns 409 if the invoice has not been paid yet. - [Download the original purchase invoice file](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.file): Stream the original PDF attached to the purchase invoice when it was uploaded. Returns 404 if no attachment is present. - [Find a purchase invoice by external ID](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.find_by_external_id): Look up a single purchase 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). Orthogonal to the supplier-provided `external_invoice_number` (the vendor's fiscal number). Returns the matching purchase invoice or 404 `purchase_invoice_not_found` if none uses that external_id within your company. - [Get purchase invoice stats](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.stats): Aggregated KPIs for your purchase invoices: total count and amount, counts per status, pending and overdue totals, and amounts by supplier. Returned as `{ "data": PurchaseInvoiceStats }`. - [List all purchase invoices](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.list): List purchase invoices received from suppliers with cursor-based pagination. - [List overdue purchase invoices](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.overdue): Return purchase invoices whose due date has passed and are still unpaid. - [List pending purchase invoices](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.pending): Return purchase invoices in pending payment status, paginated. - [List purchase invoice payments](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.list_payments): Return the full payment ledger of a purchase invoice as `{ "data": [...] }`, ordered by payment date descending. The ledger of a single invoice is bounded, so the complete set is returned without cursor pagination. An invoice with no payments returns an empty array, never a `404`; a `404` here means the invoice does not exist or belongs to another company. - [Mark purchase invoice as paid](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.mark_paid): Record payment of a purchase invoice. Sets `paid_at` to the current timestamp. - [Register a purchase invoice payment](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.register_payment): Record a partial (or total) payment against a purchase invoice and append it to its ledger. Body: `amount`, `paid_on`, `payment_method`, plus the optional `bank_account_id`, `reference` and `notes`. Three invariants are enforced and return `422`: the amount must be greater than zero and no larger than the outstanding balance, `paid_on` must fall between the invoice issue date and today, and a cancelled invoice accepts no payments. Once the accumulated payments cover the total, the invoice settles on its own — you do not need to call `mark_paid` as well. Returns `201` with the payment just created and a `Location` header pointing at the ledger. - [Remove a purchase invoice file](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.delete_file): Delete the original file attached to a purchase invoice and release its storage. Idempotent: succeeds even when no file was attached. - [Retrieve a purchase invoice](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.show): Retrieve a purchase invoice by its `uuid`. - [Update a purchase invoice](https://docs.factuarea.com/api-reference/purchase-invoices/public-api.v1.purchase_invoices.update): Update a purchase invoice. ## Migrating from other platforms - [Migrate from Holded](https://docs.factuarea.com/guides/migration-from-holded): Holded → Factuarea resource mapping, naming, equivalent endpoints and Python script. ## Optional - [Launch](https://docs.factuarea.com/changelog/launch): The Factuarea public platform launch — the v1 REST API (413 operations across 37 resources), official TypeScript and PHP SDKs, the CLI, the MCP server for AI agents, Spanish tax compliance, payments and managed-company operations, all with a test sandbox. ## Other pages - [FAQ](https://docs.factuarea.com/faq): Quick answers to the questions that come up most when integrating the Factuarea public API — keys, test mode, money, dates, idempotency and rate limits. - [API pricing & limits](https://docs.factuarea.com/pricing): What the API costs, which tier each plan grants, and the per-tier caps on requests, API keys and webhook endpoints. - [Support](https://docs.factuarea.com/support): How to reach the Factuarea API team, what to include when reporting an issue, how API access works, the status page and the changelog. - [Agents & scripting](https://docs.factuarea.com/cli/agents): The factuarea CLI agent-first contract — stable JSON on stdout, structured errors on stderr, semantic exit codes, the commands --json manifest, local scope-check and typed confirmation for irreversible operations. - [Devloop](https://docs.factuarea.com/cli/devloop): Test Factuarea webhooks locally without deploying or ngrok — factuarea listen forwards your account's events to localhost with a signed body, factuarea trigger produces real sandbox events. - [CLI overview](https://docs.factuarea.com/cli): Install and authenticate the official factuarea CLI — drive the v1 REST API from your terminal with brew, npm or a curl installer. Agent-first, Stripe-inspired. - [Usage](https://docs.factuarea.com/cli/usage): The factuarea command tree — list, show, create, domain actions, binary downloads, multipart uploads, the generic api escape hatch and the commands --json manifest. - [Absences](https://docs.factuarea.com/guides/absences): Configure absence types and policies, handle requests, and read balances and the team calendar over the v1 API. - [Account personalization](https://docs.factuarea.com/guides/account-personalization): Set the invoice-emission language, PDF template and accent color of your account — and read them back from the Account resource. - [Acting on behalf](https://docs.factuarea.com/guides/acting-on-behalf): Drive any child company from a single master API key with the X-Active-Profile header — profile resolution, the ownership guard, and how scopes stay fixed. - [Amounts & dates](https://docs.factuarea.com/guides/amounts-and-dates): How the API represents money (EUR, two decimals), dates (YYYY-MM-DD), timestamps (ISO-8601) and the Europe/Madrid timezone used for quota resets. - [Annul or correct](https://docs.factuarea.com/guides/annul-vs-correct): Four operations look like "undo an invoice" and only one is right for each case — delete, cancel, annul and corrective. Pick wrong and you either lose a fiscal document or file a declaration you did not intend. - [API keys (self-service)](https://docs.factuarea.com/guides/api-keys): List, create, rotate and revoke your API keys over the v1 API — the secret is shown once, environments are live/test, and the tier comes from your plan. - [Bulk operations](https://docs.factuarea.com/guides/bulk-operations): Partial-success contract for bulk endpoints — total, successful, failed and a per-row failures list. - [AEAT census verification](https://docs.factuarea.com/guides/census-verification): Check your company's — and your clients' — name + NIF pair against the AEAT census before issuing VeriFactu invoices — deterministic states, sandbox magic NIFs and fail-open behavior. - [Child company API keys](https://docs.factuarea.com/guides/child-api-keys): Mint, rotate and revoke API keys scoped to a single child company, deriving their scopes from the calling key — the api_keys endpoints under a managed company. - [Managed companies](https://docs.factuarea.com/guides/companies): Register, provision and operate child companies under your master tenant — the gestoría model over the v1 API, with per-seat billing and an active/inactive lifecycle. - [Corrective invoices](https://docs.factuarea.com/guides/corrective-invoices): R1 to R5, substitution versus differences, and how the lines of a corrective are built — the four decisions that determine what the AEAT and the VAT return actually receive. - [Disbursements](https://docs.factuarea.com/guides/disbursements): Money you pay on behalf of your customer — court fees, registry duties, visas — is not your revenue. How to invoice it so it stays out of your taxable base, your VAT and your annual third-party return. - [Employee seat billing](https://docs.factuarea.com/guides/employee-seats): The per-employee billing add-on — a dedicated monthly subscription whose seat count follows your active employees, with a paid seat covering the whole period. - [Export and import](https://docs.factuarea.com/guides/export-and-import): Export invoices to an Excel/CSV spreadsheet (SUMMARY or ITEMS, capped at 5000) and import clients from a CSV with a dry-run preview, column mapping, a downloadable template and partial-success. - [FACe invoicing (B2G)](https://docs.factuarea.com/guides/face-invoicing): Submit FacturaE 3.2.2 invoices to FACe — DIR3 codes, signed XAdES-EPES XML, processing states, cancellation, sandbox simulation and the facturae:write scope. - [Fiscal cookbook](https://docs.factuarea.com/guides/fiscal-cookbook): Six end-to-end recipes — issue and wait for AEAT acceptance, correct an amount, substitute simplified invoices, pass on a disbursement, invoice outside the EU, and repair a rejected record. - [Fiscal invoice examples](https://docs.factuarea.com/guides/fiscal-invoice-examples): The 21 Spanish tax scenarios for invoicing, which four of them ship as ready-to-send request examples in the API Reference, and a corrective example for each AEAT R-code (R1–R5). - [Glossary](https://docs.factuarea.com/guides/glossary): Spanish fiscal and domain terms used across the Factuarea API — NIF, VeriFactu, AEAT, FacturaE, Modelo 303/347, series, rectificativa, huella, CSV and more. - [International customers](https://docs.factuarea.com/guides/international-customers): Identifying a non-Spanish recipient with the AEAT alternative-ID catalogue, and the scenario-to-qualification map for intra-EU supplies, reverse charge, exports and one-stop-shop sales. - [Line tax classification and exemptions](https://docs.factuarea.com/guides/line-tax-classification-and-exemptions): E1–E6 and N1–N2 per line, IRPF withholding that subtracts, and the closed matrix of legal VAT-to-equivalence-surcharge pairs — the four fields that decide what the AEAT breakdown says. - [Monthly time-record close](https://docs.factuarea.com/guides/monthly-time-close): Freeze the immutable monthly register, seal it with a digital signature, and export the report or the payroll incidents file. - [Recording payments](https://docs.factuarea.com/guides/payments): Register partial payments against invoices and purchase invoices, and read the running balance from the ledger. - [Presence](https://docs.factuarea.com/guides/presence): Read who is working right now and who is in office or remote — a derived, read-only view over the time-tracking ledger, schedules and roster. - [Quickstart](https://docs.factuarea.com/guides/quickstart): Your first invoice in 5 minutes — verify your key, grab a series and a tax, create a client, issue an invoice and send it. One copy-paste sequence against a fact_test_ key. - [Recurring invoices](https://docs.factuarea.com/guides/recurring-invoices): Skip a cycle, create a recurrence from an invoice, configure auto-delivery, preview the next document and set per-line fiscal fields. - [Regime keys](https://docs.factuarea.com/guides/regime-keys): Three different things are called "regime" in Spanish invoicing. This is which one you set, which one is derived, and the closed AEAT catalogue of seventeen codes a line may declare. - [Scope and limitations](https://docs.factuarea.com/guides/scope-and-limitations): What the Factuarea API deliberately does not do, what it does not do yet, and the equivalent way to get each job done — plus four capabilities you may assume are missing and are not. - [Scopes & irreversibility](https://docs.factuarea.com/guides/scopes-and-irreversibility): How to read the required scope and irreversibility of each endpoint from the OpenAPI spec — the x-required-scope and x-irreversible extensions — and the catalog of irreversible operations. - [Simplified or full invoices](https://docs.factuarea.com/guides/simplified-vs-full-invoices): F1, F2 and F3 — when a simplified invoice is legal, the 3.000 € cap that is actually enforced, and the one-call substitution that turns a batch of tickets into a complete invoice. - [Tags & custom fields](https://docs.factuarea.com/guides/tags-and-custom-fields): Classify documents with tags and attach typed custom_fields. Filter lists by tag. How they differ from metadata. - [Territorial taxes — VAT, IGIC and IPSI](https://docs.factuarea.com/guides/territorial-taxes): Spain has three indirect taxes, not one. Which rates are legal in each, how the regime is chosen per document, what the AEAT breakdown declares, and why IGIC and IPSI never appear in the quarterly VAT return. - [Test mode & sandbox](https://docs.factuarea.com/guides/test-mode): Build your integration safely with fact_test_ keys — isolated sandbox data and AEAT, email and webhooks switched off. - [Time clock](https://docs.factuarea.com/guides/time-clock): Clock in and out, pauses, retroactive entries and the correction workflow over the append-only time-record ledger. - [VeriFactu auto-submission](https://docs.factuarea.com/guides/verifactu-auto-submission): There is no "send to AEAT" button. Registration is created when the invoice leaves draft — this is the list of gates that decide whether it happens, and the only manual levers that exist afterwards. - [VeriFactu submission states](https://docs.factuarea.com/guides/verifactu-submission-states): The lifecycle of a VeriFactu billing record — pending, submitted, accepted, rejected, error — what csv and huella mean, how the retry budget works, and when to retry instead of subsanar. - [VeriFactu record subsanación](https://docs.factuarea.com/guides/verifactu-subsanacion): Fix and resubmit VeriFactu billing records rejected by the AEAT — when subsanación applies, when you need an annulment or a corrective instead, and the exact API flow. - [Work schedules](https://docs.factuarea.com/guides/work-schedules): Define weekly work patterns, their compliance mode, and effective-dated assignments to employees over the v1 API. - [Time tracking overview](https://docs.factuarea.com/guides/workforce-overview): The workforce system over the v1 API — the immutable time-record ledger (RD-ley 8/2019), the portal-only employee role, the per-seat add-on and the eight domains that make it up. - [Claude Code plugin](https://docs.factuarea.com/mcp/claude-code-plugin): Two official plugins in one marketplace — factuarea-mcp connects Claude Code to the Factuarea MCP server, and factuarea-api ships five skills for building the integration itself. - [Connecting a client](https://docs.factuarea.com/mcp/connect): Connect Claude Code, Claude Desktop, the MCP Inspector or any MCP client to the Factuarea MCP server — with OAuth 2.1 or an API key, and in test mode. - [Errors & rate limits](https://docs.factuarea.com/mcp/errors): JSON-RPC error shapes mapped from the v1 contract, the full code table, and per-token / per-plan throttling with Retry-After. - [MCP overview](https://docs.factuarea.com/mcp): Connect AI agents to Factuarea over the Model Context Protocol — 391 tools across invoicing, catalog, compliance, time tracking and webhooks, with OAuth 2.1 and API-key auth. - [Scopes & permissions](https://docs.factuarea.com/mcp/scopes): The OAuth consent scope catalog, how it maps to the fine-grained scopes tools enforce, the super-scope, and plan/module gating. - [Tool catalog](https://docs.factuarea.com/mcp/tools): All 391 Factuarea MCP tools grouped by domain, with the scope each one requires and its rate-limit category. - [GoCardless](https://docs.factuarea.com/payments/gocardless): Status of the GoCardless integration — not released yet, what already exists behind the flag, and the exact v1 and MCP surface that appears the day it is switched on. - [Integration event inbox](https://docs.factuarea.com/payments/integration-events-inbox): Why a charge did not become an invoice — the typed discard reasons, which ones notify you, which ones park the event so you can replay it, and how the 30-day retention window works. - [Reconciling with system metadata](https://docs.factuarea.com/payments/metadata-reconciliation): The metadata keys Factuarea writes on invoices auto-issued from a Stripe subscription cycle, and how to use the metadata filter to pull every invoice of a subscription or of a billing period. - [MONEI](https://docs.factuarea.com/payments/monei): Status of the MONEI integration — not released yet, what already exists behind the flag, why it has no mandates resource, and the exact v1 and MCP surface that appears on release. - [Payouts & bank reconciliation](https://docs.factuarea.com/payments/payouts-reconciliation): How Factuarea ingests Stripe payouts, links them to the charges they group, reconciles them against your Norma 43 bank statement, and emits the payout.reconciled event. - [Stripe auto-invoicing](https://docs.factuarea.com/payments/stripe-autoinvoicing): Auto-issue invoices from Stripe Connect charges — NIF capture in Checkout, the simplified-invoice threshold, requiring a NIF, and which charges are routed to manual review. - [account_not_found](https://docs.factuarea.com/errors/account_not_found): The account behind the key could not be resolved, which usually means the key no longer points at a live company. - [addon_not_active](https://docs.factuarea.com/errors/addon_not_active): The functionality belongs to an add-on that is not active for the company right now. - [addon_required](https://docs.factuarea.com/errors/addon_required): Creating webhook endpoints belongs to the Developer API add-on, and the company does not have it active — the free tier allows zero endpoints. - [alta_record_not_found](https://docs.factuarea.com/errors/alta_record_not_found): The invoice has no registration record, so the operation that depends on it has nothing to work with. - [alternative_id_type_invalid](https://docs.factuarea.com/errors/alternative_id_type_invalid): The alternative identifier type is outside the catalogue `nif_iva`, `passport`, `country_id`, `residence_certificate`, `other_document`, `not_registered`. - [anulacion_record_already_exists](https://docs.factuarea.com/errors/anulacion_record_already_exists): The invoice already carries an annulment record in the chain, and annulment is reported only once. - [api_key_already_revoked](https://docs.factuarea.com/errors/api_key_already_revoked): The key was already revoked, and a revoked key admits no further operations: revocation is terminal. - [api_key_expired](https://docs.factuarea.com/errors/api_key_expired): The key passed its expiry date. - [api_key_not_found](https://docs.factuarea.com/errors/api_key_not_found): The identifier does not match any API key of the authenticated company. - [api_key_revoked](https://docs.factuarea.com/errors/api_key_revoked): The key was revoked, and a revoked key never authenticates again — revocation is the way to cut off a leaked credential. - [api_version_invalid_format](https://docs.factuarea.com/errors/api_version_invalid_format): The payload version of the endpoint is not a `YYYY-MM-DD` date. - [api_version_unsupported](https://docs.factuarea.com/errors/api_version_unsupported): The payload version is well formed but is not among the ones the platform serves. - [attachment_invalid_filename](https://docs.factuarea.com/errors/attachment_invalid_filename): The file name is not usable: it is empty, it carries path components, or it exceeds 200 characters. - [attachment_mime_not_allowed](https://docs.factuarea.com/errors/attachment_mime_not_allowed): The file type is outside the accepted set: PDF, PNG, JPEG, XML and HTML. - [attachment_missing](https://docs.factuarea.com/errors/attachment_missing): The purchase invoice exists but carries no attached file, so there is nothing to download. - [attachment_too_large](https://docs.factuarea.com/errors/attachment_too_large): The file exceeds the maximum size allowed for a document attachment. - [business_rule_violation](https://docs.factuarea.com/errors/business_rule_violation): A domain invariant rejected the operation. This code carries the family; `error.subcode` names the concrete rule and `error.message` explains it. - [cannot_archive_last_default_series](https://docs.factuarea.com/errors/cannot_archive_last_default_series): The series is the only active one for its document type. Archiving it would leave the company with no numbering available and freeze that kind of document. - [cannot_attach_to_cancelled_purchase_invoice](https://docs.factuarea.com/errors/cannot_attach_to_cancelled_purchase_invoice): The invoice is cancelled, and attaching documents to a cancelled record would alter closed documentation. - [cannot_have_both_tax_id_and_alternative_id](https://docs.factuarea.com/errors/cannot_have_both_tax_id_and_alternative_id): The client sends `tax_id` and an alternative identifier at the same time. Fiscal identity is one: the alternative identifier exists precisely for parties without a Spanish tax id. - [census_requires_tax_id](https://docs.factuarea.com/errors/census_requires_tax_id): Census verification checks the pair name plus tax id against AEAT, and one of the two is missing. - [certificate_expired](https://docs.factuarea.com/errors/certificate_expired): The certificate is outside its validity window: it has expired, or it is not valid yet. - [certificate_nif_mismatch](https://docs.factuarea.com/errors/certificate_nif_mismatch): The tax id of the certificate holder does not match the company tax id. AEAT records are signed on behalf of the company, so both must be the same. - [certificate_not_found](https://docs.factuarea.com/errors/certificate_not_found): The company has no FNMT certificate matching the identifier, or none uploaded at all. - [certificate_too_large](https://docs.factuarea.com/errors/certificate_too_large): The file exceeds the 100 KB limit, while a real FNMT certificate weighs a few kilobytes. - [client_has_documents](https://docs.factuarea.com/errors/client_has_documents): The client is referenced by issued documents. Deleting it would leave invoices, quotes or delivery notes without the party they were issued to, and fiscal records must remain traceable. - [client_import_too_large](https://docs.factuarea.com/errors/client_import_too_large): The CSV exceeds the row limit the synchronous import accepts, since the whole file is processed within the request. - [client_not_found](https://docs.factuarea.com/errors/client_not_found): The identifier does not resolve to any client of the authenticated company. - [client_requires_tax_identity](https://docs.factuarea.com/errors/client_requires_tax_identity): The client carries no fiscal identity: neither `tax_id` nor an alternative identifier, and an invoice cannot be issued to an unidentified party. - [clock_drift_exceeded](https://docs.factuarea.com/errors/clock_drift_exceeded): The server clock drifted from NTP beyond the allowed margin. The generation timestamp is part of the AEAT fingerprint, so an unsynchronised clock would produce records AEAT rejects. - [company_inactive](https://docs.factuarea.com/errors/company_inactive): The profile named in `X-Active-Profile` is one of your managed companies, but it is deactivated and cannot be operated until it comes back. - [conflicting_pagination_params](https://docs.factuarea.com/errors/conflicting_pagination_params): `starting_after` and `ending_before` travelled in the same request. They walk the collection in opposite directions, so only one of them can apply. - [corrective_invoice_inanulable](https://docs.factuarea.com/errors/corrective_invoice_inanulable): The invoice is itself a corrective, and correctives are never annulled: the correction chain has to stay auditable end to end. - [custom_header_blocklisted](https://docs.factuarea.com/errors/custom_header_blocklisted): One of the custom headers is reserved: the HTTP layer manages it (`host`, `content-type`, `content-length`, `user-agent`), Factuarea sends it as part of the signed contract (`factuarea-*`), or the proxy owns it (`x-forwarded-*`). - [custom_header_value_too_long](https://docs.factuarea.com/errors/custom_header_value_too_long): The value of a custom header exceeds 1024 characters. - [custom_tax_creation_disabled](https://docs.factuarea.com/errors/custom_tax_creation_disabled): Creating custom taxes is disabled for this company. - [declaracion_already_exists](https://docs.factuarea.com/errors/declaracion_already_exists): The company already filed its SIF responsibility statement for that period. - [declaracion_not_found](https://docs.factuarea.com/errors/declaracion_not_found): The company has no SIF responsibility statement filed for the requested period. - [delivery_note_not_found](https://docs.factuarea.com/errors/delivery_note_not_found): The identifier does not resolve to any delivery note of the authenticated company. - [delivery_note_section_not_editable_in_status](https://docs.factuarea.com/errors/delivery_note_section_not_editable_in_status): The logistics section — carrier, vehicle, driver — is frozen because the delivery note is already delivered, invoiced or cancelled. - [dependency_unavailable](https://docs.factuarea.com/errors/dependency_unavailable): An external service the operation relies on did not answer in time. - [direct_debit_requires_default_bank_account](https://docs.factuarea.com/errors/direct_debit_requires_default_bank_account): Direct debit was selected as the payment method, but the client has no default bank account to charge. - [document_type_required_for_ambiguous_code](https://docs.factuarea.com/errors/document_type_required_for_ambiguous_code): That series code exists for more than one document type, so on its own it does not identify a single series. - [driver_tax_id_requires_name](https://docs.factuarea.com/errors/driver_tax_id_requires_name): The driver tax id was sent without the driver name, and an identifier with no name identifies nobody on the delivery document. - [duplicate_tax_default_for_document_type](https://docs.factuarea.com/errors/duplicate_tax_default_for_document_type): Another tax of the same type is already the default for that document type, and the pair (tax type, document type) admits a single default. - [employee_seat_charge_failed](https://docs.factuarea.com/errors/employee_seat_charge_failed): The immediate pro-rated charge for the employee seat was declined: the card was refused, it needs authentication, or the payment provider was unreachable. The employee is not activated if the seat is not paid. - [employee_seat_payment_method_required](https://docs.factuarea.com/errors/employee_seat_payment_method_required): Adding or reactivating an employee charges a seat immediately, and the company operates in live mode with no payment method on file. - [event_already_processed](https://docs.factuarea.com/errors/event_already_processed): That SIF event is already recorded in the event chain, and each event is processed exactly once. - [event_not_found](https://docs.factuarea.com/errors/event_not_found): The identifier does not match any event of the authenticated company, or the event was purged by the 30-day retention policy. - [export_limit_exceeded](https://docs.factuarea.com/errors/export_limit_exceeded): The filtered selection exceeds the 5,000-invoice cap of the export, so the file is refused up front instead of being silently truncated. - [external_id_already_exists](https://docs.factuarea.com/errors/external_id_already_exists): The `external_id` you use to reconcile with your own system is already assigned to another object of the same type in this company. - [face_transmission_failed](https://docs.factuarea.com/errors/face_transmission_failed): The FACe platform — the public administration entry point — was unreachable or answered with a fault. The failure is upstream, not in your request. - [facturae_signing_failed](https://docs.factuarea.com/errors/facturae_signing_failed): The XAdES signature of the Facturae file could not be produced, usually because the signing certificate is unusable at that moment. - [feature_not_available_in_plan](https://docs.factuarea.com/errors/feature_not_available_in_plan): The feature is not included in the company plan. - [forbidden_action](https://docs.factuarea.com/errors/forbidden_action): The action is blocked for this resource even though the scope is right: the resource belongs to a shared catalogue, or the change travels through a different endpoint. - [gestoria_module_required](https://docs.factuarea.com/errors/gestoria_module_required): The master company holds a live plan, but one without the accounting-firm module, so it cannot create or operate managed companies. - [gestoria_plan_required](https://docs.factuarea.com/errors/gestoria_plan_required): The accounting firm has no active paid subscription, so there is no subscription on which to charge the seat. - [idempotency_key_in_use](https://docs.factuarea.com/errors/idempotency_key_in_use): Another request with the same `Idempotency-Key` is still in flight, and the result is not known yet. - [idempotency_key_invalid](https://docs.factuarea.com/errors/idempotency_key_invalid): The `Idempotency-Key` does not fit the accepted format: it must be 1 to 255 printable ASCII characters. - [idempotency_key_reused](https://docs.factuarea.com/errors/idempotency_key_reused): That `Idempotency-Key` was already used with a different payload. The key identifies one specific operation, so reusing it for another would make replay meaningless. - [Account error codes](https://docs.factuarea.com/errors/index-account): Every public API error code emitted by Account, with its HTTP status, its type and a page per code. - [Authentication error codes](https://docs.factuarea.com/errors/index-authentication): Every public API error code emitted by Authentication, with its HTTP status, its type and a page per code. - [Authorization error codes](https://docs.factuarea.com/errors/index-authorization): Every public API error code emitted by Authorization, with its HTTP status, its type and a page per code. - [Clients error codes](https://docs.factuarea.com/errors/index-clients): Every public API error code emitted by Clients, with its HTTP status, its type and a page per code. - [Companies error codes](https://docs.factuarea.com/errors/index-companies): Every public API error code emitted by Companies, with its HTTP status, its type and a page per code. - [Delivery Notes error codes](https://docs.factuarea.com/errors/index-delivery-notes): Every public API error code emitted by Delivery Notes, with its HTTP status, its type and a page per code. - [Employees error codes](https://docs.factuarea.com/errors/index-employees): Every public API error code emitted by Employees, with its HTTP status, its type and a page per code. - [Events error codes](https://docs.factuarea.com/errors/index-events): Every public API error code emitted by Events, with its HTTP status, its type and a page per code. - [Idempotency error codes](https://docs.factuarea.com/errors/index-idempotency): Every public API error code emitted by Idempotency, with its HTTP status, its type and a page per code. - [Invoices error codes](https://docs.factuarea.com/errors/index-invoices): Every public API error code emitted by Invoices, with its HTTP status, its type and a page per code. - [Notifications error codes](https://docs.factuarea.com/errors/index-notifications): Every public API error code emitted by Notifications, with its HTTP status, its type and a page per code. - [Payments error codes](https://docs.factuarea.com/errors/index-payments): Every public API error code emitted by Payments, with its HTTP status, its type and a page per code. - [Products error codes](https://docs.factuarea.com/errors/index-products): Every public API error code emitted by Products, with its HTTP status, its type and a page per code. - [Proformas error codes](https://docs.factuarea.com/errors/index-proformas): Every public API error code emitted by Proformas, with its HTTP status, its type and a page per code. - [Purchase Invoices error codes](https://docs.factuarea.com/errors/index-purchase-invoices): Every public API error code emitted by Purchase Invoices, with its HTTP status, its type and a page per code. - [Quotes error codes](https://docs.factuarea.com/errors/index-quotes): Every public API error code emitted by Quotes, with its HTTP status, its type and a page per code. - [Rate Limit error codes](https://docs.factuarea.com/errors/index-rate-limit): Every public API error code emitted by Rate Limit, with its HTTP status, its type and a page per code. - [Recurring Invoices error codes](https://docs.factuarea.com/errors/index-recurring-invoices): Every public API error code emitted by Recurring Invoices, with its HTTP status, its type and a page per code. - [Request error codes](https://docs.factuarea.com/errors/index-request): Every public API error code emitted by Request, with its HTTP status, its type and a page per code. - [Series error codes](https://docs.factuarea.com/errors/index-series): Every public API error code emitted by Series, with its HTTP status, its type and a page per code. - [Server error codes](https://docs.factuarea.com/errors/index-server): Every public API error code emitted by Server, with its HTTP status, its type and a page per code. - [Suppliers error codes](https://docs.factuarea.com/errors/index-suppliers): Every public API error code emitted by Suppliers, with its HTTP status, its type and a page per code. - [Tax Reports error codes](https://docs.factuarea.com/errors/index-tax-reports): Every public API error code emitted by Tax Reports, with its HTTP status, its type and a page per code. - [Taxes error codes](https://docs.factuarea.com/errors/index-taxes): Every public API error code emitted by Taxes, with its HTTP status, its type and a page per code. - [VeriFactu error codes](https://docs.factuarea.com/errors/index-verifactu): Every public API error code emitted by VeriFactu, with its HTTP status, its type and a page per code. - [Webhooks error codes](https://docs.factuarea.com/errors/index-webhooks): Every public API error code emitted by Webhooks, with its HTTP status, its type and a page per code. - [Error codes by category](https://docs.factuarea.com/errors): Every public API error code grouped by category, with a page per code covering its cause and what to do. - [indirect_tax_regime_invalid](https://docs.factuarea.com/errors/indirect_tax_regime_invalid): The indirect regime is outside the catalogue `iva`, `igic`, `ipsi`. - [insufficient_data_for_report](https://docs.factuarea.com/errors/insufficient_data_for_report): The period has no data to file, or an invoice of the period lacks a mandatory field for this model — typically the customer tax id. - [insufficient_scope](https://docs.factuarea.com/errors/insufficient_scope): The key authenticates correctly but does not carry the scope this operation requires. Scopes are granted when the key is issued and are not widened at call time. - [internal_error](https://docs.factuarea.com/errors/internal_error): Something broke on our side while processing the request. The condition is not caused by your payload. - [invalid_aeat_code](https://docs.factuarea.com/errors/invalid_aeat_code): The AEAT operation code is outside the closed catalogue `S1`, `S2`, `S3`, `E1`-`E6`, `N1`, `N2` used by VeriFactu and SII. - [invalid_api_key](https://docs.factuarea.com/errors/invalid_api_key): The key does not match any active key. It may be mistyped, truncated, or belong to a different environment — test keys and live keys are not interchangeable. - [invalid_certificate_format](https://docs.factuarea.com/errors/invalid_certificate_format): The file is not a PKCS#12 container: its first bytes do not match the ASN.1 structure the format requires, whatever its extension says. - [invalid_certificate_password](https://docs.factuarea.com/errors/invalid_certificate_password): The password does not open the certificate file. - [invalid_correction_nature](https://docs.factuarea.com/errors/invalid_correction_nature): `correction_nature` only accepts `S` (substitution: the corrective carries the full corrected amounts) or `I` (by difference: it carries only the delta). - [invalid_correction_reason](https://docs.factuarea.com/errors/invalid_correction_reason): The correction reason is outside the closed fiscal list (`error_fundado`, `concurso`, `incobrable`, `error_importe`, `error_cliente`, `devolucion`, `descuento`, `otras`), which maps to the AEAT codes R1 to R4. - [invalid_country_aeat_zone](https://docs.factuarea.com/errors/invalid_country_aeat_zone): The AEAT territorial zone is outside the catalogue `peninsula`, `canarias`, `ceuta`, `melilla`. - [invalid_country_code](https://docs.factuarea.com/errors/invalid_country_code): The country code is not exactly two characters, so it is not a valid ISO 3166-1 alpha-2 code. - [invalid_customer_visible_label](https://docs.factuarea.com/errors/invalid_customer_visible_label): The label shown to the customer on the document exceeds the allowed length. - [invalid_description](https://docs.factuarea.com/errors/invalid_description): The description exceeds the maximum length allowed for the field. - [invalid_document_type](https://docs.factuarea.com/errors/invalid_document_type): The document type is outside the catalogue: `invoice`, `quote`, `delivery_note`, `proforma`, `purchase_invoice`, `recurring_invoice`. - [invalid_expiry_date](https://docs.factuarea.com/errors/invalid_expiry_date): The expiry date is earlier than the issue date, or more than 365 days after it. - [invalid_frequency_interval](https://docs.factuarea.com/errors/invalid_frequency_interval): The interval is lower than 1, so the recurrence would never advance to a next run. - [invalid_frequency_type](https://docs.factuarea.com/errors/invalid_frequency_type): The frequency is outside the catalogue `daily`, `weekly`, `biweekly`, `monthly`, `bimonthly`, `quarterly`, `semiannual`, `annual`, `custom`. - [invalid_holiday_handling](https://docs.factuarea.com/errors/invalid_holiday_handling): The holiday policy is outside the catalogue `skip`, `before`, `after`, `same`. - [invalid_invoice_id](https://docs.factuarea.com/errors/invalid_invoice_id): The invoice reference received is not a valid identifier; it usually means an internal value slipped in where the API expects the public `id`. - [invalid_invoice_number](https://docs.factuarea.com/errors/invalid_invoice_number): The invoice number does not follow the canonical format `SERIES-YYYY-NNN`, plus the `-RECn` suffix on correctives. - [invalid_invoice_status](https://docs.factuarea.com/errors/invalid_invoice_status): The value sent as invoice status is outside the lifecycle catalogue (`draft`, `scheduled`, `sent`, `paid`, `overdue`, `cancelled`, `annulled`). - [invalid_invoice_uuid](https://docs.factuarea.com/errors/invalid_invoice_uuid): The invoice identifier in the path or in the payload is not a valid UUID. - [invalid_param_format](https://docs.factuarea.com/errors/invalid_param_format): A legacy form request rejected the shape of a value. Migrated endpoints report the same situation as `parameter_invalid_format` or `parameter_invalid_integer`. - [invalid_param_value](https://docs.factuarea.com/errors/invalid_param_value): A legacy form request rejected the value of a field. Migrated endpoints report the same situation as `parameter_invalid_enum` or `parameter_invalid_range`. - [invalid_payment_date](https://docs.factuarea.com/errors/invalid_payment_date): The payment date falls outside the accepted window: it cannot precede the invoice issue date, nor be in the future. - [invalid_payment_method](https://docs.factuarea.com/errors/invalid_payment_method): The payment method is outside the closed allowlist: `bank_transfer`, `cash`, `credit_card`, `sepa_direct_debit`, `paypal`, `bizum`, `other`. - [invalid_period](https://docs.factuarea.com/errors/invalid_period): The period does not identify a filing: the year is outside the accepted range, or the quarter is missing or out of the range 1 to 4 for a quarterly model. - [invalid_proforma_id](https://docs.factuarea.com/errors/invalid_proforma_id): The pro forma reference received is not a valid identifier, usually because an internal value replaced the public `id`. - [invalid_proforma_number](https://docs.factuarea.com/errors/invalid_proforma_number): The pro forma number does not follow the canonical numbering format of its series. - [invalid_proforma_status](https://docs.factuarea.com/errors/invalid_proforma_status): The value sent as status is outside the catalogue `draft`, `accepted`, `rejected`, `expired`, `invoiced`, `cancelled`. - [invalid_proforma_uuid](https://docs.factuarea.com/errors/invalid_proforma_uuid): The pro forma identifier in the path or in the payload is not a valid UUID. - [invalid_purchase_invoice_id](https://docs.factuarea.com/errors/invalid_purchase_invoice_id): The purchase invoice reference received is not a valid identifier, usually because an internal value replaced the public `id`. - [invalid_purchase_invoice_number](https://docs.factuarea.com/errors/invalid_purchase_invoice_number): The invoice number is empty or does not fit the accepted format. On a purchase invoice the number is the one the supplier printed, not one Factuarea generates. - [invalid_purchase_invoice_uuid](https://docs.factuarea.com/errors/invalid_purchase_invoice_uuid): The purchase invoice identifier in the path or in the payload is not a valid UUID. - [invalid_rate_for_tax_regime](https://docs.factuarea.com/errors/invalid_rate_for_tax_regime): The rate does not belong to the legal grid of its regime: IGIC admits 0, 3, 5, 7, 9.5, 15 and 20%; IPSI admits 0, 0.5, 1, 2, 4, 8 and 10%. - [invalid_recurring_invoice_id](https://docs.factuarea.com/errors/invalid_recurring_invoice_id): The recurrence reference received is not a valid identifier, usually because an internal value replaced the public `id`. - [invalid_recurring_invoice_uuid](https://docs.factuarea.com/errors/invalid_recurring_invoice_uuid): The recurrence identifier in the path or in the payload is not a valid UUID. - [invalid_series_code](https://docs.factuarea.com/errors/invalid_series_code): The series code is empty, too long, or carries characters that do not belong in a fiscal prefix. - [invalid_series_name](https://docs.factuarea.com/errors/invalid_series_name): The series name is empty or exceeds the allowed length. - [invalid_series_number](https://docs.factuarea.com/errors/invalid_series_number): The starting number is not valid: it is not a positive integer, or it falls at or below the last number already issued, which would re-issue numbers already in use. - [invalid_series_uuid](https://docs.factuarea.com/errors/invalid_series_uuid): The series identifier in the path or in the payload is not a valid UUID. - [invalid_series_year](https://docs.factuarea.com/errors/invalid_series_year): The fiscal year is not a valid four-digit year for a numbering series. - [invalid_status_transition](https://docs.factuarea.com/errors/invalid_status_transition): The requested state is not reachable from the state the document is in right now. - [invalid_tax_code](https://docs.factuarea.com/errors/invalid_tax_code): The tax code is empty or longer than 50 characters. - [invalid_tax_name](https://docs.factuarea.com/errors/invalid_tax_name): The tax name is empty or longer than 255 characters. - [invalid_tax_rate](https://docs.factuarea.com/errors/invalid_tax_rate): The rate falls outside the range allowed for its type: VAT 0-27%, withholding 0-47%, equivalence surcharge 0-10%, other 0-100%. - [invalid_tax_type_filter](https://docs.factuarea.com/errors/invalid_tax_type_filter): The `type` filter of the by-type listing carries a value outside the enum `vat`, `retention`, `surcharge`, `other`. - [invalid_validity_window](https://docs.factuarea.com/errors/invalid_validity_window): The validity window is inverted: `valid_until` falls before `valid_from`. - [invoice_already_annulled](https://docs.factuarea.com/errors/invoice_already_annulled): The invoice was already annulled. Annulment is terminal and, with VeriFactu active, its annulment record has already reached AEAT. - [invoice_already_paid](https://docs.factuarea.com/errors/invoice_already_paid): The invoice is already settled. `paid` is a terminal, accounting-closed state: the output VAT has been declared, or will be declared for the period. - [invoice_already_sent](https://docs.factuarea.com/errors/invoice_already_sent): The invoice was already issued: it holds a definitive series number and, with VeriFactu active, its registration with AEAT. Issuing does not happen twice. - [invoice_cannot_assign_number](https://docs.factuarea.com/errors/invoice_cannot_assign_number): A definitive number was requested for an invoice that is not a draft, or that already carries one. Series numbering is monotonic and numbers are never reassigned. - [invoice_invalid_status_transition](https://docs.factuarea.com/errors/invoice_invalid_status_transition): The target status is unreachable from the current one. The lifecycle is directed: `draft` moves to `scheduled` or `sent`, `sent` to `paid`, `overdue` or `annulled`, and `paid`, `cancelled` and `annulled` are terminal. - [invoice_not_cancellable_in_current_state](https://docs.factuarea.com/errors/invoice_not_cancellable_in_current_state): Cancelling withdraws a draft that is not yet fiscally binding, so it only applies while the invoice is `draft`. - [invoice_not_correctable_in_current_state](https://docs.factuarea.com/errors/invoice_not_correctable_in_current_state): A corrective invoice can only be issued against an invoice that is already issued (`sent` or `paid`). A draft, a cancelled or an annulled invoice has nothing to correct. - [invoice_not_deletable_in_current_state](https://docs.factuarea.com/errors/invoice_not_deletable_in_current_state): Only `draft` and `cancelled` invoices can be deleted. A numbered invoice never disappears: the correlative sequence must stay auditable. - [invoice_not_editable_in_current_state](https://docs.factuarea.com/errors/invoice_not_editable_in_current_state): Only a draft admits editing. Once issued, the invoice is immutable and its content is frozen along with its fiscal record. - [invoice_not_eligible_for_action](https://docs.factuarea.com/errors/invoice_not_eligible_for_action): The requested action does not apply to this invoice: its type or its current state leaves it outside the scope of the operation. - [invoice_not_found](https://docs.factuarea.com/errors/invoice_not_found): The identifier does not resolve to any invoice of the authenticated company. Invoices belonging to another company answer exactly the same way. - [invoice_not_modifiable_in_current_state](https://docs.factuarea.com/errors/invoice_not_modifiable_in_current_state): The field you are changing is frozen for the current state — for instance the tax regime of an annulled invoice. - [invoice_not_paid](https://docs.factuarea.com/errors/invoice_not_paid): A payment receipt was requested for an invoice with no settled payment, so there is nothing to certify. - [invoice_not_reschedulable_in_current_state](https://docs.factuarea.com/errors/invoice_not_reschedulable_in_current_state): Rescheduling moves the issuing date of an invoice that is waiting in `scheduled`, and this invoice is not waiting. - [invoice_not_schedulable_in_current_state](https://docs.factuarea.com/errors/invoice_not_schedulable_in_current_state): Only a draft can be scheduled: scheduling reserves a future issuing moment without consuming a series number yet. - [invoice_not_unschedulable_in_current_state](https://docs.factuarea.com/errors/invoice_not_unschedulable_in_current_state): Unscheduling returns an invoice from `scheduled` to `draft`, so it only applies while it is still waiting to be issued. - [invoice_not_unsendable_in_current_state](https://docs.factuarea.com/errors/invoice_not_unsendable_in_current_state): Undoing the delivery mark only applies to a `sent` invoice: it clears `sent_at` and keeps the invoice issued. - [invoice_requires_at_least_one_line](https://docs.factuarea.com/errors/invoice_requires_at_least_one_line): The invoice carries no operation line, so it has no taxable base and cannot be issued. This happens both when you send no lines at all and when every line you send is a disbursement: a disbursement is an amount paid on the customer's behalf (art. 78.Tres.3 LIVA), not an operation of your own. - [invoice_year_required_for_ambiguous_number](https://docs.factuarea.com/errors/invoice_year_required_for_ambiguous_number): That invoice number exists in more than one fiscal year, so on its own it does not identify a single invoice. - [ip_not_allowed](https://docs.factuarea.com/errors/ip_not_allowed): The key restricts the addresses it accepts, and the request came from one outside that list. - [length_required](https://docs.factuarea.com/errors/length_required): A request with a body arrived using chunked transfer encoding, without declaring its size. The API needs the length up front to reject oversized payloads before buffering them. - [line_total_checksum_mismatch](https://docs.factuarea.com/errors/line_total_checksum_mismatch): The `line_total` you declared does not match the one Factuarea computes for that line (quantity × price − discount + VAT − withholding + surcharge) and the deviation is above the one-cent tolerance. The amount that gets invoiced and reported to the tax authority is always the one computed here, so the discrepancy means your system and the issued invoice would not reconcile. - [line_type_invalid](https://docs.factuarea.com/errors/line_type_invalid): The line type falls outside the closed `NORMAL` / `SUPLIDO` catalogue. An issued invoice only tells two natures apart: what you sell, which forms the taxable base and carries VAT, and a disbursement (`suplido`), money advanced in the name and on behalf of the customer, which is therefore left out of the base (art. 78.Tres.3 of the Spanish VAT Act). - [maintenance](https://docs.factuarea.com/errors/maintenance): The platform is in a maintenance window and writes are held back on purpose. - [max_api_keys_exceeded](https://docs.factuarea.com/errors/max_api_keys_exceeded): The company reached the number of API keys its plan allows. - [max_retries_exceeded](https://docs.factuarea.com/errors/max_retries_exceeded): The record exhausted the technical retry budget for resending the stored XML. Retrying the same content again would fail the same way. - [max_webhook_endpoints_exceeded](https://docs.factuarea.com/errors/max_webhook_endpoints_exceeded): The company reached the number of webhook endpoints its add-on tier allows. - [metadata_too_many_keys](https://docs.factuarea.com/errors/metadata_too_many_keys): The `metadata` object exceeds the limit of 50 keys per resource. - [metadata_value_too_long](https://docs.factuarea.com/errors/metadata_value_too_long): One value of `metadata` exceeds 500 characters once serialised to text. - [method_not_allowed](https://docs.factuarea.com/errors/method_not_allowed): The path exists but does not accept the HTTP verb used. - [missing_api_key](https://docs.factuarea.com/errors/missing_api_key): The request carries no credentials: neither the `Authorization` header nor `X-API-Key`. - [missing_required_param](https://docs.factuarea.com/errors/missing_required_param): A legacy form request found a required field missing. Endpoints already migrated to the canonical parsers report the same situation as `parameter_missing`. - [mode_switch_blocked_until_year_end](https://docs.factuarea.com/errors/mode_switch_blocked_until_year_end): VeriFactu mode was activated during this fiscal year and at least one billing record was issued. Stepping back would degrade the integrity of a chain already reported to AEAT. - [module_not_available_in_sandbox](https://docs.factuarea.com/errors/module_not_available_in_sandbox): The resource belongs to a module vetoed in test mode. Sandbox never touches AEAT, banks or real billing, so those modules stay out on purpose. - [monthly_quota_exceeded](https://docs.factuarea.com/errors/monthly_quota_exceeded): The company exhausted the monthly call quota its plan includes. - [monthly_requires_month_segmented_format](https://docs.factuarea.com/errors/monthly_requires_month_segmented_format): The counter resets monthly but the numbering mask does not segment by month, so two months would start on the same correlative and produce duplicate numbers within the year. - [no_invoices_in_period](https://docs.factuarea.com/errors/no_invoices_in_period): The quarterly operation found no invoices in the requested period, so there is nothing to package or send. - [notification_not_found](https://docs.factuarea.com/errors/notification_not_found): The identifier does not match any notification of the authenticated company, or the notification fell out of the retention window. - [operation_regime_invalid](https://docs.factuarea.com/errors/operation_regime_invalid): The operation regime is outside the catalogue `general`, `intracomunitaria`, `importacion_exportacion`, `isp`. - [origin_not_allowed](https://docs.factuarea.com/errors/origin_not_allowed): The request comes from a browser origin that the key does not accept. - [pack_in_use](https://docs.factuarea.com/errors/pack_in_use): The pack is referenced by issued documents, so deleting it would break their composition. - [pack_not_found](https://docs.factuarea.com/errors/pack_not_found): The identifier does not resolve to any pack of the authenticated company. - [pack_share_link_failed](https://docs.factuarea.com/errors/pack_share_link_failed): The share link for the pack could not be produced. The pack itself is unaffected. - [parameter_invalid](https://docs.factuarea.com/errors/parameter_invalid): A value object built from the payload rejected the value it received. `error.subcode` names which one — tax code, country code, rate, and so on. - [parameter_invalid_boolean](https://docs.factuarea.com/errors/parameter_invalid_boolean): A parameter that must be a boolean received a value outside the accepted representations (`true`/`false`, `1`/`0`). - [parameter_invalid_cursor](https://docs.factuarea.com/errors/parameter_invalid_cursor): The `starting_after` or `ending_before` cursor is not a valid UUID, so it cannot point at any row of the collection. - [parameter_invalid_empty](https://docs.factuarea.com/errors/parameter_invalid_empty): A parameter arrived with an empty value: an `in` filter with no items, a comparison with nothing after the operator, or an equality filter with an empty string. - [parameter_invalid_enum](https://docs.factuarea.com/errors/parameter_invalid_enum): The value falls outside the closed set the parameter accepts. On listings it also covers a filter operator other than `eq`, `gte`, `lte`, `gt`, `lt`, `in` or `contains`. - [parameter_invalid_format](https://docs.factuarea.com/errors/parameter_invalid_format): The value has the right type but not the shape the parameter requires: a date, an identifier pattern or a header such as `Factuarea-Version`. - [parameter_invalid_integer](https://docs.factuarea.com/errors/parameter_invalid_integer): A parameter that must be a whole number received something that cannot be parsed as one, such as `limit=abc`. - [parameter_invalid_iso8601](https://docs.factuarea.com/errors/parameter_invalid_iso8601): A range filter (`gte`, `lte`, `gt`, `lt`) received a value that is neither numeric nor an ISO 8601 date. - [parameter_invalid_range](https://docs.factuarea.com/errors/parameter_invalid_range): A numeric parameter fell outside its accepted bounds. The usual case is `limit`, which must be between 1 and 100. - [parameter_invalid_string](https://docs.factuarea.com/errors/parameter_invalid_string): A parameter that must be text received an array, an object or a value that cannot be read as a string. - [parameter_invalid_url](https://docs.factuarea.com/errors/parameter_invalid_url): A field that must hold an absolute URL received a value that is not one, usually because the scheme or the host is missing. - [parameter_invalid_uuid](https://docs.factuarea.com/errors/parameter_invalid_uuid): An identifier field received a value that is not a valid UUID. Every v1 resource id is a UUID. - [parameter_invalid_value](https://docs.factuarea.com/errors/parameter_invalid_value): The value is syntactically correct but not admissible for this resource: outside the canonical catalogue of the field, or inconsistent with the rest of the payload. - [parameter_missing](https://docs.factuarea.com/errors/parameter_missing): The endpoint requires a parameter that the request did not carry. `error.param` names it. - [parameter_unknown](https://docs.factuarea.com/errors/parameter_unknown): The request carries a parameter the endpoint does not accept: a filter outside its allowlist, a `sort` field that is not sortable, or the offset-style `page` — v1 paginates by cursor. - [payload_too_large](https://docs.factuarea.com/errors/payload_too_large): The request body exceeds the accepted size: 1 MB as a rule, 6 MB on the endpoints that accept files. - [payment_method_invalid](https://docs.factuarea.com/errors/payment_method_invalid): Same closed allowlist as `invalid_payment_method`, reported when the value is rejected while reading the payment method field of the payload. - [payment_method_required](https://docs.factuarea.com/errors/payment_method_required): Adding a managed company charges a seat immediately, and the accounting firm operates in live mode with no payment method on file. - [payout_reconciliation_amount_mismatch](https://docs.factuarea.com/errors/payout_reconciliation_amount_mismatch): The confirmed amount does not match the net amount of the payout, so the reconciliation would close with a difference nobody accounts for. - [pdf_generation_failed](https://docs.factuarea.com/errors/pdf_generation_failed): The rendering service could not produce the PDF. The document and its data are intact — what failed is the file. - [product_in_use](https://docs.factuarea.com/errors/product_in_use): The product is referenced by issued documents or by other catalogue entries, and removing it would leave those references dangling. - [product_not_found](https://docs.factuarea.com/errors/product_not_found): The identifier does not resolve to any product of the authenticated company. - [profile_not_found](https://docs.factuarea.com/errors/profile_not_found): The `X-Active-Profile` header names a company that does not exist or does not belong to the accounting-firm tree of the authenticated key. Both cases answer the same so that the API never reveals companies of other tenants. - [proforma_already_accepted](https://docs.factuarea.com/errors/proforma_already_accepted): The customer already accepted the pro forma, and acceptance is registered once. - [proforma_already_rejected](https://docs.factuarea.com/errors/proforma_already_rejected): The pro forma is already marked as rejected. - [proforma_cannot_be_accepted](https://docs.factuarea.com/errors/proforma_cannot_be_accepted): Acceptance does not apply from the current state: an invoiced, cancelled or expired pro forma no longer admits it. - [proforma_cannot_be_rejected](https://docs.factuarea.com/errors/proforma_cannot_be_rejected): Rejection does not apply from the current state: once invoiced, cancelled or expired, the pro forma is closed. - [proforma_cannot_be_sent](https://docs.factuarea.com/errors/proforma_cannot_be_sent): Sending by email does not apply to a pro forma in a terminal state: there is no live offer to deliver. - [proforma_invalid_status_transition](https://docs.factuarea.com/errors/proforma_invalid_status_transition): The target status is unreachable from the current one: a draft can be accepted, cancelled or expire; an accepted pro forma can be invoiced, rejected or expire; invoiced, cancelled and expired are terminal. - [proforma_not_convertible_in_current_state](https://docs.factuarea.com/errors/proforma_not_convertible_in_current_state): Converting into an invoice requires the customer to have accepted the pro forma; from any other state there is no agreement to bill. - [proforma_not_deletable_in_current_state](https://docs.factuarea.com/errors/proforma_not_deletable_in_current_state): Only a draft pro forma can be deleted. Once it has been accepted, rejected or invoiced, it is part of the commercial trail. - [proforma_not_draft](https://docs.factuarea.com/errors/proforma_not_draft): The operation only makes sense while the pro forma is a draft, and this one has already moved on. - [proforma_not_editable_in_current_state](https://docs.factuarea.com/errors/proforma_not_editable_in_current_state): Only a draft pro forma admits editing. Once it is accepted, rejected, expired, invoiced or cancelled, its content is settled. - [proforma_not_found](https://docs.factuarea.com/errors/proforma_not_found): The identifier does not resolve to any pro forma of the authenticated company. - [proforma_requires_at_least_one_line](https://docs.factuarea.com/errors/proforma_requires_at_least_one_line): The pro forma has no lines, so there is no amount to put in front of the customer. - [public_link_expires_at_exceeds_max_days](https://docs.factuarea.com/errors/public_link_expires_at_exceeds_max_days): The requested expiry for the public link goes beyond the maximum window your plan allows for shared documents. - [purchase_invoice_already_exists](https://docs.factuarea.com/errors/purchase_invoice_already_exists): That supplier already has a purchase invoice registered with the same number. The pair supplier plus number identifies the document uniquely and prevents recording an expense twice. - [purchase_invoice_not_deletable_in_current_state](https://docs.factuarea.com/errors/purchase_invoice_not_deletable_in_current_state): Only draft and cancelled purchase invoices can be deleted. A pending or paid one is part of the expense ledger. - [purchase_invoice_not_draft](https://docs.factuarea.com/errors/purchase_invoice_not_draft): The operation only applies while the purchase invoice is a draft, and this one has already been registered. - [purchase_invoice_not_editable_in_current_state](https://docs.factuarea.com/errors/purchase_invoice_not_editable_in_current_state): Only a draft purchase invoice can be edited. Once registered as pending, paid or cancelled, its content backs an accounting entry. - [purchase_invoice_not_found](https://docs.factuarea.com/errors/purchase_invoice_not_found): The identifier does not resolve to any purchase invoice of the authenticated company. - [purchase_invoice_requires_at_least_one_line](https://docs.factuarea.com/errors/purchase_invoice_requires_at_least_one_line): The purchase invoice has no lines, so there is no expense nor deductible VAT to record. - [quote_already_accepted](https://docs.factuarea.com/errors/quote_already_accepted): The quote was already approved, and approval is registered once. - [quote_already_rejected](https://docs.factuarea.com/errors/quote_already_rejected): The quote is already marked as rejected. - [quote_expired](https://docs.factuarea.com/errors/quote_expired): The quote passed its validity date, so the offered conditions are no longer binding and it cannot be approved or converted as is. - [quote_not_found](https://docs.factuarea.com/errors/quote_not_found): The identifier does not resolve to any quote of the authenticated company. - [rate_limit_exceeded](https://docs.factuarea.com/errors/rate_limit_exceeded): The key sent more requests than its rate allows in the current window. - [receipt_not_available](https://docs.factuarea.com/errors/receipt_not_available): There is no receipt to issue because the document has no settled payment behind it. - [record_already_accepted](https://docs.factuarea.com/errors/record_already_accepted): AEAT already accepted the record. Acceptance is terminal and its content is frozen as part of the fingerprint chain. - [record_immutable](https://docs.factuarea.com/errors/record_immutable): The record belongs to an append-only ledger: once written, its fiscal content is closed to changes and to deletion. - [record_not_rejected](https://docs.factuarea.com/errors/record_not_rejected): The correction flow only applies to records AEAT rejected on data grounds. This record is in another state — a technical failure, for instance, is covered by the automatic retry. - [record_not_subsanable](https://docs.factuarea.com/errors/record_not_subsanable): The record cannot be amended: it is not a registration record, or it has no source invoice from which its content could be regenerated. - [recurring_already_active](https://docs.factuarea.com/errors/recurring_already_active): The recurrence is already running, so there is nothing to activate. Legacy code kept for compatibility: current endpoints report this as `recurring_invoice_already_active`. - [recurring_invoice_already_active](https://docs.factuarea.com/errors/recurring_invoice_already_active): The recurrence is already running. - [recurring_invoice_already_cancelled](https://docs.factuarea.com/errors/recurring_invoice_already_cancelled): The recurrence was already cancelled, and cancellation is terminal. - [recurring_invoice_already_paused](https://docs.factuarea.com/errors/recurring_invoice_already_paused): The recurrence is already paused, so pausing it again changes nothing. - [recurring_invoice_cancelled_cannot_resume](https://docs.factuarea.com/errors/recurring_invoice_cancelled_cannot_resume): A cancelled recurrence cannot be resumed: cancellation closes it for good, unlike a pause. - [recurring_invoice_cannot_run](https://docs.factuarea.com/errors/recurring_invoice_cannot_run): The recurrence cannot generate an invoice right now: it is not running, its cycle is over, or it lacks the data an invoice needs. `error.message` states the specific reason. - [recurring_invoice_has_generated_invoices](https://docs.factuarea.com/errors/recurring_invoice_has_generated_invoices): The recurrence already produced invoices, and those invoices depend on it for their traceability. - [recurring_invoice_not_found](https://docs.factuarea.com/errors/recurring_invoice_not_found): The identifier does not resolve to any recurrence of the authenticated company. - [recurring_invoice_requires_at_least_one_line](https://docs.factuarea.com/errors/recurring_invoice_requires_at_least_one_line): The recurrence has no lines, so every generated invoice would come out empty. - [recurring_not_active](https://docs.factuarea.com/errors/recurring_not_active): The operation needs a running recurrence and this one is paused, completed or cancelled. Legacy code kept for compatibility with older integrations. - [register_sealing_failed](https://docs.factuarea.com/errors/register_sealing_failed): The cryptographic sealing of the record did not complete, so the closure was left unsigned rather than sealed with a broken signature. - [reminder_not_applicable](https://docs.factuarea.com/errors/reminder_not_applicable): The payment reminder does not apply: the invoice is not `sent` or `overdue`, there is no recipient email, the public link is missing or disabled, or another reminder went out in the last 24 hours. - [replay_delivery_not_retryable](https://docs.factuarea.com/errors/replay_delivery_not_retryable): Only failed deliveries can be replayed. A delivery that succeeded, or one still in flight, has nothing to resend. - [replay_event_expired](https://docs.factuarea.com/errors/replay_event_expired): The event behind the delivery was purged by the 30-day retention policy, so there is no payload left to resend. - [report_format_invalid](https://docs.factuarea.com/errors/report_format_invalid): The format is outside the catalogue `txt_aeat`, `pdf`, `excel`. - [requires_annulment](https://docs.factuarea.com/errors/requires_annulment): The regenerated content changes a field that takes part in the fingerprint — issuer tax id, series and number, issue date, invoice type, tax amount or total — and the chain cannot be rewritten. - [resource_already_exists](https://docs.factuarea.com/errors/resource_already_exists): Creating the object would duplicate one that already exists under a unique key — tax id, SKU, external id. `error.details.existing_resource_id` points at the object that already holds the value. - [resource_conflict](https://docs.factuarea.com/errors/resource_conflict): The operation collided with the current state of the resource and no more specific conflict code applies. - [resource_immutable](https://docs.factuarea.com/errors/resource_immutable): The object is closed to changes for this operation: its state or its accounting record forbids modifying it. - [resource_locked](https://docs.factuarea.com/errors/resource_locked): Another operation holds the resource until it finishes: concurrent writes on the same object are serialised instead of interleaved. - [resource_not_deletable](https://docs.factuarea.com/errors/resource_not_deletable): The object exists but its state or its dependants block the deletion. In bulk deletions this is the per-row code of every entry that could not be removed. - [resource_not_found](https://docs.factuarea.com/errors/resource_not_found): The identifier resolves to nothing visible to the authenticated company. Objects belonging to another company answer exactly the same way, by design. - [route_not_found](https://docs.factuarea.com/errors/route_not_found): The path does not match any v1 endpoint. It is usually a typo, a missing `/v1` prefix, or a path from a different area of the API. - [scheduled_for_in_past](https://docs.factuarea.com/errors/scheduled_for_in_past): `scheduled_for` is not strictly in the future, so there is no waiting period to reserve. - [scope_not_allowed_by_plan](https://docs.factuarea.com/errors/scope_not_allowed_by_plan): One of the requested scopes belongs to a module that the plan does not include, so the key would be born with a permission that could never be exercised. - [scope_not_allowed_in_sandbox](https://docs.factuarea.com/errors/scope_not_allowed_in_sandbox): A test key cannot be born with scopes of modules vetoed in sandbox. - [seat_charge_failed](https://docs.factuarea.com/errors/seat_charge_failed): The immediate pro-rated charge for the seat was declined: the card was refused, it needs authentication, or the payment provider was unreachable. The company is not created if the seat is not paid. - [send_failed](https://docs.factuarea.com/errors/send_failed): The document was not delivered by email: the mail provider rejected the message or was unreachable. - [series_already_archived](https://docs.factuarea.com/errors/series_already_archived): The series was already archived, and archiving is not repeated: a second call means the client is out of sync with the real state. - [series_code_immutable_with_documents](https://docs.factuarea.com/errors/series_code_immutable_with_documents): Changing the prefix of a series that already issued documents would retroactively rewrite their fiscal identifier, while customers and AEAT hold the original number. - [series_has_documents](https://docs.factuarea.com/errors/series_has_documents): The series already numbered documents, so it cannot be removed: the correlative sequence has to stay auditable. - [series_immutable](https://docs.factuarea.com/errors/series_immutable): Series are not editable nor deletable through the API: legal numbering continuity requires their prefix, year and counter to stay put. - [series_initial_number_creates_gap](https://docs.factuarea.com/errors/series_initial_number_creates_gap): The starting number jumps beyond the next natural correlative while documents already exist for the current year, and that gap in the sequence is not acceptable to AEAT. - [series_locked_by_verifactu](https://docs.factuarea.com/errors/series_locked_by_verifactu): At least one invoice of the series holds a billing record accepted by AEAT, which freezes the prefix, the year and the numbering base of the series. - [series_not_found](https://docs.factuarea.com/errors/series_not_found): The identifier does not resolve to any numbering series of the authenticated company. - [series_type_invalid](https://docs.factuarea.com/errors/series_type_invalid): The document type of the series is outside the catalogue `invoice`, `quote`, `delivery_note`, `proforma`, `purchase_invoice`, `recurring_invoice`. - [series_year_locked](https://docs.factuarea.com/errors/series_year_locked): The series already issued documents in its current year. Moving the year would leave those documents pointing at an empty year while their taxable base sits in another. - [service_unavailable](https://docs.factuarea.com/errors/service_unavailable): The service, or a dependency it needs, is temporarily unable to answer. - [signature_payload_too_large](https://docs.factuarea.com/errors/signature_payload_too_large): The signature image exceeds the accepted size for the field. - [sii_excluded](https://docs.factuarea.com/errors/sii_excluded): The company is registered with SII, and SII filers are excluded from the VeriFactu regulation. - [simplified_invoice_cannot_be_substituted](https://docs.factuarea.com/errors/simplified_invoice_cannot_be_substituted): One invoice of the substitution list cannot be replaced: it is not simplified, it is cancelled or annulled, it belongs to another company, or it already has a substitute. - [simplified_invoice_not_allowed](https://docs.factuarea.com/errors/simplified_invoice_not_allowed): The operation is not eligible for a simplified invoice: it exceeds EUR 3,000, or it is an intra-EU supply, an export, a reverse-charge operation, or the customer needs a full invoice to deduct VAT. - [simplified_limit_exceeded](https://docs.factuarea.com/errors/simplified_limit_exceeded): The lines would push the simplified invoice (F2) over the absolute legal cap of EUR 3,000 VAT included. - [sku_already_exists](https://docs.factuarea.com/errors/sku_already_exists): Another product of the company already uses that SKU, and the SKU identifies the item uniquely in the catalogue. - [stripe_payout_already_reconciled](https://docs.factuarea.com/errors/stripe_payout_already_reconciled): The payout was already reconciled, and reconciliation is terminal: repeating it would double-count the bank entry. - [stripe_payout_not_found](https://docs.factuarea.com/errors/stripe_payout_not_found): The identifier does not resolve to any payout of the authenticated company. - [suplido_line_cannot_carry_taxes](https://docs.factuarea.com/errors/suplido_line_cannot_carry_taxes): The disbursement line carries charges of its own: a VAT rate, withholding, equivalence surcharge, discount, regime key, exemption cause or product/pack. A disbursement is not an operation of the issuer, so charging tax on it would mean paying tax on a supply you never made, and tying it to a product would move stock you never sold. - [suplido_not_allowed_in_simplified_invoice](https://docs.factuarea.com/errors/suplido_not_allowed_in_simplified_invoice): The invoice is simplified (F2) and a simplified invoice does not identify the recipient. With no identified recipient there is nobody to evidence the payment on behalf of, so the amount cannot take disbursement treatment on this invoice type. - [suplido_requires_source_invoice_reference](https://docs.factuarea.com/errors/suplido_requires_source_invoice_reference): The disbursement line does not carry `source_invoice_reference`, the number of the supporting document the third party issued in the customer's name. Without that document the payment is not evidenced as made on someone else's behalf, and the tax authority would treat it as the issuer's own taxable base, with VAT charged on it. - [supplier_has_documents](https://docs.factuarea.com/errors/supplier_has_documents): The supplier is referenced by registered purchase invoices, and deleting it would leave those expenses without the party that issued them. - [supplier_not_found](https://docs.factuarea.com/errors/supplier_not_found): The identifier does not resolve to any supplier of the authenticated company. - [system_tax_default_modification_forbidden](https://docs.factuarea.com/errors/system_tax_default_modification_forbidden): Defaults of the shared catalogue taxes are not set on the tax itself: the catalogue is global and the preference belongs to your company. - [system_tax_immutable](https://docs.factuarea.com/errors/system_tax_immutable): The tax belongs to the canonical AEAT catalogue shipped with the product. Its rate, code and name are fixed so that every company shares the same fiscal reference. - [system_tax_immutable_field](https://docs.factuarea.com/errors/system_tax_immutable_field): The update touches a field that is frozen on a system tax; `error.param` names it. - [system_tax_undeletable](https://docs.factuarea.com/errors/system_tax_undeletable): System taxes are part of the shared fiscal catalogue and cannot be removed: deleting one would break the documents that reference it. - [tax_applies_to_invalid](https://docs.factuarea.com/errors/tax_applies_to_invalid): The scope of the tax is outside the catalogue `sale`, `purchase`, `both`. - [tax_code_already_exists](https://docs.factuarea.com/errors/tax_code_already_exists): Another tax of the catalogue already uses that code, and codes identify taxes unambiguously. - [tax_id_already_exists](https://docs.factuarea.com/errors/tax_id_already_exists): Another client of the company already holds that tax id, and the tax id identifies the party uniquely inside a company. - [tax_id_required](https://docs.factuarea.com/errors/tax_id_required): The operation needs the tax identification number (NIF, CIF or NIE) of the party involved and the record does not carry one. - [tax_in_use](https://docs.factuarea.com/errors/tax_in_use): The tax is referenced by documents, products or suppliers. Removing it would leave historical documents without their fiscal reference. - [tax_inactive_cannot_be_default](https://docs.factuarea.com/errors/tax_inactive_cannot_be_default): A deactivated tax cannot become the default, either globally or for a document type — it would offer a hidden default that no form can pick. - [tax_not_found](https://docs.factuarea.com/errors/tax_not_found): The identifier does not match any tax of the catalogue reachable by this company. - [tax_report_not_found](https://docs.factuarea.com/errors/tax_report_not_found): The identifier does not resolve to any tax report of the authenticated company. - [tax_report_type_invalid](https://docs.factuarea.com/errors/tax_report_type_invalid): The report type is outside the catalogue `modelo_303`, `modelo_347`, `modelo_130`. - [tax_type_invalid](https://docs.factuarea.com/errors/tax_type_invalid): The tax type is outside the catalogue `vat`, `retention`, `surcharge`, `other`. - [timeout_seconds_out_of_range](https://docs.factuarea.com/errors/timeout_seconds_out_of_range): `timeout_seconds` falls outside the range 1 to 30 seconds. - [too_many_auth_failures](https://docs.factuarea.com/errors/too_many_auth_failures): Too many failed authentication attempts arrived from the same address, so it is temporarily locked out to stop credential guessing. - [too_many_custom_headers](https://docs.factuarea.com/errors/too_many_custom_headers): The endpoint declares more than 20 custom headers. - [unknown_filter](https://docs.factuarea.com/errors/unknown_filter): A listing received a filter it does not know. The canonical v1 parsers report this as `parameter_unknown`; this code survives for endpoints that have not migrated yet. - [unsupported_api_version](https://docs.factuarea.com/errors/unsupported_api_version): The `Factuarea-Version` header is well formed but names a version outside the supported set. - [unsupported_format](https://docs.factuarea.com/errors/unsupported_format): The requested format is not available for this model: not every filing produces every output. - [unsupported_media_type](https://docs.factuarea.com/errors/unsupported_media_type): A request with a body declared a `Content-Type` other than `application/json`. - [verifactu_already_submitted](https://docs.factuarea.com/errors/verifactu_already_submitted): The invoice already has its registration record. Exactly one registration exists per invoice, so a second one would break the idempotency of the chain. - [verifactu_mode_invalid](https://docs.factuarea.com/errors/verifactu_mode_invalid): The mode is outside the catalogue `verifactu` / `no_verifactu`. - [verifactu_not_eligible](https://docs.factuarea.com/errors/verifactu_not_eligible): The invoice cannot be registered with AEAT right now: the company is not on VeriFactu mode, it has no active certificate, or the certificate is revoked or issued for a different tax id. - [verifactu_record_not_found](https://docs.factuarea.com/errors/verifactu_record_not_found): The identifier does not match any billing record of the authenticated company. - [verifactu_transmission_failed](https://docs.factuarea.com/errors/verifactu_transmission_failed): The transmission of the record to AEAT did not complete: the endpoint was unreachable or answered with an incident. - [webhook_delivery_not_found](https://docs.factuarea.com/errors/webhook_delivery_not_found): The identifier does not match any delivery attempt, or the delivery falls outside the retention window kept for the history. - [webhook_endpoint_degraded](https://docs.factuarea.com/errors/webhook_endpoint_degraded): The endpoint is degraded after repeated delivery failures, so test pings are refused while it stays in that state. - [webhook_endpoint_not_found](https://docs.factuarea.com/errors/webhook_endpoint_not_found): The identifier does not resolve to any webhook endpoint of the authenticated company. - [webhook_secret_recently_rotated](https://docs.factuarea.com/errors/webhook_secret_recently_rotated): The signing secret was rotated less than five minutes ago. The grace window lets your receiver accept both secrets during the switch; rotating again inside it would invalidate signatures still in flight. - [SDKs overview](https://docs.factuarea.com/sdks): Official TypeScript and PHP SDKs for the Factuarea API — install @factuarea/sdk or factuarea/factuarea-php and get retries, idempotency, cursor pagination, typed errors and webhook verification out of the box. - [PHP](https://docs.factuarea.com/sdks/php): Install factuarea/factuarea-php with Composer, authenticate, and create your first invoice. PSR-4, Guzzle-based, PHP 8.2+. - [TypeScript](https://docs.factuarea.com/sdks/typescript): Install @factuarea/sdk for Node.js, authenticate, and create your first invoice. Dual ESM + CommonJS, full type declarations, Node 20+. - [List all absence balances](https://docs.factuarea.com/api-reference/absence-balances/public-api.v1.absence-balances.list): List your company’s absence balances with cursor-based pagination. Each balance is the accrued, carried-over and consumed days of one employee for one absence type in a given year, with the resulting `available_days`. Supports filtering by `employee_id` (UUID v7), `absence_type_id` (UUID v7) and `year`. Day amounts are exact decimal strings. - [Retrieve an absence balance](https://docs.factuarea.com/api-reference/absence-balances/public-api.v1.absence-balances.show): 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). - [Get the team absence calendar](https://docs.factuarea.com/api-reference/absence-calendar/public-api.v1.absence-calendar.show): 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`. - [Archive an absence policy](https://docs.factuarea.com/api-reference/absence-policies/public-api.v1.absence-policies.archive): 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. - [Assign a policy to employees](https://docs.factuarea.com/api-reference/absence-policies/public-api.v1.absence-policies.assign): 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. Returns the policy with its updated assigned-employee count. - [List a policy’s assigned employees](https://docs.factuarea.com/api-reference/absence-policies/public-api.v1.absence-policies.assignments): List the employees assigned to this absence policy (their `employee_id` UUID v7 and name), as a flat list under `{ "data": [ … ] }`. - [Configure a policy’s year-end carryover](https://docs.factuarea.com/api-reference/absence-policies/public-api.v1.absence-policies.carryover): Configure how much unused balance carries over at year-end for this absence policy. `carryover_type` (`none`/`capped`/`unlimited`) is required; `carryover_max_days` is required and positive only when `carryover_type` is `capped`. Optional `carryover_expiry_month` (1..12) and `carryover_expiry_day` set when the carried-over balance expires. A policy belonging to another company returns 404 `absence_policy_not_found` (anti-enumeration). Returns the updated policy. - [Create an absence policy](https://docs.factuarea.com/api-reference/absence-policies/public-api.v1.absence-policies.create): Create an absence policy for the authenticated company (resolved from the API key, never from the payload). `name`, `allowance_type` (`limited`/`unlimited`) and `accrual_method` (`annual`/`monthly`) are required; `allowance_days` is required and positive only when `allowance_type` is `limited`. `absence_type_ids` is the list of absence type UUIDs (v7) the policy covers (may be empty); a type belonging to another company returns 422. Returns the created policy with its generated `id` (UUID v7). - [List all absence policies](https://docs.factuarea.com/api-reference/absence-policies/public-api.v1.absence-policies.list): 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. - [Retrieve an absence policy](https://docs.factuarea.com/api-reference/absence-policies/public-api.v1.absence-policies.show): 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). - [Unarchive an absence policy](https://docs.factuarea.com/api-reference/absence-policies/public-api.v1.absence-policies.unarchive): Unarchive an absence policy (transition `archived` → `active`), returning it to use. No request body. Returns 422 if it is already active. - [Unassign a policy from employees](https://docs.factuarea.com/api-reference/absence-policies/public-api.v1.absence-policies.unassign): 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. - [Update an absence policy](https://docs.factuarea.com/api-reference/absence-policies/public-api.v1.absence-policies.update): 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. - [Approve an absence request](https://docs.factuarea.com/api-reference/absence-requests/public-api.v1.absence-requests.approve): 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). Returns the updated request. - [Cancel an absence request](https://docs.factuarea.com/api-reference/absence-requests/public-api.v1.absence-requests.cancel): 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. - [Create an absence request](https://docs.factuarea.com/api-reference/absence-requests/public-api.v1.absence-requests.create): Create an absence request for the authenticated company (resolved from the API key, never from the payload). `employee_id` (UUID v7) is required — an API key acts as a system, so the target employee must be given. `absence_type_id` (UUID v7) and the `start_date`/`end_date` range (`YYYY-MM-DD`, end on or after start) are required; `note` is optional. The requested amount is computed in working days minus the applicable public holidays. If the absence type does not require approval it is auto-approved and consumes the balance. Returns the created request with its generated `id` (UUID v7). - [List all absence requests](https://docs.factuarea.com/api-reference/absence-requests/public-api.v1.absence-requests.list): 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`). - [Reject an absence request](https://docs.factuarea.com/api-reference/absence-requests/public-api.v1.absence-requests.reject): 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. - [Retrieve an absence request](https://docs.factuarea.com/api-reference/absence-requests/public-api.v1.absence-requests.show): 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). - [Archive an absence type](https://docs.factuarea.com/api-reference/absence-types/public-api.v1.absence-types.archive): 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. - [Create an absence type](https://docs.factuarea.com/api-reference/absence-types/public-api.v1.absence-types.create): 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). - [List all absence types](https://docs.factuarea.com/api-reference/absence-types/public-api.v1.absence-types.list): 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. - [Retrieve an absence type](https://docs.factuarea.com/api-reference/absence-types/public-api.v1.absence-types.show): Retrieve a single absence type by its `id` (UUID v7). A type belonging to another company returns 404 `absence_type_not_found` (anti-enumeration). - [Unarchive an absence type](https://docs.factuarea.com/api-reference/absence-types/public-api.v1.absence-types.unarchive): Unarchive an absence type (transition `archived` → `active`), returning it to use. No request body. Returns 422 if it is already active. - [Update an absence type](https://docs.factuarea.com/api-reference/absence-types/public-api.v1.absence-types.update): Partially update an absence type: only the fields present in the payload are changed; omitted fields keep their current value. Returns the updated type. - [Activate a managed company](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.activate): Reactivate a previously deactivated (`inactive`) managed company. Activation is gated by an atomic per-seat charge — in live mode the prorated seat is charged synchronously and the company only becomes `active` if the charge succeeds. No payment method on file returns 402, and a plan without the gestoría module returns 403. Trial, enterprise and test keys skip the charge. - [Activate several managed companies](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.activate_batch): Reactivate several deactivated (`inactive`) managed companies in one operation, charging the combined prorated seats in a single invoice. Pass `company_ids`. The gate is atomic: every company is validated (ownership and `inactive` status) before any charge, so if one is invalid the whole batch is rejected without charging or activating any. - [Create a child API key](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.api_keys.create): Create an API key scoped to one of your managed companies and return its plaintext `secret` exactly once — store it now, it cannot be retrieved later. The requested scopes must be a subset of the calling key's scopes; requesting a scope the parent key does not hold returns 422 (no silent narrowing). - [List child API keys](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.api_keys.list): List the API keys of one of your managed companies with cursor-based pagination, including revoked keys for audit. The plaintext secret is never returned. A company not managed by your master tenant returns 404. - [Revoke a child API key](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.api_keys.revoke): Revoke a child API key immediately and irreversibly, leaving it unusable. Subsequent requests authenticated with that key fail with 401. A company not managed by your master tenant returns 404. - [Rotate a child API key secret](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.api_keys.rotate_secret): Invalidate the current secret of a child API key immediately, generate a fresh `prefix` + `secret`, and return the new secret in plaintext exactly once. Any request made with the previous secret stops authenticating right away. Irreversible. A company not managed by your master tenant returns 404. - [Retrieve a child API key](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.api_keys.show): Retrieve a single API key of one of your managed companies by its `id` (UUID v7). The plaintext secret is never included. A key not belonging to a company you manage returns 404 `api_key_not_found` (anti-enumeration). - [Create a managed company](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.create): Register a new managed company (a child sub-account) under your master tenant — the gestoría model. `name` and `tax_id` are required, and `tax_id` must be unique among the companies you manage (a duplicate returns 409). In live mode the prorated per-seat charge gates creation: with no payment method on file or a failed charge the call returns 402 and nothing is created. Use `GET /v1/companies/seat-charge-preview` to anticipate the cost; test keys skip the charge. - [Retrieve the creation status of a managed company](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.creation_status): Poll the provisioning lifecycle of a managed company. Returns `provisioning_status` (`pending`, `awaiting_payment`, `provisioning`, `active`, `failed`). `payment_setup_url` is present only while `awaiting_payment` and points to the master tenant's payment-method onboarding; `failed_reason` is present only when provisioning has `failed`. Test keys move the child to `active` directly. - [Deactivate a managed company](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.deactivate): Deactivate a managed company, moving it from `active` to `inactive`: it becomes non-operational but its data is preserved and the change is reversible (reactivate it later by paying its seat). No charge is applied; instead a prorated seat credit is emitted best-effort for the unused time. - [Archive a managed company](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.delete): Archive a managed company, moving it to the `archived` status so it no longer accepts operations. The underlying company row and its history are preserved. Archiving may be blocked by business rules (returns 422 `business_rule_violation`). A company not managed by your master tenant returns 404. - [List your managed companies](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.list): List the companies managed by your master tenant with cursor-based pagination. By default only `active` and `inactive` companies are returned; pass `status` (`active`, `inactive`, `archived`) to filter — `status=archived` is the opt-in way to surface archived companies. Only your own children are ever returned. - [Preview the seat charge of adding a company](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.seat_charge_preview): Preview the prorated per-seat amount for adding or activating managed companies, computed from the master tenant's Stripe upcoming invoice, without charging. Use `count` (≥1) to preview a batch, or `company_ids` for a coverage-aware preview: companies still covered for the current period cost `0` (`already_covered: true`). `amount` is in the currency's minor units; `requires_payment_method` is `true` when no payment method is on file. - [Retrieve a managed company](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.show): Retrieve a single managed company by its `id` (UUID v7). A company not managed by your master tenant returns 404 `company_not_found` (anti-enumeration). - [Update a managed company](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.update): Update the profile of a managed company (`name`, `business_name`, address fields, `email`, `phone`). The `tax_id` is immutable after creation (sending it returns 422) and `country_aeat_zone` is derived from the address. Partial update: omitted fields keep their value; send `""` to clear a field. - [Verify the creation of a managed company](https://docs.factuarea.com/api-reference/companies/public-api.v1.companies.verify_creation): Reconcile and advance the provisioning of a managed company against the master tenant's subscription. No request body; idempotent. While `awaiting_payment`, once the master has a payment method on file the child is charged the prorated seat and moves to `active`; otherwise it stays `awaiting_payment` with no error. Returns the creation-status resource. - [Retrieve the consolidated workforce compliance overview](https://docs.factuarea.com/api-reference/companies/public-api.v1.gestoria.workforce_summary): Return the consolidated time-tracking compliance panel for your whole managed portfolio: one row per `active` managed company, each projected from that company's latest monthly close without recomputation — whether the current (last closable) period is closed, its status (`closed`/`reopened`), the last closed period (`last_closed_year`/`last_closed_month`), and the aggregated `total_balance_minutes`, `total_overtime_minutes` and `employee_count`. Master-scoped: the portfolio is resolved from your API key, never from the payload, and only your own children appear. Unlike the per-company `X-Active-Profile` endpoints, this aggregates across children in a single call. Returned as `{ "data": [ConsolidatedWorkforce, ...] }`. - [List your API request logs](https://docs.factuarea.com/api-reference/developers/public-api.v1.developers.request_logs.list): Inspect the requests your own integration has made against this API, newest first, so you can debug it without opening a support ticket: what you called, what came back, how long it took and, when a call failed, the error it returned. Scoped to the authenticated company. Rows are purged after 30 days, so this is a debugging window, not an audit trail. - [Retrieve an API request log](https://docs.factuarea.com/api-reference/developers/public-api.v1.developers.request_logs.show): Retrieve a single request of your own integration by the `request_id` the API returned in the `X-Request-Id` header of that response — the identifier you already have in hand when a call misbehaved, and the one to quote in a support request. It is an opaque `req_…` string, not a UUID v7. The body carries the same fields as the listing. - [Summarize email delivery per document](https://docs.factuarea.com/api-reference/emails/public-api.v1.emails.indicators): Answer "did the email for these documents go out?" for a whole batch at once, instead of paging through the deliveries of each one: per document, how many emails were sent, the last status, the last hand-off and how many failed. Ideal to paint a "sent / not sent" column over a page of invoices in a single call. IMPORTANT — `last_status` and `last_sent_at` describe the hand-off to the OUTGOING SMTP SERVER, not real delivery: a `sent` email may still bounce afterwards without the platform observing it. - [List sent emails](https://docs.factuarea.com/api-reference/emails/public-api.v1.emails.list): Browse the emails your company has sent through the platform — invoices, quotes, pro formas, delivery notes, payment reminders — newest first, so you can answer "did the email for this invoice actually go out?" without asking your customer. Scoped to the authenticated company. IMPORTANT — `status` describes the hand-off to the OUTGOING SMTP SERVER, not real delivery: `sent` means the outgoing mail server accepted the message, not that the recipient received it. - [Retrieve a sent email](https://docs.factuarea.com/api-reference/emails/public-api.v1.emails.show): Retrieve one email by its id, typically after finding it in the listing, to investigate what happened to it: recipient, subject, status, attempts, the error message when it failed, and the document it was sent for. Scoped to the authenticated company. IMPORTANT — `status` describes the hand-off to the OUTGOING SMTP SERVER, not real delivery: `sent` means the outgoing mail server accepted the message, not that the recipient received it. - [Cancel an employee invitation](https://docs.factuarea.com/api-reference/employees/public-api.v1.employee-invitations.cancel): 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. - [List employee invitations](https://docs.factuarea.com/api-reference/employees/public-api.v1.employee-invitations.list): 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. - [Resend an employee invitation](https://docs.factuarea.com/api-reference/employees/public-api.v1.employee-invitations.resend): 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, and 404 if it does not exist in your company. - [Send an employee invitation](https://docs.factuarea.com/api-reference/employees/public-api.v1.employee-invitations.send): Invite a person to join your company as an employee (Control Horario portal). Only `email` is required — the `employee` role is fixed by the server, never taken from the payload. The invited person receives an email with an acceptance link. Inviting an email that already belongs to a company user, or one that already has a pending invitation, returns 422. Employee invitations do not consume the plan `users` seat limit. - [Cancel the employee seat add-on](https://docs.factuarea.com/api-reference/employees/public-api.v1.employee-seats.cancel): Cancel the per-employee billing add-on: the `employee-seats` subscription is cancelled at period end (the current month is already paid) and the per-employee coverage is purged. The plan subscription is never touched. Returns the resulting billing status, where `subscribed` stays `true` until the period ends. - [Sync the employee seat quantity](https://docs.factuarea.com/api-reference/employees/public-api.v1.employee-seats.change-quantity): Reconcile the seat quantity of the add-on to the real number of active employees (SET with `proration_behavior: none`, no invoice). Idempotent: when the quantity already matches it is a no-op. Returns the resulting billing status. - [Preview the employee seat charge](https://docs.factuarea.com/api-reference/employees/public-api.v1.employee-seats.preview): Preview the prorated per-seat amount for activating or hiring employees, computed from the Stripe upcoming invoice of the `employee-seats` subscription, without charging. Use `count` (≥1, up to 1000) for a batch preview, or `employee_ids` (UUID v7) for a coverage-aware preview: employees still covered for the current period cost 0 (`already_covered: true`). `amount` is the taxable base in cents; `requires_payment_method` is `true` when no payment method is on file. Never throws — it degrades to a neutral preview. - [Retrieve employee seat billing status](https://docs.factuarea.com/api-reference/employees/public-api.v1.employee-seats.status): Return the billing status of the per-employee add-on for your company: whether the `employee-seats` subscription is active, how many seats are billed (`quantity`), how many employees are active, and the recurring per-seat cost with VAT. Amounts are in the currency minor units (cents) and are `null` when the cost is not resolvable (not subscribed, no active plan, enterprise outside Stripe, sandbox) — never a misleading 0. `seats_billable` tells whether your plan MUST be paying per seat, independently of `subscribed`: `subscribed: false` with `seats_billable: true` and active employees is a billing anomaly, while `seats_billable: false` is a legitimate no-charge state (enterprise by contract, trial or sandbox). Employees never count towards the plan `users` seat limit. - [Subscribe to the employee seat add-on](https://docs.factuarea.com/api-reference/employees/public-api.v1.employee-seats.subscribe): Opt in to the per-employee billing add-on: create the dedicated monthly `employee-seats` subscription with `quantity` set to the number of active employees, charging the first period with the payment method on file. The charge is atomic — with no payment method it returns 402 `employee_seat_payment_method_required` (the envelope carries `error.details.payment_setup_url`), and a declined charge returns 402 `employee_seat_charge_failed`; in both cases nothing is subscribed. Returns the resulting billing status. - [Create an employee](https://docs.factuarea.com/api-reference/employees/public-api.v1.employees.create): Register a new employee for the authenticated company (resolved from the API key, never from the payload). `first_name`, `last_name`, `email`, `employment_type` (`full_time`/`part_time`), `contract_hours`, `hire_date` and `ccaa` are required; `tax_id` and `job_title` are optional. Returns the created employee with its generated `id` (UUID v7). Active employees count towards the workforce module seat billing. - [Deactivate an employee](https://docs.factuarea.com/api-reference/employees/public-api.v1.employees.deactivate): 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. - [Find an employee by external ID](https://docs.factuarea.com/api-reference/employees/public-api.v1.employees.find_by_external_id): 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. - [List all employees](https://docs.factuarea.com/api-reference/employees/public-api.v1.employees.list): 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. - [Reactivate an employee](https://docs.factuarea.com/api-reference/employees/public-api.v1.employees.reactivate): 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. - [Retrieve an employee](https://docs.factuarea.com/api-reference/employees/public-api.v1.employees.show): Retrieve a single employee by its `id` (UUID v7). An employee belonging to another company returns 404 `employee_not_found` (anti-enumeration). - [Get employee stats](https://docs.factuarea.com/api-reference/employees/public-api.v1.employees.stats): 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 }`. - [Update an employee](https://docs.factuarea.com/api-reference/employees/public-api.v1.employees.update): Update an employee. Partial update: only fields present in the payload are modified; omitted fields keep their value. `hire_date` is immutable. Returns the updated employee. - [List all holidays](https://docs.factuarea.com/api-reference/holidays/public-api.v1.holidays.list): List the public holidays visible to your company with cursor-based pagination: global reference holidays (national and per autonomous community, seeded and read-only) plus your custom local holidays. Supports filtering by `year`, `ccaa` (ISO 3166-2:ES autonomous community), `scope` (`national`/`autonomic`/`local`) and `source` (`reference` for seeded rows, `custom` for your own). - [Resolve applicable holidays](https://docs.factuarea.com/api-reference/holidays/public-api.v1.holidays.resolve): 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. - [Retrieve a holiday](https://docs.factuarea.com/api-reference/holidays/public-api.v1.holidays.show): Retrieve a single holiday by its `id` (UUID v7). A custom holiday belonging to another company returns 404 `holiday_not_found` (anti-enumeration). - [List integration events](https://docs.factuarea.com/api-reference/integration-events/public-api.v1.integrations.events.list): 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. - [Replay a parked integration event](https://docs.factuarea.com/api-reference/integration-events/public-api.v1.integrations.events.replay): Reprocess a gateway event that was parked, once the cause that prevented it from producing its effect is gone. **Before you call it** - The event must be published with `is_replayable` set to `true` — anything else returns 422. - Fix the cause first: turn automatic invoicing back on, re-link the connected account, wait for the exchange rate. - It needs the write scope `integration_events:write`, never the read scope of the inbox. **What it can do** > **This action can have real fiscal consequences.** If the cause is already resolved, the replay CAN ISSUE A REAL INVOICE, with its series number and its registration in VeriFactu. Confirm with the account owner before calling it. **What comes back** - `202` means accepted and queued, **not** completed. - The body returns the event as it stands now, not the outcome of the retry. - The outcome appears as a NEW event in the inbox — poll `GET /v1/integrations/events` to see how it ended. - It never duplicates invoices: the replay goes through the same idempotency check as the original attempt. - [Retrieve an integration event](https://docs.factuarea.com/api-reference/integration-events/public-api.v1.integrations.events.show): 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. - [Close a monthly time record](https://docs.factuarea.com/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.create): Freeze the immutable monthly close of the time record register for a finished `(year, month)`: it snapshots each active employee’s balance totals and absence breakdown/balances (reusing the balance contract, never recomputing) and locks the period against retroactive entries and corrections. `year` and `month` (1-12) are required. A month that has not ended yet returns 422 in Spanish; a period already closed returns 409. Reopening a previously reopened period re-closes it, keeping its original `id`. Returns 201 with the created close and a `Location` header. - [Download the closed register (RD-ley 8/2019)](https://docs.factuarea.com/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.export): 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. - [List all monthly time record closes](https://docs.factuarea.com/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.list): 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. - [Reopen a monthly time record close](https://docs.factuarea.com/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.reopen): 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. - [Retrieve the report of a closed period](https://docs.factuarea.com/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.report): Return the monthly report of a closed period by the close `id` (UUID v7), read from the frozen snapshot without recomputation, so the totals never drift from the sheet at the moment of closing. It holds the company aggregate totals and one row per employee with totals, absence breakdown and balances, and the daily detail. Totals are in minutes. A period without a close returns 404. A computed resource: it exposes `close_id`, never an `id` of its own. - [Seal a monthly time record register](https://docs.factuarea.com/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.seal): Seal (digitally sign) a `closed` monthly time record register by the close `id` (UUID v7): it freezes a canonical SHA-256 digest of the close snapshot and a detached RSA-SHA256 signature made with the company certificate, so the register is tamper-evident and independently verifiable. A close that is not `closed` returns 422 in Spanish, a period already sealed returns 409 (one seal per close, no re-sealing), and a company without an active usable certificate returns 422. A close belonging to another company returns 404. Returns 201 with the seal (including its live verification state) and a `Location` header. - [Retrieve the seal of a monthly register](https://docs.factuarea.com/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.seal_show): Retrieve the digital seal of a monthly time record register by the close `id` (UUID v7), together with its verification state recomputed live against the current snapshot: `verified` is `true` when the snapshot and the signature are intact, otherwise `verification_reason` explains the mismatch (`snapshot_mismatch`, `signature_invalid` or `certificate_unreadable`). The seal exposes its digest, signature and signing certificate so a third party can verify it. A close without a seal — or belonging to another company — returns 404 `monthly_register_signature_not_found` (anti-enumeration). - [Retrieve a monthly time record close](https://docs.factuarea.com/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.show): 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). - [Download the payroll export of a closed month](https://docs.factuarea.com/api-reference/payroll-exports/public-api.v1.monthly_time_record_closes.payroll_export): Download the payroll incidents file of a closed month in the format of a Spanish payroll software (`a3` for A3 Wolters Kluwer, `sage` for Sage, `nominasol` for NominaSOL), read from the frozen snapshot of the monthly close without recomputation. Each row is one employee with their fiscal identity (tax ID and name), worked vs expected minutes, overtime, balance and the approved absences broken down by type. `format` is optional and defaults to `a3`; a format outside the catalog returns 422. A period without a close returns 404. The response is a binary spreadsheet download. - [List the supported payroll export formats](https://docs.factuarea.com/api-reference/payroll-exports/public-api.v1.payroll_export_formats.list): 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. - [List office/remote presence declarations](https://docs.factuarea.com/api-reference/presence/public-api.v1.presence.daily): 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 app (SPA-only). - [Get the live team presence](https://docs.factuarea.com/api-reference/presence/public-api.v1.presence.live): Return the live presence panel of your team for the Control Horario (time tracking) module: one `employee_presence` item per active employee, with the workday state derived from the immutable time record ledger (`working`/`paused`/`finished`/`away`), the late-arrival flag (first clock-in vs planned start) and the office/remote location declared today. A computed read-only resource: each item exposes the employee UUID v7 as its `id`, never a presence record id. No filters or pagination. - [Retrieve an employee’s live presence](https://docs.factuarea.com/api-reference/presence/public-api.v1.presence.show): 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`. - [List Stripe payouts](https://docs.factuarea.com/api-reference/stripe/public-api.v1.payouts.list): 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. - [Retrieve a Stripe payout](https://docs.factuarea.com/api-reference/stripe/public-api.v1.payouts.show): 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. - [Disconnect a connected Stripe account](https://docs.factuarea.com/api-reference/stripe/public-api.v1.stripe_autoinvoicing.accounts.disconnect): 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. - [List connected Stripe accounts](https://docs.factuarea.com/api-reference/stripe/public-api.v1.stripe_autoinvoicing.accounts.list): List the connected Stripe accounts (Stripe Connect, multi-store) for your company. Each exposes its `id`, `name`, `external_account_id` (`acct_xxx`), the assigned `series_id`, its per-account configuration (`autoinvoicing_enabled`, `simplified_threshold_cents`, `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`), `status` and `connected_at`. Charges are auto-invoiced with that account's series and configuration. - [Retrieve a connected Stripe account](https://docs.factuarea.com/api-reference/stripe/public-api.v1.stripe_autoinvoicing.accounts.show): 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. - [Update a connected Stripe account](https://docs.factuarea.com/api-reference/stripe/public-api.v1.stripe_autoinvoicing.accounts.update): Update a connected Stripe account: its `name`, the auto-invoicing `series_id` (`null` clears it, falling back to the company default series) and the per-account fiscal policy (`autoinvoicing_enabled`, `simplified_threshold_cents`, `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`). All fields are optional; omitted ones keep their value. - [Retrieve Stripe autoinvoicing config](https://docs.factuarea.com/api-reference/stripe/public-api.v1.stripe_autoinvoicing.config.show): Return the Stripe Connect integration state and auto-invoicing configuration: whether Stripe is connected and enabled, the series used, the plan gating, and the fiscal policy (`simplified_threshold_cents`, `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`). With multiple connected accounts it returns 422 `per_account_config_required` — read each via `GET /v1/connected-accounts`. - [Update Stripe autoinvoicing config](https://docs.factuarea.com/api-reference/stripe/public-api.v1.stripe_autoinvoicing.config.update): Enable or disable auto-invoicing of Stripe Connect charges and choose the series used. Optionally tune the fiscal policy (`simplified_threshold_cents` in cents [0, 300000], `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`); omitted fields keep their value. With multiple connected accounts it returns 422 `per_account_config_required` — configure each account individually. - [List Stripe autoinvoiced correctives](https://docs.factuarea.com/api-reference/stripe/public-api.v1.stripe_autoinvoicing.correctives.list): 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. - [List Stripe autoinvoiced charges](https://docs.factuarea.com/api-reference/stripe/public-api.v1.stripe_autoinvoicing.payments.list): 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`). - [Retrieve an employee’s time balance for a period](https://docs.factuarea.com/api-reference/time-balances/public-api.v1.time_balances.employee): Return the time balance of an arbitrary period of an employee: expected vs worked minutes, the balance and overtime per day, and the period totals. The employee is the `{employee}` (UUID v7) in the path; `from` and `to` (`YYYY-MM-DD`) are required. This is the same contract the monthly close reuses over closed periods. A range where `to` is before `from` returns 422. Totals are in minutes. A computed resource: it exposes `employee_id`, never an `id`. - [Retrieve an employee’s monthly time sheet](https://docs.factuarea.com/api-reference/time-balances/public-api.v1.time_balances.monthly_sheet): Return the live monthly time sheet of an employee for the open (in-progress) period: expected vs worked minutes, the balance and overtime per day, and the monthly totals. `employee_id` (UUID v7) is required; `month` (`YYYY-MM`) defaults to the current month. The sheet is recomputed on every request from the immutable ledger, so a just-recorded clock entry is reflected without closing the month. Expected minutes discount public holidays and approved absences. Totals are in minutes. A computed resource: it exposes `employee_id`, never an `id`. - [Retrieve the team time balance summary](https://docs.factuarea.com/api-reference/time-balances/public-api.v1.time_balances.team_summary): Return the team time balance summary (manager view) for a month: one row per active employee with their expected, worked, balance and overtime minutes. `month` (`YYYY-MM`) defaults to the current month. Only active employees with a schedule are included. Totals are in minutes. A computed resource with no `id`. - [Approve a time entry correction](https://docs.factuarea.com/api-reference/time-corrections/public-api.v1.time_corrections.approve): Approve a pending correction request by its `id` (UUID v7), appending the resolving `correction_entry` linked to the original time entry. An optional `note` from the approver may be supplied. A request that is not pending returns 422 (already resolved), and approving your own request returns 422 (self-approval is forbidden). Returns 200 with the resolved correction. - [Request a time entry correction](https://docs.factuarea.com/api-reference/time-corrections/public-api.v1.time_corrections.create): Request the correction of a time entry (RD-ley 8/2019). `time_entry_id` (UUID v7 of the entry to correct), `kind` (`add_missing_entry`/`adjust_time`/`remove_entry`), a `reason` and the `proposed` values are required. A correction is a new append-only entry that references the original entry without mutating it (analogous to a corrective invoice); the workflow stays `pending` until a manager approves or rejects it. Returns 201 with the created request and a `Location` header. - [List all time entry corrections](https://docs.factuarea.com/api-reference/time-corrections/public-api.v1.time_corrections.list): 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`). - [Reject a time entry correction](https://docs.factuarea.com/api-reference/time-corrections/public-api.v1.time_corrections.reject): 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. - [Retrieve a time entry correction](https://docs.factuarea.com/api-reference/time-corrections/public-api.v1.time_corrections.show): 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). - [Validate the time record hash chain](https://docs.factuarea.com/api-reference/time-entries/public-api.v1.time_entries.chain.validate): Recompute the SHA-256 hash chain (`huella`) of your company time record ledger and compare it against the persisted values without mutating data. Returns whether the chain is intact and, if not, the `id` (UUID v7) of the first corrupted record — the fingerprints themselves are never exposed. Rate-limited to 1 request/minute and rejected with 422 `dataset_too_large` for datasets over 50,000 records. - [Clock in an employee](https://docs.factuarea.com/api-reference/time-entries/public-api.v1.time_entries.clock_in): Clock the start of an employee’s workday, opening a new work span. `employee_id` (UUID v7) and `source` (`web`/`mobile`) are required; `occurred_at` defaults to the server time. Valid only when the employee is not already clocked in; an invalid transition returns 422 in Spanish. Returns 201 with the created `clock_in` entry. - [Clock out an employee](https://docs.factuarea.com/api-reference/time-entries/public-api.v1.time_entries.clock_out): 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. - [Retrieve an employee’s current workday state](https://docs.factuarea.com/api-reference/time-entries/public-api.v1.time_entries.current): 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. - [List all time entries](https://docs.factuarea.com/api-reference/time-entries/public-api.v1.time_entries.list): 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`). - [Record a manual retroactive entry](https://docs.factuarea.com/api-reference/time-entries/public-api.v1.time_entries.manual): Record a past work span for an employee (a retroactive manual entry). `employee_id` (UUID v7), `started_at`, `ended_at` and a `reason` are required; optional `pauses` add pause intervals. The entries are stored with `is_retroactive: true` and `source: manual`, and one audit log entry is written. `ended_at` before `started_at`, or a missing reason, returns 422 in Spanish. Returns 201 with the created span’s `clock_out` entry. - [Start a pause](https://docs.factuarea.com/api-reference/time-entries/public-api.v1.time_entries.pause): 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. - [Resume from a pause](https://docs.factuarea.com/api-reference/time-entries/public-api.v1.time_entries.resume): 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. - [Retrieve a time entry](https://docs.factuarea.com/api-reference/time-entries/public-api.v1.time_entries.show): 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). - [Retrieve the time tracking settings](https://docs.factuarea.com/api-reference/time-tracking-settings/public-api.v1.time_tracking_settings.show): 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. - [Update the time tracking settings](https://docs.factuarea.com/api-reference/time-tracking-settings/public-api.v1.time_tracking_settings.update): Create or update the time tracking configuration of your company: `overtime_basis` (`weekly`/`daily`), the optional daily/weekly overtime thresholds in minutes (`null` derives them from the schedule), the rounding `overtime_tolerance_minutes`, and the clock-in reminder toggle and grace minutes. A negative threshold or tolerance returns 422 in Spanish. Returns the updated settings with `id` = UUID v7 of the row. - [Archive a work schedule](https://docs.factuarea.com/api-reference/work-schedules/public-api.v1.work_schedules.archive): 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. - [Assign a schedule to an employee](https://docs.factuarea.com/api-reference/work-schedules/public-api.v1.work_schedules.assign): Assign the work schedule to an employee with an effective start date. `employee_id` (UUID v7, must belong to your company) and `effective_from` (`Y-m-d`) are required. Assigning closes the employee’s previously open assignment and opens the new one (an employee has at most one open assignment; history is preserved). An unknown employee returns 422 `assigned_employee_not_found`; an unknown schedule returns 404. Returns the created assignment. - [List a schedule’s assignments](https://docs.factuarea.com/api-reference/work-schedules/public-api.v1.work_schedules.assignments): List the employees with an open assignment (`effective_to` = null) to this work schedule, as a flat list under `{ "data": [ … ] }`. - [Create a work schedule](https://docs.factuarea.com/api-reference/work-schedules/public-api.v1.work_schedules.create): Create a weekly work schedule for the authenticated company (resolved from the API key, never from the payload). `name` and `week_pattern` are required; `mode` defaults to `validated`. The `week_pattern` is a list of weekdays (ISO 8601 1..7) each with its ordered, non-overlapping `HH:MM` time ranges (an empty `ranges` means a rest day). Returns the created schedule with its generated `id` (UUID v7); `weekly_hours` is derived from the pattern. - [Get an employee’s current schedule](https://docs.factuarea.com/api-reference/work-schedules/public-api.v1.work_schedules.employee_schedule): Resolve the work schedule currently in effect (today) for an employee by its `id` (UUID v7). Returns 404 `schedule_assignment_not_found` when the employee has no schedule in effect (or belongs to another company). The result is the resolved schedule (`id` = UUID v7 of the schedule), not the assignment. - [List all work schedules](https://docs.factuarea.com/api-reference/work-schedules/public-api.v1.work_schedules.list): 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. - [Retrieve a work schedule](https://docs.factuarea.com/api-reference/work-schedules/public-api.v1.work_schedules.show): Retrieve a single work schedule by its `id` (UUID v7). A schedule belonging to another company returns 404 `work_schedule_not_found` (anti-enumeration). - [Get work schedule stats](https://docs.factuarea.com/api-reference/work-schedules/public-api.v1.work_schedules.stats): 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": … }`. - [Unarchive a work schedule](https://docs.factuarea.com/api-reference/work-schedules/public-api.v1.work_schedules.unarchive): Unarchive a work schedule (transition `archived` → `active`), returning it to use. No request body. Returns 422 if it is already active. - [Unassign a schedule from an employee](https://docs.factuarea.com/api-reference/work-schedules/public-api.v1.work_schedules.unassign): Close the employee’s open assignment to this schedule. `employee_id` (UUID v7) is required; `effective_to` (`Y-m-d`) is optional and defaults to today. Returns 404 when there is no open assignment. Responds 204 No Content. - [Update a work schedule](https://docs.factuarea.com/api-reference/work-schedules/public-api.v1.work_schedules.update): Fully replace a work schedule: `name`, `mode` and the complete `week_pattern` are required (there is no partial update of the pattern). `weekly_hours` is recomputed from the new pattern. Returns the updated schedule. - [All error codes](https://docs.factuarea.com/guides/errors/all): Complete reference of every public API error code, grouped by bounded context, with its HTTP status and type. - [FAQ](https://docs.factuarea.com/es/faq): Respuestas rápidas a las preguntas que más surgen al integrar la API pública de Factuarea — claves, modo de prueba, dinero, fechas, idempotencia y límites de peticiones. - [API de Factuarea](https://docs.factuarea.com/es): La API REST de Factuarea para automatizar tu SaaS de facturación multi-tenant para empresas españolas. - [Precios y límites de la API](https://docs.factuarea.com/es/pricing): Qué cuesta la API, qué tier otorga cada plan y los topes por tier de peticiones, API keys y endpoints de webhook. - [Soporte](https://docs.factuarea.com/es/support): Cómo contactar con el equipo de la API de Factuarea, qué incluir al reportar un problema, cómo funciona el acceso a la API, la página de estado y el changelog. - [Launch](https://docs.factuarea.com/es/changelog/launch): El lanzamiento de la plataforma pública de Factuarea — la API REST v1 (413 operaciones en 37 recursos), los SDKs oficiales de TypeScript y PHP, el CLI, el servidor MCP para agentes de IA, el cumplimiento fiscal español, los pagos y la operativa de empresas gestionadas, todo con un sandbox de prueba. - [Agentes y scripting](https://docs.factuarea.com/es/cli/agents): El contrato agent-first del CLI factuarea — JSON estable por stdout, errores estructurados por stderr, exit codes semánticos, el manifiesto commands --json, scope-check local y confirmación tipada de operaciones irreversibles. - [Devloop](https://docs.factuarea.com/es/cli/devloop): Prueba los webhooks de Factuarea en local sin desplegar ni ngrok — factuarea listen reenvía los eventos de tu cuenta a localhost con un cuerpo firmado, factuarea trigger produce eventos reales en sandbox. - [Resumen del CLI](https://docs.factuarea.com/es/cli): Instala y autentica el CLI oficial factuarea — maneja la API REST v1 desde tu terminal con brew, npm o un instalador curl. Agent-first, inspirado en Stripe. - [Uso](https://docs.factuarea.com/es/cli/usage): El árbol de comandos de factuarea — list, show, create, acciones de dominio, descargas binarias, subidas multipart, el escape hatch genérico api y el manifiesto commands --json. - [Ausencias](https://docs.factuarea.com/es/guides/absences): Configura tipos y políticas de ausencia, gestiona las solicitudes y lee los saldos y el calendario de equipo sobre la API v1. - [Personalización de la cuenta](https://docs.factuarea.com/es/guides/account-personalization): Fija el idioma de emisión de facturas, la plantilla PDF y el color de acento de tu cuenta — y léelos desde el recurso Account. - [Actuar en nombre de una hija](https://docs.factuarea.com/es/guides/acting-on-behalf): Maneja cualquier empresa hija desde una sola master key con el header X-Active-Profile — resolución del perfil, el guard de propiedad y cómo los scopes se mantienen fijos. - [Importes y fechas](https://docs.factuarea.com/es/guides/amounts-and-dates): Cómo representa la API el dinero (EUR, dos decimales), las fechas (YYYY-MM-DD), los timestamps (ISO-8601) y la zona horaria Europe/Madrid usada para el reinicio de cuotas. - [Anular o rectificar](https://docs.factuarea.com/es/guides/annul-vs-correct): Cuatro operaciones parecen «deshacer una factura» y solo una es correcta en cada caso — eliminar, cancelar, anular y rectificar. Si eliges mal, pierdes un documento fiscal o presentas una declaración que no pretendías. - [API keys (autoservicio)](https://docs.factuarea.com/es/guides/api-keys): Lista, crea, rota y revoca tus API keys desde la API v1 — el secret se muestra una vez, los environments son live/test y el tier lo deriva tu plan. - [Autenticación](https://docs.factuarea.com/es/guides/authentication): API keys con prefijos fact_live_ / fact_test_, scopes granulares, rotación con periodo de gracia y lista de acceso por IP. - [Operaciones en lote](https://docs.factuarea.com/es/guides/bulk-operations): Contrato de éxito parcial para endpoints bulk — total, successful, failed y una lista failures por fila. - [Verificación censal AEAT](https://docs.factuarea.com/es/guides/census-verification): Contrasta el par razón social + NIF de tu empresa — y el de tus clientes — contra el censo de la AEAT antes de emitir facturas VeriFactu — estados deterministas, NIFs mágicos del sandbox y comportamiento fail-open. - [API keys de empresas hijas](https://docs.factuarea.com/es/guides/child-api-keys): Emite, rota y revoca API keys acotadas a una sola empresa hija, derivando sus scopes de la key llamante — los endpoints api_keys bajo una empresa gestionada. - [Empresas gestionadas](https://docs.factuarea.com/es/guides/companies): Da de alta, aprovisiona y opera empresas hijas bajo tu tenant maestro — el modelo de gestoría desde la API v1, con cobro per-seat y un ciclo de vida activa/desactivada. - [Facturas rectificativas](https://docs.factuarea.com/es/guides/corrective-invoices): De R1 a R5, sustitución frente a diferencias, y cómo se construyen las líneas de una rectificativa — las cuatro decisiones que determinan lo que reciben de verdad la AEAT y la declaración de IVA. - [Suplidos](https://docs.factuarea.com/es/guides/disbursements): El dinero que pagas por cuenta de tu cliente —tasas judiciales, aranceles registrales, visados— no es ingreso tuyo. Cómo facturarlo para que quede fuera de tu base imponible, de tu IVA y de tu declaración anual de operaciones con terceros. - [Facturación de asientos de empleado](https://docs.factuarea.com/es/guides/employee-seats): El add-on de facturación por empleado — una suscripción mensual dedicada cuyo número de asientos sigue a tus empleados activos, con un asiento pagado que cubre todo el periodo. - [Eventos](https://docs.factuarea.com/es/guides/events): Objetos event de solo lectura con un id opaco. Consulta histórica vía la API y entrega por webhook. - [Exportación e importación](https://docs.factuarea.com/es/guides/export-and-import): Exporta facturas a una hoja de cálculo Excel/CSV (SUMMARY o ITEMS, con tope de 5000) e importa clientes desde un CSV con previsualización dry-run, mapeo de columnas, plantilla descargable y partial-success. - [Facturación FACe (B2G)](https://docs.factuarea.com/es/guides/face-invoicing): Envía facturas FacturaE 3.2.2 a FACe — códigos DIR3, XML firmado XAdES-EPES, estados de tramitación, anulación, simulación en sandbox y el scope facturae:write. - [Recetario fiscal](https://docs.factuarea.com/es/guides/fiscal-cookbook): Seis recetas de extremo a extremo — emitir y esperar la aceptación de la AEAT, corregir un importe, sustituir facturas simplificadas, repercutir un suplido, facturar fuera de la UE y reparar un registro rechazado. - [Ejemplos fiscales de factura](https://docs.factuarea.com/es/guides/fiscal-invoice-examples): Los 21 escenarios fiscales españoles de facturación, cuáles cuatro de ellos se publican como ejemplos de request listos para enviar en la Referencia de la API y un ejemplo de rectificativa por cada código R de la AEAT (R1–R5). - [Glosario](https://docs.factuarea.com/es/guides/glossary): Términos fiscales y de dominio españoles usados en toda la API de Factuarea — NIF, VeriFactu, AEAT, FacturaE, Modelo 303/347, series, rectificativa, huella, CSV y más. - [Idempotencia](https://docs.factuarea.com/es/guides/idempotency): Header Idempotency-Key con TTL de 24 h. Reintenta un POST sin duplicar recursos. - [Clientes internacionales](https://docs.factuarea.com/es/guides/international-customers): Identificar a un destinatario no español con el catálogo AEAT de identificación alternativa, y el mapa de escenario a calificación para entregas intracomunitarias, inversión del sujeto pasivo, exportaciones y ventas por ventanilla única. - [Clasificación fiscal y exenciones por línea](https://docs.factuarea.com/es/guides/line-tax-classification-and-exemptions): E1–E6 y N1–N2 por línea, la retención de IRPF que resta, y la matriz cerrada de pares legales de IVA y recargo de equivalencia — los cuatro campos que deciden qué dice el desglose que llega a la AEAT. - [Migración desde Holded](https://docs.factuarea.com/es/guides/migration-from-holded): Mapeo de recursos Holded → Factuarea, nomenclatura, endpoints equivalentes y script en Python. - [Cierre mensual del registro](https://docs.factuarea.com/es/guides/monthly-time-close): Congela el registro de jornada mensual inalterable, séllalo con una firma digital y exporta el informe o el fichero de incidencias para nóminas. - [Paginación](https://docs.factuarea.com/es/guides/pagination): Paginación por cursor con starting_after y ending_before. Sin ?page=, semántica al estilo Stripe. - [Registrar pagos](https://docs.factuarea.com/es/guides/payments): Registra pagos parciales contra facturas y facturas de compra, y consulta el saldo en curso desde el ledger. - [Presencia](https://docs.factuarea.com/es/guides/presence): Consulta quién trabaja ahora mismo y quién está en oficina o en remoto — una vista derivada y de solo lectura sobre el ledger de jornada, los horarios y la plantilla. - [Inicio rápido](https://docs.factuarea.com/es/guides/quickstart): Tu primera factura en 5 minutos — verifica tu key, consigue una serie y un impuesto, crea un cliente, emite una factura y envíala. Una sola secuencia de copiar y pegar contra una key fact_test_. - [Límites de peticiones](https://docs.factuarea.com/es/guides/rate-limits): Cuotas por minuto y mensuales según el tier. Cabeceras X-RateLimit-* y back-off recomendado. - [Facturas recurrentes](https://docs.factuarea.com/es/guides/recurring-invoices): Omite un ciclo, crea una recurrencia desde una factura, configura el envío automático, previsualiza el próximo documento y define campos fiscales por línea. - [Claves de régimen](https://docs.factuarea.com/es/guides/regime-keys): En la facturación española se llaman «régimen» tres cosas distintas. Esta página aclara cuál fijas tú, cuál se deriva y cuál es el catálogo cerrado de diecisiete códigos AEAT que puede declarar una línea. - [Alcance y limitaciones](https://docs.factuarea.com/es/guides/scope-and-limitations): Lo que la API de Factuarea no hace a propósito, lo que aún no hace, y la forma equivalente de resolver cada caso — más cuatro capacidades que puedes dar por ausentes y no lo están. - [Scopes e irreversibilidad](https://docs.factuarea.com/es/guides/scopes-and-irreversibility): Cómo leer el scope requerido y la irreversibilidad de cada endpoint desde la especificación OpenAPI — las extensiones x-required-scope y x-irreversible — y el catálogo de operaciones irreversibles. - [Facturas simplificadas o completas](https://docs.factuarea.com/es/guides/simplified-vs-full-invoices): F1, F2 y F3 — cuándo es legal una factura simplificada, el tope de 3.000 € que sí se aplica de verdad, y la sustitución en una sola llamada que convierte un lote de tiques en una factura completa. - [Etiquetas y campos personalizados](https://docs.factuarea.com/es/guides/tags-and-custom-fields): Clasifica documentos con tags y adjunta custom_fields tipados. Filtra listados por tag. En qué se diferencian de metadata. - [Impuestos territoriales — IVA, IGIC e IPSI](https://docs.factuarea.com/es/guides/territorial-taxes): España tiene tres impuestos indirectos, no uno. Qué tipos son legales en cada uno, cómo se elige el régimen por documento, qué declara el desglose de la AEAT y por qué el IGIC y el IPSI nunca aparecen en la declaración trimestral de IVA. - [Modo de prueba y sandbox](https://docs.factuarea.com/es/guides/test-mode): Crea tu integración de forma segura con claves fact_test_ — datos de sandbox aislados y AEAT, email y webhooks desactivados. - [Fichajes](https://docs.factuarea.com/es/guides/time-clock): Fichar entrada y salida, pausas, fichajes retroactivos y el flujo de correcciones sobre el ledger de jornada de solo apéndice. - [Alta automática en VeriFactu](https://docs.factuarea.com/es/guides/verifactu-auto-submission): No hay un botón de «enviar a la AEAT». El alta se crea cuando la factura sale de draft — esta es la lista de compuertas que deciden si ocurre, y las únicas palancas manuales que existen después. - [Estados de envío VeriFactu](https://docs.factuarea.com/es/guides/verifactu-submission-states): El ciclo de vida de un registro de facturación VeriFactu — pending, submitted, accepted, rejected, error —, qué significan el CSV y la huella, cómo funciona el presupuesto de reintentos y cuándo reintentar en lugar de subsanar. - [Subsanación de registros VeriFactu](https://docs.factuarea.com/es/guides/verifactu-subsanacion): Corrige y reenvía registros de facturación VeriFactu rechazados por la AEAT — cuándo aplica la subsanación, cuándo necesitas una anulación o una rectificativa, y el flujo exacto de la API. - [Versionado](https://docs.factuarea.com/es/guides/versioning): Política de versionado plano /v1 con la cabecera Factuarea-Version. Compromisos de estabilidad y deprecación. - [Webhooks](https://docs.factuarea.com/es/guides/webhooks): Notificaciones POST firmadas con HMAC SHA256. Verificación, reintentos exponenciales y rotación de secret. - [Horarios de trabajo](https://docs.factuarea.com/es/guides/work-schedules): Define patrones semanales de trabajo, su modo de cumplimiento y las asignaciones efectivo-datadas a empleados sobre la API v1. - [Visión general del control horario](https://docs.factuarea.com/es/guides/workforce-overview): El sistema de control horario sobre la API v1 — el registro de jornada inalterable (RD-ley 8/2019), el rol de empleado solo-portal, el add-on por asiento y los ocho dominios que lo componen. - [Plugin de Claude Code](https://docs.factuarea.com/es/mcp/claude-code-plugin): Dos plugins oficiales en un mismo marketplace — factuarea-mcp conecta Claude Code al servidor MCP de Factuarea, y factuarea-api trae cinco skills para construir la propia integración. - [Conectar un cliente](https://docs.factuarea.com/es/mcp/connect): Conecta Claude Code, Claude Desktop, el MCP Inspector o cualquier cliente MCP al servidor MCP de Factuarea — con OAuth 2.1 o una API key, y en modo de prueba. - [Errores y límites de peticiones](https://docs.factuarea.com/es/mcp/errors): Formas de error JSON-RPC mapeadas desde el contrato v1, la tabla completa de códigos y throttling por token / por plan con Retry-After. - [Resumen de MCP](https://docs.factuarea.com/es/mcp): Conecta agentes de IA a Factuarea sobre el Model Context Protocol — 391 tools de facturación, catálogo, cumplimiento, control horario y webhooks, con autenticación OAuth 2.1 y API key. - [Scopes y permisos](https://docs.factuarea.com/es/mcp/scopes): El catálogo de scopes del consentimiento OAuth, cómo se mapea a los scopes detallados que aplican las tools, el super-scope y el gating por plan/módulo. - [Catálogo de tools](https://docs.factuarea.com/es/mcp/tools): Las 391 tools del MCP de Factuarea agrupadas por dominio, con el scope que requiere cada una y su categoría de límite de peticiones. - [Integración GoCardless](https://docs.factuarea.com/es/payments/gocardless): Estado de la integración con GoCardless — todavía no liberada, qué existe ya detrás del flag, y la superficie v1 y MCP exacta que aparece el día que se enciende. - [Bandeja de eventos de integración](https://docs.factuarea.com/es/payments/integration-events-inbox): Por qué un cobro no acabó en factura — los motivos de descarte tipados, cuáles te avisan, cuáles parquean el evento para que puedas reprocesarlo, y cómo funciona la ventana de retención de 30 días. - [Conciliar con la metadata de sistema](https://docs.factuarea.com/es/payments/metadata-reconciliation): Las claves de metadata que Factuarea escribe en las facturas auto-emitidas desde un ciclo de suscripción de Stripe, y cómo usar el filtro de metadata para sacar todas las facturas de una suscripción o de un periodo de facturación. - [Integración MONEI](https://docs.factuarea.com/es/payments/monei): Estado de la integración con MONEI — todavía no liberada, qué existe ya detrás del flag, por qué no tiene recurso de mandatos, y la superficie v1 y MCP exacta que aparece al liberarse. - [Payouts y conciliación bancaria](https://docs.factuarea.com/es/payments/payouts-reconciliation): Cómo Factuarea ingiere los payouts de Stripe, los vincula con los cobros que agrupan, los concilia contra tu extracto Norma 43 y emite el evento payout.reconciled. - [Auto-facturación con Stripe](https://docs.factuarea.com/es/payments/stripe-autoinvoicing): Emite facturas automáticamente desde los cobros de Stripe Connect — captura de NIF en el Checkout, umbral de factura simplificada, exigir NIF y qué cobros se derivan a revisión manual. - [account_not_found](https://docs.factuarea.com/es/errors/account_not_found): No se pudo resolver la cuenta asociada a la clave, lo que suele significar que la clave ya no apunta a una empresa viva. - [addon_not_active](https://docs.factuarea.com/es/errors/addon_not_active): La funcionalidad pertenece a un add-on que ahora mismo no está activo para la empresa. - [addon_required](https://docs.factuarea.com/es/errors/addon_required): Crear endpoints de webhook pertenece al add-on Developer API, y la empresa no lo tiene activo: el nivel gratuito permite cero endpoints. - [alta_record_not_found](https://docs.factuarea.com/es/errors/alta_record_not_found): La factura no tiene registro de alta, así que la operación que depende de él no tiene sobre qué trabajar. - [alternative_id_type_invalid](https://docs.factuarea.com/es/errors/alternative_id_type_invalid): El tipo de identificador alternativo queda fuera del catálogo `nif_iva`, `passport`, `country_id`, `residence_certificate`, `other_document`, `not_registered`. - [anulacion_record_already_exists](https://docs.factuarea.com/es/errors/anulacion_record_already_exists): La factura ya tiene un registro de anulación en la cadena, y la anulación se declara una sola vez. - [api_key_already_revoked](https://docs.factuarea.com/es/errors/api_key_already_revoked): La clave ya estaba revocada, y una clave revocada no admite más operaciones: la revocación es terminal. - [api_key_expired](https://docs.factuarea.com/es/errors/api_key_expired): La clave pasó su fecha de caducidad. - [api_key_not_found](https://docs.factuarea.com/es/errors/api_key_not_found): El identificador no corresponde a ninguna API key de la empresa autenticada. - [api_key_revoked](https://docs.factuarea.com/es/errors/api_key_revoked): La clave fue revocada, y una clave revocada no vuelve a autenticar nunca: revocar es justamente la forma de cortar una credencial filtrada. - [api_version_invalid_format](https://docs.factuarea.com/es/errors/api_version_invalid_format): La versión de payload del endpoint no es una fecha `YYYY-MM-DD`. - [api_version_unsupported](https://docs.factuarea.com/es/errors/api_version_unsupported): La versión de payload está bien formada pero no está entre las que sirve la plataforma. - [attachment_invalid_filename](https://docs.factuarea.com/es/errors/attachment_invalid_filename): El nombre del fichero no es utilizable: está vacío, lleva componentes de ruta, o supera los 200 caracteres. - [attachment_mime_not_allowed](https://docs.factuarea.com/es/errors/attachment_mime_not_allowed): El tipo de fichero queda fuera del conjunto admitido: PDF, PNG, JPEG, XML y HTML. - [attachment_missing](https://docs.factuarea.com/es/errors/attachment_missing): La factura de compra existe pero no tiene fichero adjunto, así que no hay nada que descargar. - [attachment_too_large](https://docs.factuarea.com/es/errors/attachment_too_large): El fichero supera el tamaño máximo permitido para un adjunto de documento. - [business_rule_violation](https://docs.factuarea.com/es/errors/business_rule_violation): Una invariante del dominio rechazó la operación. Este código indica la familia; `error.subcode` nombra la regla concreta y `error.message` la explica. - [cannot_archive_last_default_series](https://docs.factuarea.com/es/errors/cannot_archive_last_default_series): La serie es la única activa de su tipo de documento. Archivarla dejaría a la empresa sin numeración disponible y congelaría ese tipo de documento. - [cannot_attach_to_cancelled_purchase_invoice](https://docs.factuarea.com/es/errors/cannot_attach_to_cancelled_purchase_invoice): La factura está cancelada, y adjuntar documentos a un registro cancelado alteraría documentación ya cerrada. - [cannot_have_both_tax_id_and_alternative_id](https://docs.factuarea.com/es/errors/cannot_have_both_tax_id_and_alternative_id): El cliente envía `tax_id` y un identificador alternativo a la vez. La identidad fiscal es una: el identificador alternativo existe precisamente para partes sin NIF español. - [census_requires_tax_id](https://docs.factuarea.com/es/errors/census_requires_tax_id): La verificación censal contrasta el par nombre + NIF contra la AEAT, y falta uno de los dos. - [certificate_expired](https://docs.factuarea.com/es/errors/certificate_expired): El certificado está fuera de su ventana de validez: ha caducado, o todavía no es válido. - [certificate_nif_mismatch](https://docs.factuarea.com/es/errors/certificate_nif_mismatch): El NIF del titular del certificado no coincide con el de la empresa. Los registros AEAT se firman en nombre de la empresa, así que ambos deben ser el mismo. - [certificate_not_found](https://docs.factuarea.com/es/errors/certificate_not_found): La empresa no tiene ningún certificado FNMT que corresponda al identificador, o no tiene ninguno subido. - [certificate_too_large](https://docs.factuarea.com/es/errors/certificate_too_large): El fichero supera el límite de 100 KB, cuando un certificado FNMT real pesa unos pocos kilobytes. - [client_has_documents](https://docs.factuarea.com/es/errors/client_has_documents): El cliente está referenciado por documentos emitidos. Borrarlo dejaría facturas, presupuestos o albaranes sin la parte a la que se emitieron, y los registros fiscales tienen que seguir siendo trazables. - [client_import_too_large](https://docs.factuarea.com/es/errors/client_import_too_large): El CSV supera el límite de filas que admite la importación síncrona, ya que el fichero entero se procesa dentro de la propia petición. - [client_not_found](https://docs.factuarea.com/es/errors/client_not_found): El identificador no resuelve a ningún cliente de la empresa autenticada. - [client_requires_tax_identity](https://docs.factuarea.com/es/errors/client_requires_tax_identity): El cliente no tiene identidad fiscal: ni `tax_id` ni identificador alternativo, y no se puede emitir una factura a una parte sin identificar. - [clock_drift_exceeded](https://docs.factuarea.com/es/errors/clock_drift_exceeded): El reloj del servidor se desvió del NTP por encima del margen permitido. La marca de tiempo de generación entra en la huella AEAT, así que un reloj desincronizado produciría registros que la AEAT rechaza. - [company_inactive](https://docs.factuarea.com/es/errors/company_inactive): El perfil que indica `X-Active-Profile` es una de tus empresas gestionadas, pero está desactivada y no se puede operar hasta que vuelva a estar activa. - [conflicting_pagination_params](https://docs.factuarea.com/es/errors/conflicting_pagination_params): `starting_after` y `ending_before` viajaron en la misma petición. Recorren la colección en sentidos opuestos, así que solo puede aplicarse uno. - [corrective_invoice_inanulable](https://docs.factuarea.com/es/errors/corrective_invoice_inanulable): La factura es a su vez una rectificativa, y las rectificativas nunca se anulan: la cadena de corrección tiene que seguir siendo auditable de punta a punta. - [custom_header_blocklisted](https://docs.factuarea.com/es/errors/custom_header_blocklisted): Una de las cabeceras personalizadas está reservada: la gestiona la capa HTTP (`host`, `content-type`, `content-length`, `user-agent`), la envía Factuarea como parte del contrato firmado (`factuarea-*`), o pertenece al proxy (`x-forwarded-*`). - [custom_header_value_too_long](https://docs.factuarea.com/es/errors/custom_header_value_too_long): El valor de una cabecera personalizada supera los 1024 caracteres. - [custom_tax_creation_disabled](https://docs.factuarea.com/es/errors/custom_tax_creation_disabled): La creación de impuestos personalizados está deshabilitada para esta empresa. - [declaracion_already_exists](https://docs.factuarea.com/es/errors/declaracion_already_exists): La empresa ya tiene presentada la declaración responsable del SIF de ese período. - [declaracion_not_found](https://docs.factuarea.com/es/errors/declaracion_not_found): La empresa no tiene presentada la declaración responsable del SIF del período solicitado. - [delivery_note_not_found](https://docs.factuarea.com/es/errors/delivery_note_not_found): El identificador no resuelve a ningún albarán de la empresa autenticada. - [delivery_note_section_not_editable_in_status](https://docs.factuarea.com/es/errors/delivery_note_section_not_editable_in_status): La sección logística —transportista, vehículo, conductor— está congelada porque el albarán ya está entregado, facturado o cancelado. - [dependency_unavailable](https://docs.factuarea.com/es/errors/dependency_unavailable): Un servicio externo del que depende la operación no respondió a tiempo. - [direct_debit_requires_default_bank_account](https://docs.factuarea.com/es/errors/direct_debit_requires_default_bank_account): Se eligió domiciliación bancaria como método de pago, pero el cliente no tiene cuenta bancaria por defecto a la que cargar. - [document_type_required_for_ambiguous_code](https://docs.factuarea.com/es/errors/document_type_required_for_ambiguous_code): Ese código de serie existe para más de un tipo de documento, así que por sí solo no identifica una única serie. - [driver_tax_id_requires_name](https://docs.factuarea.com/es/errors/driver_tax_id_requires_name): Se envió el NIF del conductor sin su nombre, y un identificador sin nombre no identifica a nadie en el documento de entrega. - [duplicate_tax_default_for_document_type](https://docs.factuarea.com/es/errors/duplicate_tax_default_for_document_type): Ya hay otro impuesto del mismo tipo marcado como default para ese tipo de documento, y el par (tipo de impuesto, tipo de documento) admite un único default. - [employee_seat_charge_failed](https://docs.factuarea.com/es/errors/employee_seat_charge_failed): El cobro inmediato del prorrateo del asiento de empleado fue rechazado: la tarjeta se denegó, necesita autenticación, o el proveedor de pago estaba inaccesible. El empleado no se activa si el asiento no se cobra. - [employee_seat_payment_method_required](https://docs.factuarea.com/es/errors/employee_seat_payment_method_required): 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. - [event_already_processed](https://docs.factuarea.com/es/errors/event_already_processed): Ese evento del SIF ya está registrado en la cadena de eventos, y cada evento se procesa exactamente una vez. - [event_not_found](https://docs.factuarea.com/es/errors/event_not_found): El identificador no corresponde a ningún evento de la empresa autenticada, o el evento fue purgado por la política de retención de 30 días. - [export_limit_exceeded](https://docs.factuarea.com/es/errors/export_limit_exceeded): La selección filtrada supera el tope de 5.000 facturas de la exportación, así que el fichero se rechaza de entrada en lugar de truncarse en silencio. - [external_id_already_exists](https://docs.factuarea.com/es/errors/external_id_already_exists): El `external_id` con el que concilias contra tu sistema ya está asignado a otro objeto del mismo tipo en esta empresa. - [face_transmission_failed](https://docs.factuarea.com/es/errors/face_transmission_failed): La plataforma FACe —el punto de entrada de las administraciones públicas— estaba inaccesible o respondió con un fallo. El problema está aguas arriba, no en tu petición. - [facturae_signing_failed](https://docs.factuarea.com/es/errors/facturae_signing_failed): No se pudo producir la firma XAdES del fichero Facturae, normalmente porque el certificado de firma no es utilizable en ese momento. - [feature_not_available_in_plan](https://docs.factuarea.com/es/errors/feature_not_available_in_plan): La funcionalidad no está incluida en el plan de la empresa. - [forbidden_action](https://docs.factuarea.com/es/errors/forbidden_action): La acción está bloqueada para este recurso aunque el scope sea el correcto: el recurso pertenece a un catálogo compartido, o el cambio va por otro endpoint. - [gestoria_module_required](https://docs.factuarea.com/es/errors/gestoria_module_required): La gestoría tiene un plan vigente, pero sin el módulo de gestoría, así que no puede crear ni operar empresas gestionadas. - [gestoria_plan_required](https://docs.factuarea.com/es/errors/gestoria_plan_required): La gestoría no tiene una suscripción de pago activa, así que no hay suscripción sobre la que cobrar el asiento. - [idempotency_key_in_use](https://docs.factuarea.com/es/errors/idempotency_key_in_use): Hay otra petición con la misma `Idempotency-Key` todavía en curso, y aún no se conoce su resultado. - [idempotency_key_invalid](https://docs.factuarea.com/es/errors/idempotency_key_invalid): La `Idempotency-Key` no encaja con el formato admitido: entre 1 y 255 caracteres ASCII imprimibles. - [idempotency_key_reused](https://docs.factuarea.com/es/errors/idempotency_key_reused): Esa `Idempotency-Key` ya se usó con un payload distinto. La clave identifica una operación concreta, así que reutilizarla para otra vaciaría de sentido el replay. - [Códigos de error de Cuenta](https://docs.factuarea.com/es/errors/index-account): Todos los códigos de error de la API pública que emite Cuenta, con su estado HTTP, su type y una página por código. - [Códigos de error de Autenticación](https://docs.factuarea.com/es/errors/index-authentication): Todos los códigos de error de la API pública que emite Autenticación, con su estado HTTP, su type y una página por código. - [Códigos de error de Autorización](https://docs.factuarea.com/es/errors/index-authorization): Todos los códigos de error de la API pública que emite Autorización, con su estado HTTP, su type y una página por código. - [Códigos de error de Clientes](https://docs.factuarea.com/es/errors/index-clients): Todos los códigos de error de la API pública que emite Clientes, con su estado HTTP, su type y una página por código. - [Códigos de error de Empresas](https://docs.factuarea.com/es/errors/index-companies): Todos los códigos de error de la API pública que emite Empresas, con su estado HTTP, su type y una página por código. - [Códigos de error de Albaranes](https://docs.factuarea.com/es/errors/index-delivery-notes): Todos los códigos de error de la API pública que emite Albaranes, con su estado HTTP, su type y una página por código. - [Códigos de error de Empleados](https://docs.factuarea.com/es/errors/index-employees): Todos los códigos de error de la API pública que emite Empleados, con su estado HTTP, su type y una página por código. - [Códigos de error de Events](https://docs.factuarea.com/es/errors/index-events): Todos los códigos de error de la API pública que emite Events, con su estado HTTP, su type y una página por código. - [Códigos de error de Idempotency](https://docs.factuarea.com/es/errors/index-idempotency): Todos los códigos de error de la API pública que emite Idempotency, con su estado HTTP, su type y una página por código. - [Códigos de error de Facturas](https://docs.factuarea.com/es/errors/index-invoices): Todos los códigos de error de la API pública que emite Facturas, con su estado HTTP, su type y una página por código. - [Códigos de error de Notificaciones](https://docs.factuarea.com/es/errors/index-notifications): Todos los códigos de error de la API pública que emite Notificaciones, con su estado HTTP, su type y una página por código. - [Códigos de error de Pagos](https://docs.factuarea.com/es/errors/index-payments): Todos los códigos de error de la API pública que emite Pagos, con su estado HTTP, su type y una página por código. - [Códigos de error de Productos](https://docs.factuarea.com/es/errors/index-products): Todos los códigos de error de la API pública que emite Productos, con su estado HTTP, su type y una página por código. - [Códigos de error de Facturas proforma](https://docs.factuarea.com/es/errors/index-proformas): Todos los códigos de error de la API pública que emite Facturas proforma, con su estado HTTP, su type y una página por código. - [Códigos de error de Facturas de compra](https://docs.factuarea.com/es/errors/index-purchase-invoices): Todos los códigos de error de la API pública que emite Facturas de compra, con su estado HTTP, su type y una página por código. - [Códigos de error de Presupuestos](https://docs.factuarea.com/es/errors/index-quotes): Todos los códigos de error de la API pública que emite Presupuestos, con su estado HTTP, su type y una página por código. - [Códigos de error de Límite de tasa](https://docs.factuarea.com/es/errors/index-rate-limit): Todos los códigos de error de la API pública que emite Límite de tasa, con su estado HTTP, su type y una página por código. - [Códigos de error de Facturas recurrentes](https://docs.factuarea.com/es/errors/index-recurring-invoices): Todos los códigos de error de la API pública que emite Facturas recurrentes, con su estado HTTP, su type y una página por código. - [Códigos de error de Request](https://docs.factuarea.com/es/errors/index-request): Todos los códigos de error de la API pública que emite Request, con su estado HTTP, su type y una página por código. - [Códigos de error de Series](https://docs.factuarea.com/es/errors/index-series): Todos los códigos de error de la API pública que emite Series, con su estado HTTP, su type y una página por código. - [Códigos de error de Servidor](https://docs.factuarea.com/es/errors/index-server): Todos los códigos de error de la API pública que emite Servidor, con su estado HTTP, su type y una página por código. - [Códigos de error de Proveedores](https://docs.factuarea.com/es/errors/index-suppliers): Todos los códigos de error de la API pública que emite Proveedores, con su estado HTTP, su type y una página por código. - [Códigos de error de Informes fiscales](https://docs.factuarea.com/es/errors/index-tax-reports): Todos los códigos de error de la API pública que emite Informes fiscales, con su estado HTTP, su type y una página por código. - [Códigos de error de Impuestos](https://docs.factuarea.com/es/errors/index-taxes): Todos los códigos de error de la API pública que emite Impuestos, con su estado HTTP, su type y una página por código. - [Códigos de error de VeriFactu](https://docs.factuarea.com/es/errors/index-verifactu): Todos los códigos de error de la API pública que emite VeriFactu, con su estado HTTP, su type y una página por código. - [Códigos de error de Webhooks](https://docs.factuarea.com/es/errors/index-webhooks): Todos los códigos de error de la API pública que emite Webhooks, con su estado HTTP, su type y una página por código. - [Códigos de error por categoría](https://docs.factuarea.com/es/errors): Todos los códigos de error de la API pública agrupados por categoría, con una página por código donde se explica su causa y qué hacer. - [indirect_tax_regime_invalid](https://docs.factuarea.com/es/errors/indirect_tax_regime_invalid): El régimen indirecto queda fuera del catálogo `iva`, `igic`, `ipsi`. - [insufficient_data_for_report](https://docs.factuarea.com/es/errors/insufficient_data_for_report): El período no tiene datos que declarar, o a una factura del período le falta un campo obligatorio para este modelo, típicamente el NIF del cliente. - [insufficient_scope](https://docs.factuarea.com/es/errors/insufficient_scope): La clave autentica correctamente pero no lleva el scope que exige esta operación. Los scopes se conceden al emitir la clave y no se amplían en tiempo de llamada. - [internal_error](https://docs.factuarea.com/es/errors/internal_error): Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload. - [invalid_aeat_code](https://docs.factuarea.com/es/errors/invalid_aeat_code): El código de operación AEAT queda fuera del catálogo cerrado `S1`, `S2`, `S3`, `E1`-`E6`, `N1`, `N2` que usan VeriFactu y el SII. - [invalid_api_key](https://docs.factuarea.com/es/errors/invalid_api_key): La clave no corresponde a ninguna clave activa. Puede estar mal copiada, truncada, o pertenecer a otro entorno: las claves de prueba y las de producción no son intercambiables. - [invalid_certificate_format](https://docs.factuarea.com/es/errors/invalid_certificate_format): El fichero no es un contenedor PKCS#12: sus primeros bytes no corresponden a la estructura ASN.1 que exige el formato, diga lo que diga la extensión. - [invalid_certificate_password](https://docs.factuarea.com/es/errors/invalid_certificate_password): La contraseña no abre el fichero del certificado. - [invalid_correction_nature](https://docs.factuarea.com/es/errors/invalid_correction_nature): `correction_nature` solo acepta `S` (sustitución: la rectificativa lleva los importes corregidos completos) o `I` (por diferencias: lleva solo el delta). - [invalid_correction_reason](https://docs.factuarea.com/es/errors/invalid_correction_reason): El motivo de rectificación queda fuera de la lista fiscal cerrada (`error_fundado`, `concurso`, `incobrable`, `error_importe`, `error_cliente`, `devolucion`, `descuento`, `otras`), que mapea a los códigos AEAT R1 a R4. - [invalid_country_aeat_zone](https://docs.factuarea.com/es/errors/invalid_country_aeat_zone): La zona territorial AEAT queda fuera del catálogo `peninsula`, `canarias`, `ceuta`, `melilla`. - [invalid_country_code](https://docs.factuarea.com/es/errors/invalid_country_code): El código de país no tiene exactamente dos caracteres, así que no es un código ISO 3166-1 alfa-2 válido. - [invalid_customer_visible_label](https://docs.factuarea.com/es/errors/invalid_customer_visible_label): La etiqueta que se muestra al cliente en el documento supera la longitud permitida. - [invalid_description](https://docs.factuarea.com/es/errors/invalid_description): La descripción supera la longitud máxima permitida para el campo. - [invalid_document_type](https://docs.factuarea.com/es/errors/invalid_document_type): El tipo de documento queda fuera del catálogo: `invoice`, `quote`, `delivery_note`, `proforma`, `purchase_invoice`, `recurring_invoice`. - [invalid_expiry_date](https://docs.factuarea.com/es/errors/invalid_expiry_date): La fecha de vencimiento es anterior a la de emisión, o la supera en más de 365 días. - [invalid_frequency_interval](https://docs.factuarea.com/es/errors/invalid_frequency_interval): El intervalo es menor que 1, así que la recurrencia nunca avanzaría a una siguiente ejecución. - [invalid_frequency_type](https://docs.factuarea.com/es/errors/invalid_frequency_type): La frecuencia queda fuera del catálogo `daily`, `weekly`, `biweekly`, `monthly`, `bimonthly`, `quarterly`, `semiannual`, `annual`, `custom`. - [invalid_holiday_handling](https://docs.factuarea.com/es/errors/invalid_holiday_handling): La política de festivos queda fuera del catálogo `skip`, `before`, `after`, `same`. - [invalid_invoice_id](https://docs.factuarea.com/es/errors/invalid_invoice_id): La referencia de factura recibida no es un identificador válido; suele significar que se coló un valor interno donde la API espera el `id` público. - [invalid_invoice_number](https://docs.factuarea.com/es/errors/invalid_invoice_number): El número de factura no sigue el formato canónico `SERIE-AAAA-NNN`, más el sufijo `-RECn` en las rectificativas. - [invalid_invoice_status](https://docs.factuarea.com/es/errors/invalid_invoice_status): El valor enviado como estado de factura queda fuera del catálogo del ciclo de vida (`draft`, `scheduled`, `sent`, `paid`, `overdue`, `cancelled`, `annulled`). - [invalid_invoice_uuid](https://docs.factuarea.com/es/errors/invalid_invoice_uuid): El identificador de factura de la ruta o del payload no es un UUID válido. - [invalid_param_format](https://docs.factuarea.com/es/errors/invalid_param_format): Un form request legacy rechazó la forma de un valor. Los endpoints migrados reportan lo mismo como `parameter_invalid_format` o `parameter_invalid_integer`. - [invalid_param_value](https://docs.factuarea.com/es/errors/invalid_param_value): Un form request legacy rechazó el valor de un campo. Los endpoints migrados reportan lo mismo como `parameter_invalid_enum` o `parameter_invalid_range`. - [invalid_payment_date](https://docs.factuarea.com/es/errors/invalid_payment_date): La fecha de pago queda fuera de la ventana admitida: no puede ser anterior a la fecha de emisión de la factura ni situarse en el futuro. - [invalid_payment_method](https://docs.factuarea.com/es/errors/invalid_payment_method): El método de pago queda fuera de la allowlist cerrada: `bank_transfer`, `cash`, `credit_card`, `sepa_direct_debit`, `paypal`, `bizum`, `other`. - [invalid_period](https://docs.factuarea.com/es/errors/invalid_period): El período no identifica una declaración: el año queda fuera del rango admitido, o falta el trimestre o está fuera del rango 1 a 4 en un modelo trimestral. - [invalid_proforma_id](https://docs.factuarea.com/es/errors/invalid_proforma_id): La referencia de proforma recibida no es un identificador válido, normalmente porque un valor interno sustituyó al `id` público. - [invalid_proforma_number](https://docs.factuarea.com/es/errors/invalid_proforma_number): El número de proforma no sigue el formato canónico de numeración de su serie. - [invalid_proforma_status](https://docs.factuarea.com/es/errors/invalid_proforma_status): El valor enviado como estado queda fuera del catálogo `draft`, `accepted`, `rejected`, `expired`, `invoiced`, `cancelled`. - [invalid_proforma_uuid](https://docs.factuarea.com/es/errors/invalid_proforma_uuid): El identificador de proforma de la ruta o del payload no es un UUID válido. - [invalid_purchase_invoice_id](https://docs.factuarea.com/es/errors/invalid_purchase_invoice_id): La referencia de factura de compra recibida no es un identificador válido, normalmente porque un valor interno sustituyó al `id` público. - [invalid_purchase_invoice_number](https://docs.factuarea.com/es/errors/invalid_purchase_invoice_number): El número de factura está vacío o no encaja con el formato admitido. En una factura de compra el número es el que imprimió el proveedor, no uno que genere Factuarea. - [invalid_purchase_invoice_uuid](https://docs.factuarea.com/es/errors/invalid_purchase_invoice_uuid): El identificador de factura de compra de la ruta o del payload no es un UUID válido. - [invalid_rate_for_tax_regime](https://docs.factuarea.com/es/errors/invalid_rate_for_tax_regime): El tipo no pertenece a la rejilla legal de su régimen: el IGIC admite 0, 3, 5, 7, 9,5, 15 y 20 %; el IPSI admite 0, 0,5, 1, 2, 4, 8 y 10 %. - [invalid_recurring_invoice_id](https://docs.factuarea.com/es/errors/invalid_recurring_invoice_id): La referencia de recurrencia recibida no es un identificador válido, normalmente porque un valor interno sustituyó al `id` público. - [invalid_recurring_invoice_uuid](https://docs.factuarea.com/es/errors/invalid_recurring_invoice_uuid): El identificador de recurrencia de la ruta o del payload no es un UUID válido. - [invalid_series_code](https://docs.factuarea.com/es/errors/invalid_series_code): El código de la serie está vacío, es demasiado largo, o lleva caracteres que no corresponden a un prefijo fiscal. - [invalid_series_name](https://docs.factuarea.com/es/errors/invalid_series_name): El nombre de la serie está vacío o supera la longitud permitida. - [invalid_series_number](https://docs.factuarea.com/es/errors/invalid_series_number): El número inicial no es válido: no es un entero positivo, o queda en el último número ya emitido o por debajo, lo que reemitiría números ya consumidos. - [invalid_series_uuid](https://docs.factuarea.com/es/errors/invalid_series_uuid): El identificador de serie de la ruta o del payload no es un UUID válido. - [invalid_series_year](https://docs.factuarea.com/es/errors/invalid_series_year): El ejercicio no es un año de cuatro cifras válido para una serie de numeración. - [invalid_status_transition](https://docs.factuarea.com/es/errors/invalid_status_transition): El estado solicitado no es alcanzable desde el estado en el que está ahora mismo el documento. - [invalid_tax_code](https://docs.factuarea.com/es/errors/invalid_tax_code): El código del impuesto está vacío o supera los 50 caracteres. - [invalid_tax_name](https://docs.factuarea.com/es/errors/invalid_tax_name): El nombre del impuesto está vacío o supera los 255 caracteres. - [invalid_tax_rate](https://docs.factuarea.com/es/errors/invalid_tax_rate): El tipo impositivo queda fuera del rango permitido para su clase: IVA 0-27 %, retención 0-47 %, recargo de equivalencia 0-10 %, otros 0-100 %. - [invalid_tax_type_filter](https://docs.factuarea.com/es/errors/invalid_tax_type_filter): El filtro `type` del listado por tipo lleva un valor fuera del enum `vat`, `retention`, `surcharge`, `other`. - [invalid_validity_window](https://docs.factuarea.com/es/errors/invalid_validity_window): La ventana de vigencia está invertida: `valid_until` es anterior a `valid_from`. - [invoice_already_annulled](https://docs.factuarea.com/es/errors/invoice_already_annulled): La factura ya estaba anulada. La anulación es terminal y, con VeriFactu activo, su registro de anulación ya llegó a la AEAT. - [invoice_already_paid](https://docs.factuarea.com/es/errors/invoice_already_paid): La factura ya está cobrada. `paid` es un estado terminal y contablemente cerrado: el IVA repercutido ya se ha declarado, o se declarará en el período. - [invoice_already_sent](https://docs.factuarea.com/es/errors/invoice_already_sent): La factura ya fue emitida: tiene número definitivo de serie y, con VeriFactu activo, su alta en la AEAT. La emisión no ocurre dos veces. - [invoice_cannot_assign_number](https://docs.factuarea.com/es/errors/invoice_cannot_assign_number): Se pidió número definitivo para una factura que no es borrador, o que ya lo tiene. La numeración de serie es monótona y los números no se reasignan. - [invoice_invalid_status_transition](https://docs.factuarea.com/es/errors/invoice_invalid_status_transition): El estado destino no es alcanzable desde el actual. El ciclo de vida es dirigido: `draft` pasa a `scheduled` o `sent`, `sent` a `paid`, `overdue` o `annulled`, y `paid`, `cancelled` y `annulled` son terminales. - [invoice_not_cancellable_in_current_state](https://docs.factuarea.com/es/errors/invoice_not_cancellable_in_current_state): Cancelar retira un borrador que todavía no es fiscalmente vinculante, así que solo aplica mientras la factura está en `draft`. - [invoice_not_correctable_in_current_state](https://docs.factuarea.com/es/errors/invoice_not_correctable_in_current_state): Una rectificativa solo se emite contra una factura ya emitida (`sent` o `paid`). Un borrador, una factura cancelada o una anulada no tienen nada que rectificar. - [invoice_not_deletable_in_current_state](https://docs.factuarea.com/es/errors/invoice_not_deletable_in_current_state): Solo se borran las facturas en `draft` y `cancelled`. Una factura numerada nunca desaparece: la serie correlativa debe seguir siendo auditable. - [invoice_not_editable_in_current_state](https://docs.factuarea.com/es/errors/invoice_not_editable_in_current_state): Solo un borrador admite edición. Una vez emitida, la factura es inmutable y su contenido queda congelado junto con su registro fiscal. - [invoice_not_eligible_for_action](https://docs.factuarea.com/es/errors/invoice_not_eligible_for_action): La acción solicitada no aplica a esta factura: su tipo o su estado actual la dejan fuera del alcance de la operación. - [invoice_not_found](https://docs.factuarea.com/es/errors/invoice_not_found): El identificador no resuelve a ninguna factura de la empresa autenticada. Las facturas de otra empresa responden exactamente igual. - [invoice_not_modifiable_in_current_state](https://docs.factuarea.com/es/errors/invoice_not_modifiable_in_current_state): El campo que intentas cambiar está congelado para el estado actual — por ejemplo el régimen fiscal de una factura anulada. - [invoice_not_paid](https://docs.factuarea.com/es/errors/invoice_not_paid): Se pidió un justificante de pago de una factura sin cobro registrado, así que no hay nada que certificar. - [invoice_not_reschedulable_in_current_state](https://docs.factuarea.com/es/errors/invoice_not_reschedulable_in_current_state): Reprogramar mueve la fecha de emisión de una factura que está esperando en `scheduled`, y esta factura no está esperando. - [invoice_not_schedulable_in_current_state](https://docs.factuarea.com/es/errors/invoice_not_schedulable_in_current_state): Solo un borrador se puede programar: la programación reserva un momento futuro de emisión sin consumir todavía número de serie. - [invoice_not_unschedulable_in_current_state](https://docs.factuarea.com/es/errors/invoice_not_unschedulable_in_current_state): Desprogramar devuelve la factura de `scheduled` a `draft`, así que solo aplica mientras sigue esperando a emitirse. - [invoice_not_unsendable_in_current_state](https://docs.factuarea.com/es/errors/invoice_not_unsendable_in_current_state): Deshacer la marca de entrega solo aplica a una factura `sent`: limpia `sent_at` y mantiene la factura emitida. - [invoice_requires_at_least_one_line](https://docs.factuarea.com/es/errors/invoice_requires_at_least_one_line): La factura no lleva ninguna línea de operación, así que no tiene base imponible y no se puede emitir. Ocurre cuando no envías líneas y cuando todas las que envías son de suplido: un suplido es una cantidad pagada por cuenta del cliente (art. 78.Tres.3 LIVA), no una operación tuya. - [invoice_year_required_for_ambiguous_number](https://docs.factuarea.com/es/errors/invoice_year_required_for_ambiguous_number): Ese número de factura existe en más de un ejercicio, así que por sí solo no identifica una única factura. - [ip_not_allowed](https://docs.factuarea.com/es/errors/ip_not_allowed): La clave restringe las direcciones que acepta, y la petición llegó desde una que no está en esa lista. - [length_required](https://docs.factuarea.com/es/errors/length_required): Llegó una petición con body en codificación chunked, sin declarar su tamaño. La API necesita conocer la longitud por adelantado para rechazar payloads excesivos antes de cargarlos en memoria. - [line_total_checksum_mismatch](https://docs.factuarea.com/es/errors/line_total_checksum_mismatch): El `line_total` declarado no coincide con el que calcula Factuarea para esa línea (cantidad × precio − descuento + IVA − retención + recargo) y la desviación supera el céntimo de tolerancia. El importe que se factura y se declara a la AEAT es siempre el calculado aquí, así que la discrepancia significa que tu sistema y la factura emitida no cuadrarían. - [line_type_invalid](https://docs.factuarea.com/es/errors/line_type_invalid): El tipo de línea queda fuera del catálogo cerrado `NORMAL` / `SUPLIDO`. Una factura emitida sólo distingue dos naturalezas: lo que vendes tú, que forma base imponible y lleva IVA, y el suplido, que es dinero adelantado en nombre y por cuenta del cliente y por eso queda fuera de la base (art. 78.Tres.3 LIVA). - [maintenance](https://docs.factuarea.com/es/errors/maintenance): La plataforma está en ventana de mantenimiento y las escrituras se retienen a propósito. - [max_api_keys_exceeded](https://docs.factuarea.com/es/errors/max_api_keys_exceeded): La empresa alcanzó el número de API keys que permite su plan. - [max_retries_exceeded](https://docs.factuarea.com/es/errors/max_retries_exceeded): El registro agotó el presupuesto de reintentos técnicos de reenvío del XML almacenado. Reintentar el mismo contenido volvería a fallar igual. - [max_webhook_endpoints_exceeded](https://docs.factuarea.com/es/errors/max_webhook_endpoints_exceeded): La empresa alcanzó el número de endpoints de webhook que permite su nivel de add-on. - [metadata_too_many_keys](https://docs.factuarea.com/es/errors/metadata_too_many_keys): El objeto `metadata` supera el límite de 50 claves por recurso. - [metadata_value_too_long](https://docs.factuarea.com/es/errors/metadata_value_too_long): Un valor de `metadata` supera los 500 caracteres una vez serializado a texto. - [method_not_allowed](https://docs.factuarea.com/es/errors/method_not_allowed): La ruta existe pero no acepta el verbo HTTP utilizado. - [missing_api_key](https://docs.factuarea.com/es/errors/missing_api_key): La petición no lleva credenciales: ni cabecera `Authorization` ni `X-API-Key`. - [missing_required_param](https://docs.factuarea.com/es/errors/missing_required_param): Un form request legacy detectó que faltaba un campo obligatorio. Los endpoints ya migrados a los parsers canónicos reportan lo mismo como `parameter_missing`. - [mode_switch_blocked_until_year_end](https://docs.factuarea.com/es/errors/mode_switch_blocked_until_year_end): El modo VeriFactu se activó en este ejercicio y ya se emitió al menos un registro de facturación. Dar marcha atrás degradaría la integridad de una cadena ya declarada a la AEAT. - [module_not_available_in_sandbox](https://docs.factuarea.com/es/errors/module_not_available_in_sandbox): El recurso pertenece a un módulo vetado en modo test. La sandbox nunca toca AEAT, bancos ni cobros reales, así que esos módulos quedan fuera a propósito. - [monthly_quota_exceeded](https://docs.factuarea.com/es/errors/monthly_quota_exceeded): La empresa agotó la cuota mensual de llamadas que incluye su plan. - [monthly_requires_month_segmented_format](https://docs.factuarea.com/es/errors/monthly_requires_month_segmented_format): El contador se reinicia cada mes pero la máscara de numeración no segrega por mes, así que dos meses arrancarían en el mismo correlativo y producirían números duplicados dentro del año. - [no_invoices_in_period](https://docs.factuarea.com/es/errors/no_invoices_in_period): La operación trimestral no encontró facturas en el período pedido, así que no hay nada que empaquetar ni enviar. - [notification_not_found](https://docs.factuarea.com/es/errors/notification_not_found): El identificador no corresponde a ninguna notificación de la empresa autenticada, o la notificación quedó fuera de la ventana de retención. - [operation_regime_invalid](https://docs.factuarea.com/es/errors/operation_regime_invalid): El régimen de operación queda fuera del catálogo `general`, `intracomunitaria`, `importacion_exportacion`, `isp`. - [origin_not_allowed](https://docs.factuarea.com/es/errors/origin_not_allowed): La petición viene de un origen de navegador que la clave no acepta. - [pack_in_use](https://docs.factuarea.com/es/errors/pack_in_use): El pack está referenciado por documentos emitidos, así que borrarlo rompería su composición. - [pack_not_found](https://docs.factuarea.com/es/errors/pack_not_found): El identificador no resuelve a ningún pack de la empresa autenticada. - [pack_share_link_failed](https://docs.factuarea.com/es/errors/pack_share_link_failed): No se pudo generar el enlace para compartir el pack. El pack en sí no queda afectado. - [parameter_invalid](https://docs.factuarea.com/es/errors/parameter_invalid): Un value object construido a partir del payload rechazó el valor recibido. `error.subcode` dice cuál: código de impuesto, código de país, tipo impositivo, etc. - [parameter_invalid_boolean](https://docs.factuarea.com/es/errors/parameter_invalid_boolean): Un parámetro que debe ser booleano recibió un valor fuera de las representaciones aceptadas (`true`/`false`, `1`/`0`). - [parameter_invalid_cursor](https://docs.factuarea.com/es/errors/parameter_invalid_cursor): El cursor `starting_after` o `ending_before` no es un UUID válido, así que no puede apuntar a ninguna fila de la colección. - [parameter_invalid_empty](https://docs.factuarea.com/es/errors/parameter_invalid_empty): Un parámetro llegó con el valor vacío: un filtro `in` sin elementos, una comparación sin nada tras el operador, o un filtro de igualdad con la cadena vacía. - [parameter_invalid_enum](https://docs.factuarea.com/es/errors/parameter_invalid_enum): El valor queda fuera del conjunto cerrado que acepta el parámetro. En los listados cubre además un operador de filtro distinto de `eq`, `gte`, `lte`, `gt`, `lt`, `in` o `contains`. - [parameter_invalid_format](https://docs.factuarea.com/es/errors/parameter_invalid_format): El valor tiene el tipo correcto pero no la forma que exige el parámetro: una fecha, un patrón de identificador o una cabecera como `Factuarea-Version`. - [parameter_invalid_integer](https://docs.factuarea.com/es/errors/parameter_invalid_integer): Un parámetro que debe ser un número entero recibió algo que no se puede interpretar como tal, por ejemplo `limit=abc`. - [parameter_invalid_iso8601](https://docs.factuarea.com/es/errors/parameter_invalid_iso8601): Un filtro de rango (`gte`, `lte`, `gt`, `lt`) recibió un valor que no es numérico ni una fecha ISO 8601. - [parameter_invalid_range](https://docs.factuarea.com/es/errors/parameter_invalid_range): Un parámetro numérico quedó fuera de sus límites. El caso habitual es `limit`, que debe estar entre 1 y 100. - [parameter_invalid_string](https://docs.factuarea.com/es/errors/parameter_invalid_string): Un parámetro que debe ser texto recibió un array, un objeto o un valor que no se puede leer como cadena. - [parameter_invalid_url](https://docs.factuarea.com/es/errors/parameter_invalid_url): Un campo que debe contener una URL absoluta recibió un valor que no lo es, normalmente por faltarle el esquema o el host. - [parameter_invalid_uuid](https://docs.factuarea.com/es/errors/parameter_invalid_uuid): Un campo de identificador recibió un valor que no es un UUID válido. Todo `id` de recurso en v1 es un UUID. - [parameter_invalid_value](https://docs.factuarea.com/es/errors/parameter_invalid_value): El valor es sintácticamente correcto pero no admisible para este recurso: fuera del catálogo canónico del campo, o incoherente con el resto del payload. - [parameter_missing](https://docs.factuarea.com/es/errors/parameter_missing): El endpoint exige un parámetro que la petición no llevaba. `error.param` dice cuál. - [parameter_unknown](https://docs.factuarea.com/es/errors/parameter_unknown): La petición lleva un parámetro que el endpoint no acepta: un filtro fuera de su allowlist, un campo de `sort` no ordenable, o el `page` de paginación por offset — v1 pagina por cursor. - [payload_too_large](https://docs.factuarea.com/es/errors/payload_too_large): El body de la petición supera el tamaño admitido: 1 MB con carácter general, 6 MB en los endpoints que aceptan ficheros. - [payment_method_invalid](https://docs.factuarea.com/es/errors/payment_method_invalid): La misma allowlist cerrada que `invalid_payment_method`, reportada cuando el valor se rechaza al leer el campo de método de pago del payload. - [payment_method_required](https://docs.factuarea.com/es/errors/payment_method_required): Dar de alta una empresa gestionada cobra un asiento de inmediato, y la gestoría opera en modo real sin método de pago configurado. - [payout_reconciliation_amount_mismatch](https://docs.factuarea.com/es/errors/payout_reconciliation_amount_mismatch): El importe confirmado no coincide con el neto de la liquidación, así que la conciliación cerraría con una diferencia que nadie justifica. - [pdf_generation_failed](https://docs.factuarea.com/es/errors/pdf_generation_failed): El servicio de renderizado no pudo producir el PDF. El documento y sus datos están intactos: lo que falló es el fichero. - [product_in_use](https://docs.factuarea.com/es/errors/product_in_use): El producto está referenciado por documentos emitidos o por otras entradas del catálogo, y eliminarlo dejaría esas referencias colgando. - [product_not_found](https://docs.factuarea.com/es/errors/product_not_found): El identificador no resuelve a ningún producto de la empresa autenticada. - [profile_not_found](https://docs.factuarea.com/es/errors/profile_not_found): La cabecera `X-Active-Profile` nombra una empresa que no existe o que no pertenece al árbol de gestoría de la clave autenticada. Ambos casos responden igual para que la API nunca revele empresas de otros tenants. - [proforma_already_accepted](https://docs.factuarea.com/es/errors/proforma_already_accepted): El cliente ya aceptó la proforma, y la aceptación se registra una sola vez. - [proforma_already_rejected](https://docs.factuarea.com/es/errors/proforma_already_rejected): La proforma ya está marcada como rechazada. - [proforma_cannot_be_accepted](https://docs.factuarea.com/es/errors/proforma_cannot_be_accepted): La aceptación no procede desde el estado actual: una proforma facturada, cancelada o expirada ya no la admite. - [proforma_cannot_be_rejected](https://docs.factuarea.com/es/errors/proforma_cannot_be_rejected): El rechazo no procede desde el estado actual: una vez facturada, cancelada o expirada, la proforma está cerrada. - [proforma_cannot_be_sent](https://docs.factuarea.com/es/errors/proforma_cannot_be_sent): El envío por email no aplica a una proforma en estado terminal: no hay oferta viva que entregar. - [proforma_invalid_status_transition](https://docs.factuarea.com/es/errors/proforma_invalid_status_transition): El estado destino no es alcanzable desde el actual: un borrador se acepta, se cancela o expira; una proforma aceptada se factura, se rechaza o expira; facturada, cancelada y expirada son terminales. - [proforma_not_convertible_in_current_state](https://docs.factuarea.com/es/errors/proforma_not_convertible_in_current_state): Convertir en factura exige que el cliente haya aceptado la proforma; desde cualquier otro estado no hay acuerdo que facturar. - [proforma_not_deletable_in_current_state](https://docs.factuarea.com/es/errors/proforma_not_deletable_in_current_state): Solo se borra una proforma en borrador. Una vez aceptada, rechazada o facturada forma parte del rastro comercial. - [proforma_not_draft](https://docs.factuarea.com/es/errors/proforma_not_draft): La operación solo tiene sentido mientras la proforma es un borrador, y esta ya ha avanzado. - [proforma_not_editable_in_current_state](https://docs.factuarea.com/es/errors/proforma_not_editable_in_current_state): Solo una proforma en borrador admite edición. Una vez aceptada, rechazada, expirada, facturada o cancelada, su contenido queda fijado. - [proforma_not_found](https://docs.factuarea.com/es/errors/proforma_not_found): El identificador no resuelve a ninguna proforma de la empresa autenticada. - [proforma_requires_at_least_one_line](https://docs.factuarea.com/es/errors/proforma_requires_at_least_one_line): La proforma no lleva líneas, así que no hay importe que poner delante del cliente. - [public_link_expires_at_exceeds_max_days](https://docs.factuarea.com/es/errors/public_link_expires_at_exceeds_max_days): La caducidad pedida para el enlace público supera la ventana máxima que permite tu plan para documentos compartidos. - [purchase_invoice_already_exists](https://docs.factuarea.com/es/errors/purchase_invoice_already_exists): Ese proveedor ya tiene registrada una factura de compra con el mismo número. El par proveedor + número identifica el documento sin ambigüedad y evita contabilizar dos veces el mismo gasto. - [purchase_invoice_not_deletable_in_current_state](https://docs.factuarea.com/es/errors/purchase_invoice_not_deletable_in_current_state): Solo se borran las facturas de compra en borrador o canceladas. Una pendiente o pagada forma parte del libro de gastos. - [purchase_invoice_not_draft](https://docs.factuarea.com/es/errors/purchase_invoice_not_draft): La operación solo aplica mientras la factura de compra es un borrador, y esta ya está registrada. - [purchase_invoice_not_editable_in_current_state](https://docs.factuarea.com/es/errors/purchase_invoice_not_editable_in_current_state): Solo se edita una factura de compra en borrador. Una vez registrada como pendiente, pagada o cancelada, su contenido respalda un apunte contable. - [purchase_invoice_not_found](https://docs.factuarea.com/es/errors/purchase_invoice_not_found): El identificador no resuelve a ninguna factura de compra de la empresa autenticada. - [purchase_invoice_requires_at_least_one_line](https://docs.factuarea.com/es/errors/purchase_invoice_requires_at_least_one_line): La factura de compra no lleva líneas, así que no hay gasto ni IVA soportado que registrar. - [quote_already_accepted](https://docs.factuarea.com/es/errors/quote_already_accepted): El presupuesto ya estaba aprobado, y la aprobación se registra una sola vez. - [quote_already_rejected](https://docs.factuarea.com/es/errors/quote_already_rejected): El presupuesto ya está marcado como rechazado. - [quote_expired](https://docs.factuarea.com/es/errors/quote_expired): El presupuesto pasó su fecha de validez, así que las condiciones ofrecidas ya no vinculan y no se puede aprobar ni convertir tal cual. - [quote_not_found](https://docs.factuarea.com/es/errors/quote_not_found): El identificador no resuelve a ningún presupuesto de la empresa autenticada. - [rate_limit_exceeded](https://docs.factuarea.com/es/errors/rate_limit_exceeded): La clave envió más peticiones de las que permite su ritmo en la ventana actual. - [receipt_not_available](https://docs.factuarea.com/es/errors/receipt_not_available): No hay justificante que emitir porque el documento no tiene ningún cobro registrado detrás. - [record_already_accepted](https://docs.factuarea.com/es/errors/record_already_accepted): La AEAT ya aceptó el registro. La aceptación es terminal y su contenido queda congelado como parte de la cadena de huellas. - [record_immutable](https://docs.factuarea.com/es/errors/record_immutable): El registro pertenece a un ledger de solo-adición: una vez escrito, su contenido fiscal queda cerrado a modificaciones y a borrado. - [record_not_rejected](https://docs.factuarea.com/es/errors/record_not_rejected): La subsanación solo aplica a registros que la AEAT rechazó por datos. Este registro está en otro estado — un fallo técnico, por ejemplo, lo cubre el reintento automático. - [record_not_subsanable](https://docs.factuarea.com/es/errors/record_not_subsanable): El registro no se puede subsanar: no es un registro de alta, o no tiene factura de origen desde la que regenerar su contenido. - [recurring_already_active](https://docs.factuarea.com/es/errors/recurring_already_active): La recurrencia ya está en marcha, así que no hay nada que activar. Código legacy conservado por compatibilidad: los endpoints actuales reportan esto como `recurring_invoice_already_active`. - [recurring_invoice_already_active](https://docs.factuarea.com/es/errors/recurring_invoice_already_active): La recurrencia ya está en marcha. - [recurring_invoice_already_cancelled](https://docs.factuarea.com/es/errors/recurring_invoice_already_cancelled): La recurrencia ya estaba cancelada, y la cancelación es terminal. - [recurring_invoice_already_paused](https://docs.factuarea.com/es/errors/recurring_invoice_already_paused): La recurrencia ya está pausada, así que pausarla otra vez no cambia nada. - [recurring_invoice_cancelled_cannot_resume](https://docs.factuarea.com/es/errors/recurring_invoice_cancelled_cannot_resume): Una recurrencia cancelada no se reanuda: la cancelación la cierra definitivamente, a diferencia de la pausa. - [recurring_invoice_cannot_run](https://docs.factuarea.com/es/errors/recurring_invoice_cannot_run): La recurrencia no puede generar una factura ahora mismo: no está en marcha, su ciclo terminó, o le faltan datos que la factura necesita. `error.message` indica el motivo concreto. - [recurring_invoice_has_generated_invoices](https://docs.factuarea.com/es/errors/recurring_invoice_has_generated_invoices): La recurrencia ya generó facturas, y esas facturas dependen de ella para su trazabilidad. - [recurring_invoice_not_found](https://docs.factuarea.com/es/errors/recurring_invoice_not_found): El identificador no resuelve a ninguna recurrencia de la empresa autenticada. - [recurring_invoice_requires_at_least_one_line](https://docs.factuarea.com/es/errors/recurring_invoice_requires_at_least_one_line): La recurrencia no lleva líneas, así que cada factura generada saldría vacía. - [recurring_not_active](https://docs.factuarea.com/es/errors/recurring_not_active): La operación necesita una recurrencia en marcha y esta está pausada, completada o cancelada. Código legacy conservado por compatibilidad con integraciones antiguas. - [register_sealing_failed](https://docs.factuarea.com/es/errors/register_sealing_failed): El sellado criptográfico del registro no se completó, así que el cierre quedó sin firmar en lugar de sellado con una firma rota. - [reminder_not_applicable](https://docs.factuarea.com/es/errors/reminder_not_applicable): El recordatorio de pago no procede: la factura no está en `sent` ni `overdue`, no hay email de destinatario, falta el enlace público o está desactivado, o ya salió otro recordatorio en las últimas 24 horas. - [replay_delivery_not_retryable](https://docs.factuarea.com/es/errors/replay_delivery_not_retryable): Solo se reenvían las entregas fallidas. Una entrega que llegó bien, o una todavía en curso, no tiene nada que reenviar. - [replay_event_expired](https://docs.factuarea.com/es/errors/replay_event_expired): El evento que respalda la entrega fue purgado por la política de retención de 30 días, así que ya no queda payload que reenviar. - [report_format_invalid](https://docs.factuarea.com/es/errors/report_format_invalid): El formato queda fuera del catálogo `txt_aeat`, `pdf`, `excel`. - [requires_annulment](https://docs.factuarea.com/es/errors/requires_annulment): El contenido regenerado cambia un campo que entra en la huella —NIF del emisor, serie y número, fecha de expedición, tipo de factura, cuota o importe total— y la cadena no se puede reescribir. - [resource_already_exists](https://docs.factuarea.com/es/errors/resource_already_exists): Crear el objeto duplicaría uno que ya existe bajo una clave única — NIF, SKU, external id. `error.details.existing_resource_id` apunta al objeto que ya ocupa ese valor. - [resource_conflict](https://docs.factuarea.com/es/errors/resource_conflict): La operación chocó con el estado actual del recurso y no aplica ningún código de conflicto más específico. - [resource_immutable](https://docs.factuarea.com/es/errors/resource_immutable): El objeto está cerrado a cambios para esta operación: su estado o su registro contable impiden modificarlo. - [resource_locked](https://docs.factuarea.com/es/errors/resource_locked): Otra operación retiene el recurso hasta terminar: las escrituras concurrentes sobre el mismo objeto se serializan en lugar de entrelazarse. - [resource_not_deletable](https://docs.factuarea.com/es/errors/resource_not_deletable): El objeto existe, pero su estado o sus dependientes bloquean el borrado. En los borrados masivos este es el código por fila de cada entrada que no se pudo eliminar. - [resource_not_found](https://docs.factuarea.com/es/errors/resource_not_found): El identificador no resuelve a nada visible para la empresa autenticada. Los objetos de otra empresa responden exactamente igual, a propósito. - [route_not_found](https://docs.factuarea.com/es/errors/route_not_found): La ruta no corresponde a ningún endpoint de v1. Suele ser una errata, un prefijo `/v1` ausente o una ruta de otra área de la API. - [scheduled_for_in_past](https://docs.factuarea.com/es/errors/scheduled_for_in_past): `scheduled_for` no es estrictamente futuro, así que no hay ninguna espera que reservar. - [scope_not_allowed_by_plan](https://docs.factuarea.com/es/errors/scope_not_allowed_by_plan): Uno de los scopes pedidos pertenece a un módulo que el plan no incluye, así que la clave nacería con un permiso que nunca podría ejercer. - [scope_not_allowed_in_sandbox](https://docs.factuarea.com/es/errors/scope_not_allowed_in_sandbox): Una clave de prueba no puede nacer con scopes de módulos vetados en sandbox. - [seat_charge_failed](https://docs.factuarea.com/es/errors/seat_charge_failed): El cobro inmediato del prorrateo del asiento fue rechazado: la tarjeta se denegó, necesita autenticación, o el proveedor de pago estaba inaccesible. La empresa no se crea si el asiento no se cobra. - [send_failed](https://docs.factuarea.com/es/errors/send_failed): El documento no se entregó por email: el proveedor de correo rechazó el mensaje o estaba inaccesible. - [series_already_archived](https://docs.factuarea.com/es/errors/series_already_archived): La serie ya estaba archivada, y el archivado no se repite: una segunda llamada indica que el cliente ha perdido el estado real. - [series_code_immutable_with_documents](https://docs.factuarea.com/es/errors/series_code_immutable_with_documents): Cambiar el prefijo de una serie que ya emitió documentos reescribiría retroactivamente su identificador fiscal, mientras los clientes y la AEAT tienen el número original. - [series_has_documents](https://docs.factuarea.com/es/errors/series_has_documents): La serie ya numeró documentos, así que no se puede eliminar: la secuencia correlativa tiene que seguir siendo auditable. - [series_immutable](https://docs.factuarea.com/es/errors/series_immutable): Las series no son editables ni eliminables vía API: la continuidad legal de la numeración exige que su prefijo, su año y su contador se queden como están. - [series_initial_number_creates_gap](https://docs.factuarea.com/es/errors/series_initial_number_creates_gap): El número inicial salta más allá del siguiente correlativo natural habiendo documentos del año en curso, y ese hueco en la secuencia no es admisible para la AEAT. - [series_locked_by_verifactu](https://docs.factuarea.com/es/errors/series_locked_by_verifactu): Al menos una factura de la serie tiene un registro de facturación aceptado por la AEAT, lo que congela el prefijo, el año y la base de numeración de la serie. - [series_not_found](https://docs.factuarea.com/es/errors/series_not_found): El identificador no resuelve a ninguna serie de numeración de la empresa autenticada. - [series_type_invalid](https://docs.factuarea.com/es/errors/series_type_invalid): El tipo de documento de la serie queda fuera del catálogo `invoice`, `quote`, `delivery_note`, `proforma`, `purchase_invoice`, `recurring_invoice`. - [series_year_locked](https://docs.factuarea.com/es/errors/series_year_locked): La serie ya emitió documentos en su año vigente. Mover el año dejaría esos documentos apuntando a un ejercicio vacío mientras su base imponible está en otro. - [service_unavailable](https://docs.factuarea.com/es/errors/service_unavailable): El servicio, o una dependencia que necesita, no puede responder temporalmente. - [signature_payload_too_large](https://docs.factuarea.com/es/errors/signature_payload_too_large): La imagen de la firma supera el tamaño admitido para el campo. - [sii_excluded](https://docs.factuarea.com/es/errors/sii_excluded): La empresa está registrada en el SII, y los obligados al SII quedan excluidos del reglamento VeriFactu. - [simplified_invoice_cannot_be_substituted](https://docs.factuarea.com/es/errors/simplified_invoice_cannot_be_substituted): Una de las facturas de la lista de sustitución no se puede sustituir: no es simplificada, está cancelada o anulada, pertenece a otra empresa, o ya tiene sustitutiva. - [simplified_invoice_not_allowed](https://docs.factuarea.com/es/errors/simplified_invoice_not_allowed): La operación no es elegible para factura simplificada: supera los 3.000 €, o es una entrega intracomunitaria, una exportación, una operación con inversión del sujeto pasivo, o el cliente necesita factura completa para deducir el IVA. - [simplified_limit_exceeded](https://docs.factuarea.com/es/errors/simplified_limit_exceeded): Las líneas llevarían la factura simplificada (F2) por encima del tope legal absoluto de 3.000 € IVA incluido. - [sku_already_exists](https://docs.factuarea.com/es/errors/sku_already_exists): Otro producto de la empresa ya usa ese SKU, y el SKU identifica al artículo sin ambigüedad dentro del catálogo. - [stripe_payout_already_reconciled](https://docs.factuarea.com/es/errors/stripe_payout_already_reconciled): La liquidación ya estaba conciliada, y la conciliación es terminal: repetirla contabilizaría dos veces el apunte bancario. - [stripe_payout_not_found](https://docs.factuarea.com/es/errors/stripe_payout_not_found): El identificador no resuelve a ninguna liquidación de la empresa autenticada. - [suplido_line_cannot_carry_taxes](https://docs.factuarea.com/es/errors/suplido_line_cannot_carry_taxes): La línea de suplido lleva carga propia: tipo de IVA, retención, recargo de equivalencia, descuento, clave de régimen, causa de exención o producto/pack. Un suplido no es una operación del emisor, así que repercutir un impuesto sobre él sería tributar por una entrega que no has hecho, y ligarlo a un producto movería un stock que nunca has vendido. - [suplido_not_allowed_in_simplified_invoice](https://docs.factuarea.com/es/errors/suplido_not_allowed_in_simplified_invoice): La factura es simplificada (F2) y una simplificada no identifica al destinatario. Sin destinatario identificado no hay a quién acreditar el pago por cuenta ajena, así que el importe no admite el tratamiento de suplido en este tipo de factura. - [suplido_requires_source_invoice_reference](https://docs.factuarea.com/es/errors/suplido_requires_source_invoice_reference): La línea de suplido no informa `source_invoice_reference`, el número del justificante que el tercero expidió a nombre del cliente. Sin ese justificante el pago no se acredita como hecho por cuenta ajena y Hacienda lo trataría como base imponible propia del emisor, con su IVA repercutido. - [supplier_has_documents](https://docs.factuarea.com/es/errors/supplier_has_documents): El proveedor está referenciado por facturas de compra registradas, y borrarlo dejaría esos gastos sin la parte que los emitió. - [supplier_not_found](https://docs.factuarea.com/es/errors/supplier_not_found): El identificador no resuelve a ningún proveedor de la empresa autenticada. - [system_tax_default_modification_forbidden](https://docs.factuarea.com/es/errors/system_tax_default_modification_forbidden): Los defaults de los impuestos del catálogo compartido no se fijan sobre el impuesto: el catálogo es global y la preferencia es de tu empresa. - [system_tax_immutable](https://docs.factuarea.com/es/errors/system_tax_immutable): El impuesto pertenece al catálogo canónico AEAT que trae el producto. Su tipo, su código y su nombre son fijos para que todas las empresas compartan la misma referencia fiscal. - [system_tax_immutable_field](https://docs.factuarea.com/es/errors/system_tax_immutable_field): La actualización toca un campo congelado en un impuesto del sistema; `error.param` dice cuál. - [system_tax_undeletable](https://docs.factuarea.com/es/errors/system_tax_undeletable): Los impuestos del sistema forman parte del catálogo fiscal compartido y no se eliminan: borrarlos rompería los documentos que los referencian. - [tax_applies_to_invalid](https://docs.factuarea.com/es/errors/tax_applies_to_invalid): El ámbito del impuesto queda fuera del catálogo `sale`, `purchase`, `both`. - [tax_code_already_exists](https://docs.factuarea.com/es/errors/tax_code_already_exists): Otro impuesto del catálogo ya usa ese código, y el código identifica al impuesto sin ambigüedad. - [tax_id_already_exists](https://docs.factuarea.com/es/errors/tax_id_already_exists): Otro cliente de la empresa ya tiene ese NIF, y el NIF identifica a la parte sin ambigüedad dentro de una empresa. - [tax_id_required](https://docs.factuarea.com/es/errors/tax_id_required): La operación necesita el número de identificación fiscal (NIF, CIF o NIE) de la parte implicada y el registro no lo tiene. - [tax_in_use](https://docs.factuarea.com/es/errors/tax_in_use): El impuesto está referenciado por documentos, productos o proveedores. Eliminarlo dejaría documentos históricos sin su referencia fiscal. - [tax_inactive_cannot_be_default](https://docs.factuarea.com/es/errors/tax_inactive_cannot_be_default): Un impuesto desactivado no puede quedar como default, ni global ni por tipo de documento: sería un default oculto que ningún formulario puede elegir. - [tax_not_found](https://docs.factuarea.com/es/errors/tax_not_found): El identificador no corresponde a ningún impuesto del catálogo accesible para esta empresa. - [tax_report_not_found](https://docs.factuarea.com/es/errors/tax_report_not_found): El identificador no resuelve a ninguna declaración de la empresa autenticada. - [tax_report_type_invalid](https://docs.factuarea.com/es/errors/tax_report_type_invalid): El tipo de declaración queda fuera del catálogo `modelo_303`, `modelo_347`, `modelo_130`. - [tax_type_invalid](https://docs.factuarea.com/es/errors/tax_type_invalid): El tipo de impuesto queda fuera del catálogo `vat`, `retention`, `surcharge`, `other`. - [timeout_seconds_out_of_range](https://docs.factuarea.com/es/errors/timeout_seconds_out_of_range): `timeout_seconds` queda fuera del rango de 1 a 30 segundos. - [too_many_auth_failures](https://docs.factuarea.com/es/errors/too_many_auth_failures): Llegaron demasiados intentos fallidos de autenticación desde la misma dirección, así que queda bloqueada temporalmente para frenar los intentos de adivinar credenciales. - [too_many_custom_headers](https://docs.factuarea.com/es/errors/too_many_custom_headers): El endpoint declara más de 20 cabeceras personalizadas. - [unknown_filter](https://docs.factuarea.com/es/errors/unknown_filter): Un listado recibió un filtro que no conoce. Los parsers canónicos de v1 reportan esto como `parameter_unknown`; este código sobrevive para los endpoints aún sin migrar. - [unsupported_api_version](https://docs.factuarea.com/es/errors/unsupported_api_version): La cabecera `Factuarea-Version` está bien formada pero nombra una versión fuera del conjunto soportado. - [unsupported_format](https://docs.factuarea.com/es/errors/unsupported_format): El formato pedido no está disponible para este modelo: no toda declaración produce todas las salidas. - [unsupported_media_type](https://docs.factuarea.com/es/errors/unsupported_media_type): Una petición con body declaró un `Content-Type` distinto de `application/json`. - [verifactu_already_submitted](https://docs.factuarea.com/es/errors/verifactu_already_submitted): La factura ya tiene su registro de alta. Existe exactamente un alta por factura, así que una segunda rompería la idempotencia de la cadena. - [verifactu_mode_invalid](https://docs.factuarea.com/es/errors/verifactu_mode_invalid): El modo queda fuera del catálogo `verifactu` / `no_verifactu`. - [verifactu_not_eligible](https://docs.factuarea.com/es/errors/verifactu_not_eligible): La factura no se puede registrar ahora mismo en la AEAT: la empresa no está en modo VeriFactu, no tiene certificado activo, o el certificado está revocado o emitido para otro NIF. - [verifactu_record_not_found](https://docs.factuarea.com/es/errors/verifactu_record_not_found): El identificador no corresponde a ningún registro de facturación de la empresa autenticada. - [verifactu_transmission_failed](https://docs.factuarea.com/es/errors/verifactu_transmission_failed): El envío del registro a la AEAT no llegó a completarse: el endpoint estaba inaccesible o respondió con una incidencia. - [webhook_delivery_not_found](https://docs.factuarea.com/es/errors/webhook_delivery_not_found): El identificador no corresponde a ningún intento de entrega, o la entrega queda fuera de la ventana de retención del histórico. - [webhook_endpoint_degraded](https://docs.factuarea.com/es/errors/webhook_endpoint_degraded): El endpoint está degradado tras fallos repetidos de entrega, así que los pings de prueba se rechazan mientras siga en ese estado. - [webhook_endpoint_not_found](https://docs.factuarea.com/es/errors/webhook_endpoint_not_found): El identificador no resuelve a ningún endpoint de webhook de la empresa autenticada. - [webhook_secret_recently_rotated](https://docs.factuarea.com/es/errors/webhook_secret_recently_rotated): El secreto de firma se rotó hace menos de cinco minutos. La ventana de gracia permite que tu receptor acepte ambos secretos durante el cambio; rotar otra vez dentro de ella invalidaría firmas todavía en vuelo. - [Resumen de los SDKs](https://docs.factuarea.com/es/sdks): SDKs oficiales de TypeScript y PHP para la API de Factuarea — instala @factuarea/sdk o factuarea/factuarea-php y obtén reintentos, idempotencia, paginación por cursor, errores tipados y verificación de webhooks de serie. - [PHP](https://docs.factuarea.com/es/sdks/php): Instala factuarea/factuarea-php con Composer, autentícate y crea tu primera factura. PSR-4, basado en Guzzle, PHP 8.2+. - [TypeScript](https://docs.factuarea.com/es/sdks/typescript): Instala @factuarea/sdk para Node.js, autentícate y crea tu primera factura. ESM + CommonJS dual, declaraciones de tipos completas, Node 20+. - [Listar todos los saldos de ausencias](https://docs.factuarea.com/es/api-reference/absence-balances/public-api.v1.absence-balances.list): Lista los saldos de ausencias de tu empresa con paginación por cursor. Cada saldo son los días devengados, arrastrados y consumidos de un empleado para un tipo de ausencia en un año dado, con los `available_days` resultantes. Admite filtrar por `employee_id` (UUID v7), `absence_type_id` (UUID v7) y `year`. Los importes de días son cadenas decimales exactas. - [Obtener un saldo de ausencias](https://docs.factuarea.com/es/api-reference/absence-balances/public-api.v1.absence-balances.show): Obtén un único saldo de ausencias por su `id` (UUID v7), incluidos sus días devengados, arrastrados, consumidos y disponibles para el empleado, tipo de ausencia y año. Un saldo perteneciente a otra empresa devuelve 404 `absence_balance_not_found` (anti-enumeración). - [Obtener el calendario de ausencias del equipo](https://docs.factuarea.com/es/api-reference/absence-calendar/public-api.v1.absence-calendar.show): Devuelve el calendario mensual de ausencias de tu equipo para un `year` y `month` dados: cada empleado activo con sus ausencias aprobadas de ese mes (cada una coloreada por su tipo de ausencia) y los festivos que aplican, mantenidos separados de las ausencias. Opcionalmente acotado a un único `employee_id` (UUID v7). Un recurso computado: expone `employee_id` por miembro, nunca un `id`. - [Archivar una política de ausencias](https://docs.factuarea.com/es/api-reference/absence-policies/public-api.v1.absence-policies.archive): Archiva una política de ausencias (transición `active` → `archived`), retirándola del uso pero conservándola. Sin cuerpo de la petición. Devuelve 422 si ya está archivada. Reversible mediante desarchivar. - [Asignar una política a empleados](https://docs.factuarea.com/es/api-reference/absence-policies/public-api.v1.absence-policies.assign): Asigna la política de ausencias a uno o más empleados. `employee_ids` (una lista no vacía de UUID v7, cada uno perteneciente a tu empresa) es obligatorio; un empleado desconocido devuelve 422. Devuelve la política con su recuento de empleados asignados actualizado. - [Listar los empleados asignados a una política](https://docs.factuarea.com/es/api-reference/absence-policies/public-api.v1.absence-policies.assignments): Lista los empleados asignados a esta política de ausencias (su `employee_id` UUID v7 y su nombre), como una lista plana bajo `{ "data": [ … ] }`. - [Configurar el arrastre de fin de año de una política](https://docs.factuarea.com/es/api-reference/absence-policies/public-api.v1.absence-policies.carryover): Configura cuánto saldo sin usar se arrastra a fin de año para esta política de ausencias. `carryover_type` (`none`/`capped`/`unlimited`) es obligatorio; `carryover_max_days` es obligatorio y positivo solo cuando `carryover_type` es `capped`. Los opcionales `carryover_expiry_month` (1..12) y `carryover_expiry_day` fijan cuándo caduca el saldo arrastrado. Una política perteneciente a otra empresa devuelve 404 `absence_policy_not_found` (anti-enumeración). Devuelve la política actualizada. - [Crear una política de ausencias](https://docs.factuarea.com/es/api-reference/absence-policies/public-api.v1.absence-policies.create): Crea una política de ausencias para la empresa autenticada (resuelta desde la API key, nunca desde el payload). `name`, `allowance_type` (`limited`/`unlimited`) y `accrual_method` (`annual`/`monthly`) son obligatorios; `allowance_days` es obligatorio y positivo solo cuando `allowance_type` es `limited`. `absence_type_ids` es la lista de UUID (v7) de tipos de ausencia que la política cubre (puede estar vacía); un tipo perteneciente a otra empresa devuelve 422. Devuelve la política creada con su `id` generado (UUID v7). - [Listar todas las políticas de ausencias](https://docs.factuarea.com/es/api-reference/absence-policies/public-api.v1.absence-policies.list): Lista las políticas de ausencias de tu empresa con paginación por cursor. Admite filtrar por `status` (`active`/`archived`) y `accrual_method` (`annual`/`monthly`), más una `search` de texto libre sobre el nombre de la política. - [Obtener una política de ausencias](https://docs.factuarea.com/es/api-reference/absence-policies/public-api.v1.absence-policies.show): Obtén una única política de ausencias por su `id` (UUID v7), incluidos los UUID de sus tipos de ausencia asociados y el recuento de empleados asignados. Una política perteneciente a otra empresa devuelve 404 `absence_policy_not_found` (anti-enumeración). - [Desarchivar una política de ausencias](https://docs.factuarea.com/es/api-reference/absence-policies/public-api.v1.absence-policies.unarchive): Desarchiva una política de ausencias (transición `archived` → `active`), devolviéndola al uso. Sin cuerpo de la petición. Devuelve 422 si ya está activa. - [Desasignar una política de empleados](https://docs.factuarea.com/es/api-reference/absence-policies/public-api.v1.absence-policies.unassign): Retira la asignación de la política de ausencias de uno o más empleados. `employee_ids` (una lista no vacía de UUID v7) es obligatorio; retirar una asignación que no existe es un no-op. Devuelve la política con su recuento de empleados asignados actualizado. - [Actualizar una política de ausencias](https://docs.factuarea.com/es/api-reference/absence-policies/public-api.v1.absence-policies.update): Actualiza parcialmente una política de ausencias: solo se cambian los campos presentes en el payload; los omitidos conservan su valor actual. Cuando se proporciona `absence_type_ids` reemplaza por completo los tipos asociados. Devuelve la política actualizada. - [Aprobar una solicitud de ausencia](https://docs.factuarea.com/es/api-reference/absence-requests/public-api.v1.absence-requests.approve): Aprueba una solicitud de ausencia pendiente (transición `pending` → `approved`), consumiendo el saldo del empleado. Sin cuerpo de la petición (se admite una `note` opcional). Un revisor no puede aprobar la solicitud que él mismo creó (422). Devuelve la solicitud actualizada. - [Cancelar una solicitud de ausencia](https://docs.factuarea.com/es/api-reference/absence-requests/public-api.v1.absence-requests.cancel): Cancela una solicitud de ausencia. Si estaba aprobada, el saldo consumido se devuelve. Sin cuerpo de la petición. Una solicitud perteneciente a otra empresa devuelve 404 `absence_request_not_found` (anti-enumeración). Devuelve la solicitud actualizada. - [Crear una solicitud de ausencia](https://docs.factuarea.com/es/api-reference/absence-requests/public-api.v1.absence-requests.create): Crea una solicitud de ausencia para la empresa autenticada (resuelta desde la API key, nunca desde el payload). `employee_id` (UUID v7) es obligatorio — una API key actúa como un sistema, así que debe indicarse el empleado destino. `absence_type_id` (UUID v7) y el rango `start_date`/`end_date` (`YYYY-MM-DD`, fin igual o posterior al inicio) son obligatorios; `note` es opcional. La cantidad solicitada se computa en días laborables menos los festivos aplicables. Si el tipo de ausencia no requiere aprobación, se autoaprueba y consume el saldo. Devuelve la solicitud creada con su `id` generado (UUID v7). - [Listar todas las solicitudes de ausencia](https://docs.factuarea.com/es/api-reference/absence-requests/public-api.v1.absence-requests.list): Lista las solicitudes de ausencia de tu empresa con paginación por cursor. Admite filtrar por `employee_id` (UUID v7), `absence_type_id` (UUID v7), `status` (`pending`/`approved`/`rejected`/`cancelled`) y por rango de fechas (`from`/`to`, `YYYY-MM-DD`). - [Rechazar una solicitud de ausencia](https://docs.factuarea.com/es/api-reference/absence-requests/public-api.v1.absence-requests.reject): Rechaza una solicitud de ausencia pendiente (transición `pending` → `rejected`). Se requiere un `reason` (422 sin él); rechazar ni consume ni libera saldo. Devuelve la solicitud actualizada. - [Obtener una solicitud de ausencia](https://docs.factuarea.com/es/api-reference/absence-requests/public-api.v1.absence-requests.show): Obtén una única solicitud de ausencia por su `id` (UUID v7), incluidos su tipo, rango de fechas, cantidad solicitada, estado del ciclo de vida y campos de revisión. Una solicitud perteneciente a otra empresa devuelve 404 `absence_request_not_found` (anti-enumeración). - [Archivar un tipo de ausencia](https://docs.factuarea.com/es/api-reference/absence-types/public-api.v1.absence-types.archive): Archiva un tipo de ausencia (transición `active` → `archived`), retirándolo del uso pero conservándolo. Sin cuerpo de la petición. Devuelve 422 si ya está archivado. Reversible mediante desarchivar. - [Crear un tipo de ausencia](https://docs.factuarea.com/es/api-reference/absence-types/public-api.v1.absence-types.create): Crea un tipo de ausencia para la empresa autenticada (resuelta desde la API key, nunca desde el payload). `name`, `is_paid`, `requires_approval`, `measurement_unit` (`days`/`hours`), `color` (hex `#RRGGBB`) y `visibility` (`everyone`/`managers_only`) son todos obligatorios. Devuelve el tipo creado con su `id` generado (UUID v7). - [Listar todos los tipos de ausencia](https://docs.factuarea.com/es/api-reference/absence-types/public-api.v1.absence-types.list): Lista los tipos de ausencia de tu empresa con paginación por cursor. Admite filtrar por `status` (`active`/`archived`) y `measurement_unit` (`days`/`hours`), más una `search` de texto libre sobre el nombre del tipo. - [Obtener un tipo de ausencia](https://docs.factuarea.com/es/api-reference/absence-types/public-api.v1.absence-types.show): Obtén un único tipo de ausencia por su `id` (UUID v7). Un tipo perteneciente a otra empresa devuelve 404 `absence_type_not_found` (anti-enumeración). - [Desarchivar un tipo de ausencia](https://docs.factuarea.com/es/api-reference/absence-types/public-api.v1.absence-types.unarchive): Desarchiva un tipo de ausencia (transición `archived` → `active`), devolviéndolo al uso. Sin cuerpo de la petición. Devuelve 422 si ya está activo. - [Actualizar un tipo de ausencia](https://docs.factuarea.com/es/api-reference/absence-types/public-api.v1.absence-types.update): Actualiza parcialmente un tipo de ausencia: solo se cambian los campos presentes en el payload; los omitidos conservan su valor actual. Devuelve el tipo actualizado. - [Crear una API key](https://docs.factuarea.com/es/api-reference/account/public-api.v1.account.api_keys.create): Crea una API key nueva y devuelve su `secret` en claro exactamente una vez —guárdalo ahora, no podrá recuperarse después. Solicitar un scope por encima del plan del titular o fuera del catálogo devuelve 422. Pasa `environment: test` para acuñar una clave de sandbox (`fact_test_`) sin efectos en el mundo real; omítelo para una clave live (`fact_live_`). - [Listar tus API keys](https://docs.factuarea.com/es/api-reference/account/public-api.v1.account.api_keys.list): Lista las API keys de la empresa autenticada con paginación por cursor. Cada clave expone su `prefix`, `scopes`, `tier`, `environment` (`live`/`test`) y timestamps de ciclo de vida. El secret en claro nunca se devuelve: se muestra una vez, en la creación o la rotación. - [Revocar una API key](https://docs.factuarea.com/es/api-reference/account/public-api.v1.account.api_keys.revoke): Revoca una API key de inmediato e irreversiblemente. Las peticiones posteriores autenticadas con esa clave fallan con 401. Puedes revocar la clave en uso actualmente —hacerlo corta tu propio acceso. Revocar una clave de otra empresa devuelve 404 `api_key_not_found`. - [Rotar el secreto de una API key](https://docs.factuarea.com/es/api-reference/account/public-api.v1.account.api_keys.rotate_secret): Invalida el secret actual de una API key de inmediato, genera un `prefix` + `secret` nuevos, y devuelve el nuevo secret en claro exactamente una vez. Cualquier petición hecha con el secret anterior deja de autenticar al instante. Irreversible. - [Recuperar una API key](https://docs.factuarea.com/es/api-reference/account/public-api.v1.account.api_keys.show): Recupera una sola API key de la empresa autenticada por su `id` (UUID v7). El secret en claro nunca se incluye. Una clave que pertenece a otra empresa devuelve 404 `api_key_not_found` (anti-enumeración). - [Obtener los detalles de facturación de la cuenta](https://docs.factuarea.com/es/api-reference/account/public-api.v1.account.billing): Devuelve el resumen de facturación por suscripción de la empresa autenticada: suscripción del plan base (estado, prueba, fin del periodo actual, cambio de plan pendiente), suscripción de asientos de gestoría (cantidad, empresas gestionadas activas, coste por asiento con IVA, total recurrente, próxima factura) y método de pago por defecto. Las empresas gestionadas (plan `gestionada`) reciben `managed: true` sin los datos de facturación del maestro. Los importes van en céntimos enteros; los importes no resueltos son `null`, nunca un 0 engañoso. - [Lista las plantillas de personalización disponibles](https://docs.factuarea.com/es/api-reference/account/public-api.v1.account.personalization.templates): Lista las plantillas PDF disponibles para el plan de la cuenta (según el plan) más el formato aceptado para el `accent_color`. Úsalo para descubrir qué slugs de `pdf_template` y colores pueden fijarse vía `PATCH /v1/account/personalization`. - [Actualiza la personalización de la cuenta](https://docs.factuarea.com/es/api-reference/account/public-api.v1.account.personalization.update): Fija en una sola actualización parcial el idioma de emisión de facturas, la plantilla PDF y el color de acento de la empresa; los campos omitidos mantienen su valor. `language` es uno de `es`, `en`, `ca`; `pdf_template` es un slug del catálogo `PdfTemplate`; `accent_color` es un color hex `#RRGGBB`. Devuelve el recurso `Account` actualizado. - [Obtener los detalles de la cuenta](https://docs.factuarea.com/es/api-reference/account/public-api.v1.account.show): Endpoint de cuenta estilo Stripe: devuelve la empresa autenticada junto con su plan, sus add-ons y los metadatos de la API key en uso (environment, scopes). Úsalo para introspeccionar qué puede hacer la clave actual. - [Verificar la cuenta contra el censo de la AEAT](https://docs.factuarea.com/es/api-reference/account/public-api.v1.account.verify_census): Comprueba el par nombre + NIF persistido de la empresa contra el censo de la AEAT (VNifV2) para anticipar rechazos VeriFactu 4104. Sin cuerpo de petición: el endpoint verifica siempre los datos fiscales persistidos de la cuenta. Fail-open — si la AEAT no está disponible, la llamada devuelve 200 con `status: unavailable`. Las claves de prueba (`fact_test_`) devuelven estados deterministas según el NIF mágico sin contactar con la AEAT. - [Listar la línea temporal de actividad del cliente](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.activities): Devuelve la línea de tiempo de auditoría de un cliente combinando sus propios eventos de dominio más los eventos de factura, presupuesto, albarán, proforma y factura de compra que lo referencian. Paginada con los query params page y per_page (50 por defecto). - [Crear clientes en bloque](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.bulk_create): Crea hasta 500 clientes en una llamada, cada entrada un payload de cliente completo. Con `dry_run=true` valida cada fila sin persistir y devuelve una clasificación por fila (`results[]`, incluyendo `external_id`/`tax_id` duplicado y un aviso no bloqueante de censo AEAT); con `dry_run=false` crea solo las filas válidas y reporta el resto en `failures[]`. Devuelve la forma `BulkCreateResult`. - [Elimina varios clientes de forma masiva](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.bulk_delete): Elimina hasta 200 clientes en una sola petición. Devuelve un `BulkPartialSuccessResult` con los contadores `total`, `successful` y `failed` más una lista `failures` (`id` + `error_code` + `error_message` en español); los clientes con documentos asociados se reportan en `failures`. - [Crear un cliente](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.create): Crea un nuevo cliente para tu empresa. El objeto devuelto incluye el `uuid` generado que deberías guardar para operaciones posteriores. - [Elimina un cliente](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.delete): Elimina un cliente. Devuelve 422 si el cliente está referenciado por algún documento (factura, presupuesto, etc.). - [Buscar un cliente por external ID](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.find_by_external_id): Busca un cliente por su `external_id` (enviado en el body JSON), la clave de integración que lo mapea a un registro en un sistema de terceros (ERP/CRM/e-commerce). Distinto del `tax_id` fiscal. Devuelve el cliente coincidente o 404 si ningún cliente usa ese external_id dentro de tu empresa. - [Buscar un cliente por tax ID](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.find_by_tax_id): Busca un cliente por su identificador fiscal español (NIF/CIF/NIE). Devuelve el cliente coincidente o 404 si ningún cliente usa ese tax_id dentro de tu empresa. - [Importar clientes desde un archivo](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.import): Importa clientes en masa desde un archivo CSV/XLSX como `multipart/form-data`; el procesamiento es síncrono y la respuesta lleva el resultado por fila. Sube primero con `dry_run=true` para validar sin persistir, corrige los `failures[]` reportados, y vuelve a subir con `dry_run=false` para crear solo las filas válidas. `mapping` mapea las cabeceras de tus columnas a los campos destino (`name` y `tax_id` son obligatorios). Descarga la plantilla de cabeceras desde `GET /v1/clients/import-template`. ```json { "dry_run": true, "mapping": { "Nombre": "name", "CIF": "tax_id", "Email": "email" } } ``` Límites: archivo ≤10 MB y menos de 200 filas; un archivo mayor devuelve 422 `client_import_too_large`. - [Descargar la plantilla de importación de clientes](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.import_template): Descarga la plantilla CSV (cabeceras en español + dos filas de ejemplo) para rellenarla antes de subirla a `POST /v1/clients/import`. El contenido es estático y no accede a datos de la empresa. Devuelve un stream `text/csv` como adjunto. - [Listar todos los clientes](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.list): Lista tus clientes con paginación por cursor. Admite filtrado por `is_active`, `created_at[gte|lte]` y `name[in]`. - [Busca clientes](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.search): Busca clientes por consulta de texto libre contra `name`, `tax_id`, `vat_id`, `email` y `phone`. Devuelve un array plano (sin paginación) limitado a 50 resultados. - [Obtener un cliente](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.show): Obtiene un cliente por su `uuid`. Devuelve 404 si el cliente no existe o pertenece a otra empresa. - [Obtener estadísticas del cliente](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.stats): KPIs agregados de la empresa autenticada: número total de clientes, número de activos, número con facturas de venta, número con presupuestos y totales por tipo de documento. Devuelto como `{ "data": ClientStats }`. - [Actualizar un cliente](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.update): Actualiza un cliente. Solo se modifican los campos incluidos en el payload; los campos omitidos conservan sus valores previos. - [Verificar un cliente contra el censo de la AEAT](https://docs.factuarea.com/es/api-reference/clients/public-api.v1.clients.verify_census): Comprueba el par nombre + NIF de un tercero (el destinatario de una factura) contra el censo de la AEAT (VNifV2) para anticipar rechazos VeriFactu 1239 antes de facturar. Sin estado e informativo: no se persiste nada en el cliente. Fail-open — si la AEAT no está disponible, la llamada devuelve 200 con `status: unavailable`. Las claves de prueba (`fact_test_`) devuelven estados deterministas según el NIF mágico sin contactar con la AEAT. - [Activar una empresa gestionada](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.activate): Reactiva una empresa gestionada previamente desactivada (`inactive`). La activación está condicionada por un cargo atómico por seat: en modo live el seat prorrateado se cobra de forma síncrona y la empresa solo pasa a `active` si el cargo tiene éxito. Sin método de pago registrado devuelve 402, y un plan sin el módulo de gestoría devuelve 403. Las claves de trial, enterprise y test se saltan el cargo. - [Activar varias empresas gestionadas](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.activate_batch): Reactiva varias empresas gestionadas desactivadas (`inactive`) en una operación, cobrando los seats prorrateados combinados en una única factura. Pasa `company_ids`. El gate es atómico: cada empresa se valida (propiedad y estado `inactive`) antes de cualquier cargo, así que si una es inválida se rechaza todo el lote sin cobrar ni activar ninguna. - [Crear una API key hija](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.api_keys.create): Crea una API key con scope en una de tus empresas gestionadas y devuelve su `secret` en claro exactamente una vez —guárdalo ahora, no podrá recuperarse después. Los scopes solicitados deben ser un subconjunto de los scopes de la clave que llama; solicitar un scope que la clave padre no posee devuelve 422 (sin estrechamiento silencioso). - [Listar las API keys hijas](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.api_keys.list): Lista las API keys de una de tus empresas gestionadas con paginación por cursor, incluyendo las claves revocadas para auditoría. El secret en claro nunca se devuelve. Una empresa no gestionada por tu tenant maestro devuelve 404. - [Revocar una API key hija](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.api_keys.revoke): Revoca una API key hija de inmediato e irreversiblemente, dejándola inutilizable. Las peticiones posteriores autenticadas con esa clave fallan con 401. Una empresa no gestionada por tu tenant maestro devuelve 404. - [Rotar el secreto de una API key hija](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.api_keys.rotate_secret): Invalida el secret actual de una API key hija de inmediato, genera un `prefix` + `secret` nuevos, y devuelve el nuevo secret en claro exactamente una vez. Cualquier petición hecha con el secret anterior deja de autenticar al instante. Irreversible. Una empresa no gestionada por tu tenant maestro devuelve 404. - [Recuperar una API key hija](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.api_keys.show): Recupera una sola API key de una de tus empresas gestionadas por su `id` (UUID v7). El secret en claro nunca se incluye. Una clave que no pertenece a una empresa que gestionas devuelve 404 `api_key_not_found` (anti-enumeración). - [Crear una empresa gestionada](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.create): Registra una nueva empresa gestionada (una subcuenta hija) bajo tu tenant maestro —el modelo de gestoría. `name` y `tax_id` son obligatorios, y `tax_id` debe ser único entre las empresas que gestionas (un duplicado devuelve 409). En modo live el cargo prorrateado por seat condiciona la creación: sin método de pago registrado o con un cargo fallido la llamada devuelve 402 y no se crea nada. Usa `GET /v1/companies/seat-charge-preview` para anticipar el coste; las claves de test se saltan el cargo. - [Consultar el estado de creación de una empresa gestionada](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.creation_status): Consulta el ciclo de vida de aprovisionamiento de una empresa gestionada. Devuelve `provisioning_status` (`pending`, `awaiting_payment`, `provisioning`, `active`, `failed`). `payment_setup_url` está presente solo mientras `awaiting_payment` y apunta al onboarding de método de pago del tenant maestro; `failed_reason` está presente solo cuando el aprovisionamiento ha `failed`. Las claves de test mueven la hija a `active` directamente. - [Desactivar una empresa gestionada](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.deactivate): Desactiva una empresa gestionada, moviéndola de `active` a `inactive`: pasa a ser no operativa pero sus datos se conservan y el cambio es reversible (reactívala más tarde pagando su seat). No se aplica ningún cargo; en su lugar se emite un crédito prorrateado del seat best-effort por el tiempo no usado. - [Archivar una empresa gestionada](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.delete): Archiva una empresa gestionada, moviéndola al estado `archived` para que ya no acepte operaciones. La fila de la empresa y su histórico se conservan. El archivado puede quedar bloqueado por reglas de negocio (devuelve 422 `business_rule_violation`). Una empresa no gestionada por tu tenant maestro devuelve 404. - [Listar tus empresas gestionadas](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.list): Lista las empresas gestionadas por tu tenant maestro con paginación por cursor. Por defecto solo se devuelven las empresas `active` e `inactive`; pasa `status` (`active`, `inactive`, `archived`) para filtrar —`status=archived` es la forma opt-in de mostrar las empresas archivadas. Solo se devuelven tus propias hijas. - [Previsualiza el cargo por asiento de añadir una empresa](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.seat_charge_preview): Previsualiza el importe prorrateado por seat de añadir o activar empresas gestionadas, calculado a partir de la próxima factura de Stripe del tenant maestro, sin cobrar. Usa `count` (≥1) para previsualizar un lote, o `company_ids` para una previsualización consciente de la cobertura: las empresas aún cubiertas para el periodo actual cuestan `0` (`already_covered: true`). `amount` está en las unidades menores de la moneda; `requires_payment_method` es `true` cuando no hay ningún método de pago registrado. - [Recuperar una empresa gestionada](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.show): Recupera una sola empresa gestionada por su `id` (UUID v7). Una empresa no gestionada por tu tenant maestro devuelve 404 `company_not_found` (anti-enumeración). - [Actualizar una empresa gestionada](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.update): Actualiza el perfil de una empresa gestionada (`name`, `business_name`, campos de dirección, `email`, `phone`). El `tax_id` es inmutable tras la creación (enviarlo devuelve 422) y `country_aeat_zone` se deriva de la dirección. Actualización parcial: los campos omitidos mantienen su valor; envía `""` para vaciar un campo. - [Verificar la creación de una empresa gestionada](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.companies.verify_creation): Concilia y avanza el aprovisionamiento de una empresa gestionada contra la suscripción del tenant maestro. Sin cuerpo de petición; idempotente. Mientras `awaiting_payment`, una vez el maestro tenga un método de pago registrado, la hija se cobra el seat prorrateado y pasa a `active`; en otro caso se queda en `awaiting_payment` sin error. Devuelve el recurso de estado de creación. - [Obtener el resumen consolidado de cumplimiento de plantilla](https://docs.factuarea.com/es/api-reference/companies/public-api.v1.gestoria.workforce_summary): Devuelve el panel consolidado de cumplimiento del control horario de toda tu cartera gestionada: una fila por empresa gestionada `active`, cada una proyectada desde el último cierre mensual de esa empresa sin recomputar — si el periodo actual (el último cerrable) está cerrado, su estado (`closed`/`reopened`), el último periodo cerrado (`last_closed_year`/`last_closed_month`), y los agregados `total_balance_minutes`, `total_overtime_minutes` y `employee_count`. De ámbito master: la cartera se resuelve desde tu API key, nunca desde el payload, y solo aparecen tus propias empresas hijas. A diferencia de los endpoints por empresa con `X-Active-Profile`, este agrega entre empresas hijas en una sola llamada. Se devuelve como `{ "data": [ConsolidatedWorkforce, ...] }`. - [Eliminación masiva de albaranes](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.bulk_delete): Elimina varios albaranes en una sola petición. El cuerpo toma un array `ids` de `uuid`s. Devuelve un `BulkPartialSuccessResult` con los contadores `total`, `successful`, `failed` y una lista `failures` (`id` + `error_code` + `error_message` en español) para los que no se pudieron eliminar (p. ej. firmados o facturados). Admite `Idempotency-Key` para reintentos seguros. - [Descargar en bloque los PDF de albaranes](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.bulk_pdf): Empaqueta los PDF de hasta 50 albaranes (por id) en un único ZIP. Los ids no encontrados o sin PDF generable no abortan la petición: el ZIP lleva solo los válidos y los contadores por recurso viajan en las cabeceras de respuesta `X-Bulk-*`. - [Enviar albaranes en bloque](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.bulk_send): Envía hasta 200 albaranes por email (encolado) en una sola llamada, reutilizando la ruta de envío individual por id. Devuelve un `BulkPartialSuccessResult` con los contadores `total`, `successful` y `failed` más una lista `failures` (`id` + `error_code` + `error_message` en español) por cada albarán que no se pudo enviar (no encontrado, estado no enviable o sin destinatario resoluble). - [Cambiar en bloque el estado de albaranes](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.bulk_status): Transiciona hasta 50 albaranes (por id) a un estado del conjunto cerrado `[delivered, cancelled]`, cada uno a través del guard de estado del documento. Devuelve un `BulkPartialSuccessResult`; los albaranes cuya transición se rechaza (no encontrados o no transicionables) vuelven en `failures[]`. - [Anular un albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.cancel): Transiciona un albarán al estado `cancelled`. Reemplazo REST canónico del obsoleto `POST /change_status`. Devuelve 409 `invalid_status_transition` si el albarán no se puede cancelar (p. ej. ya facturado). Admite `Idempotency-Key` para reintentos seguros. - [Convertir albarán en factura](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.convert): Convierte un albarán en una factura de venta. El albarán pasa a `invoiced` con `converted_to_id` rellenado y la nueva factura se devuelve en `data`. Solo se admite `target=invoice`. - [Crear un albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.create): Crea un nuevo albarán en estado `draft`. Los albaranes registran las mercancías enviadas a un cliente y luego pueden convertirse en facturas. - [Elimina un albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.delete): Elimina un albarán. Solo se pueden eliminar los albaranes `draft` sin número asignado; cualquier otro estado devuelve 409 `invalid_status_transition`. - [Duplicar un albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.duplicate): Crea un nuevo albarán en borrador copiando líneas, cliente y metadatos. - [Buscar un albarán por external ID](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.find_by_external_id): Busca un único albarán por su `external_id` (enviado en el body JSON), la clave de integración que lo mapea a un registro en un sistema de terceros (ERP/CRM/e-commerce). Devuelve el albarán coincidente o 404 `delivery_note_not_found` si ningún albarán usa ese external_id dentro de tu empresa. - [Listar todos los albaranes](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.list): Lista tus albaranes con paginación por cursor. - [Marca el albarán como entregado](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.mark_delivered): Transiciona un albarán al estado `delivered` (público `sent`). Reemplazo REST canónico del obsoleto `POST /change_status`. Devuelve 409 `invalid_status_transition` si el albarán no puede transicionar. Admite `Idempotency-Key` para reintentos seguros. - [Descargar el PDF del albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.pdf): Descarga la representación en PDF de un albarán. Devuelve el flujo binario del PDF (`application/pdf`). Pasa `?download=1` para `Content-Disposition: attachment` (descarga del archivo); en caso contrario se sirve `inline`. La respuesta lleva un `ETag`; reenvíalo mediante `If-None-Match` para recibir `304 Not Modified` cuando el documento no haya cambiado. - [Obtener el enlace público de un albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.public_link.get): Devuelve el estado del enlace público para compartir de un albarán: `url` (absoluta, lista para enviar al cliente), `enabled`, `expires_at` (`null` = sin límite) y `max_days` (máximo impuesto por el plan al extender el enlace). - [Actualizar el enlace público de un albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.public_link.update): Activa/desactiva el enlace público compartido de un albarán o cambia su caducidad. Devuelve 422 `expiry_exceeds_max_days` si la caducidad solicitada supera el `max_days` impuesto por el plan. Admite `Idempotency-Key` para reintentos seguros. - [Envía un albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.send): Envía un albarán al cliente por email. Usa el email registrado salvo que se sobrescriba en el payload. - [Obtener un albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.show): Obtiene un albarán por su `uuid`. - [Firmar un albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.sign): Registra una firma manuscrita en un albarán, típicamente capturada del destinatario en la entrega. La firma debe ser un PNG codificado en base64 (≤2 MB); otros formatos devuelven 422. Firmar fija `signed_at`/`signed_by` pero no cambia el estado. El log de auditoría de firmas retiene PII del destinatario hasheada durante 5 años (LSSI-CE española); usa el endpoint `signature-audits/{auditId}/forget` para atender una solicitud de supresión RGPD. - [Olvidar la PII de la firma del albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.signature_audits.forget): RGPD Art. 17 (derecho de supresión) — elimina los datos personales (nombre/DNI del destinatario) de una entrada del log de auditoría de firmas conservando la traza de auditoría no-PII exigida para el cumplimiento LSSI-CE. El `{auditId}` es la clave primaria numérica del registro de auditoría de firma. - [Recupera las estadísticas de albaranes](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.stats): Devuelve KPIs agregados de tus albaranes: total de documentos, importe acumulado, desglose por estado, número pendiente de firma y número convertido a factura este mes. - [Listar estados de albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.statuses): Lista el catálogo cerrado de estados de albarán (`draft`, `delivered`, `invoiced`, `cancelled`) con sus etiquetas públicas y colores. Úsalo para poblar filtros o selectores de estado en lugar de codificar valores a mano. El campo `data` de la respuesta es un array de elementos `{ value, label, color }`. - [Actualizar un albarán](https://docs.factuarea.com/es/api-reference/delivery-notes/public-api.v1.delivery_notes.update): Actualiza un albarán en borrador. Una vez firmado o facturado, el albarán se vuelve inmutable. - [Lista el registro de peticiones de tu API](https://docs.factuarea.com/es/api-reference/developers/public-api.v1.developers.request_logs.list): Inspecciona las peticiones que tu propia integración ha hecho contra esta API, de más reciente a más antigua, para depurarla sin abrir un ticket de soporte: qué llamaste, qué te devolvió, cuánto tardó y, cuando una llamada falló, el error que devolvió. Acotado a la empresa autenticada. Las filas se purgan a los 30 días, así que esto es una ventana de depuración, no un rastro de auditoría. - [Consulta un registro de petición de la API](https://docs.factuarea.com/es/api-reference/developers/public-api.v1.developers.request_logs.show): Consulta una única petición de tu propia integración por el `request_id` que la API devolvió en el header `X-Request-Id` de esa respuesta — el identificador que ya tienes a mano cuando una llamada se portó mal, y el que hay que citar en una petición de soporte. Es una cadena opaca `req_…`, no un UUID v7. El cuerpo lleva los mismos campos que el listado. - [Resume la entrega de email por documento](https://docs.factuarea.com/es/api-reference/emails/public-api.v1.emails.indicators): Responde a «¿salió el email de estos documentos?» para un lote entero de una vez, en lugar de paginar los envíos de cada uno: por documento, cuántos emails se enviaron, el último estado, la última entrega al servidor SMTP y cuántos fallaron. Ideal para pintar una columna «enviado / no enviado» sobre una página de facturas en una sola llamada. IMPORTANTE — `last_status` y `last_sent_at` describen la entrega al SERVIDOR SMTP DE SALIDA, no la entrega real: un email `sent` puede rebotar después sin que la plataforma se entere. - [Lista los emails enviados](https://docs.factuarea.com/es/api-reference/emails/public-api.v1.emails.list): Consulta los emails que tu empresa ha enviado por la plataforma — facturas, presupuestos, facturas proforma, albaranes, recordatorios de cobro —, de más reciente a más antiguo, para poder responder a «¿salió de verdad el email de esta factura?» sin preguntárselo a tu cliente. Acotado a la empresa autenticada. IMPORTANTE — `status` describe la entrega al SERVIDOR SMTP DE SALIDA, no la entrega real: `sent` significa que el servidor de correo saliente aceptó el mensaje, no que el destinatario lo recibiera. - [Consulta un email enviado](https://docs.factuarea.com/es/api-reference/emails/public-api.v1.emails.show): Consulta un email por su id, típicamente después de encontrarlo en el listado, para investigar qué le pasó: destinatario, asunto, estado, intentos, el mensaje de error cuando falló y el documento para el que se envió. Acotado a la empresa autenticada. IMPORTANTE — `status` describe la entrega al SERVIDOR SMTP DE SALIDA, no la entrega real: `sent` significa que el servidor de correo saliente aceptó el mensaje, no que el destinatario lo recibiera. - [Cancelar una invitación de empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employee-invitations.cancel): Cancela una invitación de empleado pendiente identificada por su `id` (UUID v7); pasa a `canceled` y ya no puede aceptarse. Devuelve 204 si tiene éxito, 422 si la invitación ya se había aceptado y 404 si no existe en tu empresa. - [Listar las invitaciones de empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employee-invitations.list): Lista las invitaciones de empleado de tu empresa. Solo se devuelven las invitaciones con rol `employee`; se excluyen las invitaciones de usuario/admin de la superficie de gestión de usuarios. Cada elemento expone su `id` opaco (UUID v7), `email`, `status` (`pending`/`accepted`/`canceled`/`expired`) y caducidad. - [Reenviar una invitación de empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employee-invitations.resend): Reenvía una invitación de empleado pendiente identificada por su `id` (UUID v7), regenerando su token y caducidad y reenviando el email de invitación. Devuelve 422 si la invitación ya se había aceptado o cancelado, y 404 si no existe en tu empresa. - [Enviar una invitación de empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employee-invitations.send): Invita a una persona a unirse a tu empresa como empleado (portal de Control Horario). Solo `email` es obligatorio — el rol `employee` lo fija el servidor, nunca se toma del payload. La persona invitada recibe un email con un enlace de aceptación. Invitar un email que ya pertenece a un usuario de la empresa, o que ya tiene una invitación pendiente, devuelve 422. Las invitaciones de empleado no consumen el límite de asientos `users` del plan. - [Cancelar el add-on de asientos de empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employee-seats.cancel): Cancela el add-on de facturación por empleado: la suscripción `employee-seats` se cancela al final del periodo (el mes actual ya está pagado) y la cobertura por empleado se purga. La suscripción del plan nunca se toca. Devuelve el estado de facturación resultante, donde `subscribed` sigue siendo `true` hasta que termina el periodo. - [Sincronizar la cantidad de asientos de empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employee-seats.change-quantity): Reconcilia la cantidad de asientos del add-on con el número real de empleados activos (SET con `proration_behavior: none`, sin factura). Idempotente: cuando la cantidad ya coincide es un no-op. Devuelve el estado de facturación resultante. - [Previsualizar el cargo del asiento de empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employee-seats.preview): Previsualiza el importe prorrateado por asiento para activar o contratar empleados, computado desde la próxima factura de Stripe de la suscripción `employee-seats`, sin cobrar. Usa `count` (≥1, hasta 1000) para una vista previa en bloque, o `employee_ids` (UUID v7) para una vista previa consciente de cobertura: los empleados aún cubiertos en el periodo actual cuestan 0 (`already_covered: true`). `amount` es la base imponible en céntimos; `requires_payment_method` es `true` cuando no hay método de pago registrado. Nunca lanza — degrada a una vista previa neutra. - [Obtener el estado de facturación de asientos de empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employee-seats.status): Devuelve el estado de facturación del add-on por empleado de tu empresa: si la suscripción `employee-seats` está activa, cuántos asientos se facturan (`quantity`), cuántos empleados están activos, y el coste recurrente por asiento con IVA. Los importes están en unidades menores de la moneda (céntimos) y son `null` cuando el coste no es resoluble (sin suscripción, sin plan activo, enterprise fuera de Stripe, sandbox) — nunca un 0 engañoso. `seats_billable` indica si tu plan DEBE estar pagando por asiento, con independencia de `subscribed`: `subscribed: false` con `seats_billable: true` y empleados activos es una anomalía de facturación, mientras que `seats_billable: false` es un estado legítimo sin cargo (enterprise por contrato, trial o sandbox). Los empleados nunca cuentan para el límite de asientos `users` del plan. - [Suscribirse al add-on de asientos de empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employee-seats.subscribe): Suscríbete al add-on de facturación por empleado: crea la suscripción mensual dedicada `employee-seats` con `quantity` fijado al número de empleados activos, cobrando el primer periodo con el método de pago registrado. El cobro es atómico — sin método de pago devuelve 402 `employee_seat_payment_method_required` (el envoltorio lleva `error.details.payment_setup_url`), y un cobro rechazado devuelve 402 `employee_seat_charge_failed`; en ambos casos no se suscribe nada. Devuelve el estado de facturación resultante. - [Crear un empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employees.create): Registra un nuevo empleado para la empresa autenticada (resuelta desde la API key, nunca desde el payload). `first_name`, `last_name`, `email`, `employment_type` (`full_time`/`part_time`), `contract_hours`, `hire_date` y `ccaa` son obligatorios; `tax_id` y `job_title` son opcionales. Devuelve el empleado creado con su `id` generado (UUID v7). Los empleados activos cuentan para la facturación por asientos del módulo de plantilla. - [Desactivar un empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employees.deactivate): Desactiva un empleado (transición `active` → `inactive`), retirándolo suavemente de la plantilla activa pero conservando su registro. `termination_date` (`Y-m-d`) es opcional — omítela para usar la fecha de hoy. Devuelve 422 si el empleado ya está inactivo o la fecha de baja es anterior a la fecha de alta. Reversible mediante reactivar. - [Buscar un empleado por external ID](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employees.find_by_external_id): Busca un empleado por su `external_id` (enviado en el body JSON), la clave de integración que lo mapea a un registro en un sistema de terceros (ERP/CRM/HR). Distinto del `tax_id` fiscal. Devuelve el empleado coincidente o 404 si ningún empleado usa ese external_id dentro de tu empresa. - [Listar todos los empleados](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employees.list): Lista los empleados de tu empresa con paginación por cursor. Admite filtrar por `status` (`active`/`inactive`), `employment_type` (`full_time`/`part_time`) y `ccaa`, más una `search` de texto libre sobre nombre y email. - [Reactivar un empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employees.reactivate): Reactiva un empleado (transición `inactive` → `active`), limpiando su `termination_date` y devolviéndolo a la plantilla activa. Sin cuerpo de la petición. Devuelve 422 si el empleado ya está activo. - [Obtener un empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employees.show): Obtén un único empleado por su `id` (UUID v7). Un empleado perteneciente a otra empresa devuelve 404 `employee_not_found` (anti-enumeración). - [Obtener las estadísticas de empleados](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employees.stats): KPIs agregados de tu plantilla: número total de empleados, número de activos e inactivos y un desglose por tipo de jornada (`full_time`/`part_time`). Los empleados desactivados cuentan en `total`/`inactive` pero no como asientos activos. Se devuelve como `{ "data": EmployeeStats }`. - [Actualizar un empleado](https://docs.factuarea.com/es/api-reference/employees/public-api.v1.employees.update): Actualiza un empleado. Actualización parcial: solo se modifican los campos presentes en el payload; los omitidos conservan su valor. `hire_date` es inmutable. Devuelve el empleado actualizado. - [Listar tipos de evento](https://docs.factuarea.com/es/api-reference/events/public-api.v1.event_catalog.list): Lista el catálogo cerrado de tipos de evento que Factuarea puede emitir a los webhooks. Cada entrada expone su `name`, `category`, una descripción y un `status`: los tipos `available` se emiten hoy y son suscribibles vía `enabled_events`; los tipos `coming_soon` están reservados para una versión futura y aún no son suscribibles (pasar uno en `enabled_events` devuelve 422). - [Listar todos los eventos](https://docs.factuarea.com/es/api-reference/events/public-api.v1.events.list): Lista los eventos de tu registro de eventos con paginación por cursor. Cada evento registra algo que ocurrió en tu cuenta (se pagó una factura, se aceptó un presupuesto, …) y es el mismo objeto que se entrega a tus webhook endpoints. Admite filtrado por `type[in]` y `created[gte|lte]`. - [Obtener un evento](https://docs.factuarea.com/es/api-reference/events/public-api.v1.events.show): Obtiene un único evento por su `id` (formato `evt_`, un identificador opaco). Útil para auditar y reenviar payloads de webhook. Devuelve `404 not_found` si el evento no existe o pertenece a otra empresa. - [Solicitar la anulación de un envío a FACe](https://docs.factuarea.com/es/api-reference/facturae/public-api.v1.face_submissions.cancel): Solicita la anulación (4200) de un envío a FACe con un `reason` obligatorio. Solo se permite mientras el envío está en un estado anulable (`submitted`, `registered_rcf`, `accounted`); en caso contrario devuelve 422 `face_submission_not_cancellable`. El envío pasa a `cancellation_requested` hasta que FACe confirma. - [Obtener un envío a FACe](https://docs.factuarea.com/es/api-reference/facturae/public-api.v1.face_submissions.show): Obtiene un envío a FACe por su `id` (UUID). El campo `status` refleja el último estado de tramitación conocido en FACe (`submitted`, `registered_rcf`, `accounted`, `paid`, `rejected`, `cancellation_requested`, `cancelled`, `error`) — el sistema consulta FACe periódicamente, así que un GET normal es la forma de seguir el progreso (no hay endpoint de refresco en v1). - [Listar los envíos a FACe de la factura](https://docs.factuarea.com/es/api-reference/facturae/public-api.v1.invoices.face_submissions.list): Lista el histórico de envíos a FACe de una factura (array plano, incluye el más reciente). Devuelve `data: []` cuando la factura nunca se ha enviado. - [Enviar la factura a FACe](https://docs.factuarea.com/es/api-reference/facturae/public-api.v1.invoices.face_submissions.submit): Presenta una factura emitida a FACe (el punto de entrada B2G español). Requiere los tres códigos DIR3 del cliente y un certificado de firma activo; el XML FacturaE 3.2.2 se firma XAdES-EPES y se presenta a FACe, devolviendo el número de registro. Sin cuerpo de petición —los códigos DIR3 se leen del cliente. Las claves de test simulan la presentación sin contactar con FACe. - [Descargar el XML de FacturaE](https://docs.factuarea.com/es/api-reference/facturae/public-api.v1.invoices.facturae): Devuelve en streaming el XML FacturaE 3.2.2 de la factura (cumplimiento B2G), conforme a XSD con el desglose de impuestos completo. Con un certificado de firma activo el cuerpo se firma XAdES-EPES y se sirve como `.xsig`; sin él se devuelve sin firmar como `.xml`. La cabecera `X-Facturae-Signed` distingue ambos. Las facturas en borrador devuelven 422. - [Listar todos los festivos](https://docs.factuarea.com/es/api-reference/holidays/public-api.v1.holidays.list): Lista los festivos visibles para tu empresa con paginación por cursor: festivos de referencia globales (nacionales y por comunidad autónoma, precargados y de solo lectura) más tus festivos locales personalizados. Admite filtrar por `year`, `ccaa` (comunidad autónoma ISO 3166-2:ES), `scope` (`national`/`autonomic`/`local`) y `source` (`reference` para filas precargadas, `custom` para las propias). - [Resolver los festivos aplicables](https://docs.factuarea.com/es/api-reference/holidays/public-api.v1.holidays.resolve): Resuelve los festivos que aplican a una comunidad autónoma dada en un año dado: los festivos nacionales, los festivos autonómicos de esa `ccaa` y tus festivos locales personalizados, fusionados en una única lista plana bajo `{ "data": [Holiday, …] }`. Tanto `ccaa` (ISO 3166-2:ES) como `year` son obligatorios; un código de comunidad inválido o un año fuera de rango devuelve 422. - [Obtener un festivo](https://docs.factuarea.com/es/api-reference/holidays/public-api.v1.holidays.show): Obtén un único festivo por su `id` (UUID v7). Un festivo personalizado perteneciente a otra empresa devuelve 404 `holiday_not_found` (anti-enumeración). - [Lista los eventos de integración](https://docs.factuarea.com/es/api-reference/integration-events/public-api.v1.integrations.events.list): Consulta todo lo que las pasarelas de pago le han enviado a Factuarea. Esta es la bandeja que hay que abrir cuando un cobro no generó su factura: cada evento descartado lleva un `discard_reason` tipado y si se puede reprocesar. De más reciente a más antiguo, y acotado a la empresa autenticada. El contenido crudo del evento no se devuelve nunca. - [Reprocesa un evento de integración aparcado](https://docs.factuarea.com/es/api-reference/integration-events/public-api.v1.integrations.events.replay): Reprocesa un evento de pasarela que se aparcó, una vez desaparecida la causa que le impidió producir su efecto. **Antes de llamarlo** - El evento debe estar publicado con `is_replayable` a `true`; cualquier otro devuelve 422. - Resuelve antes la causa: vuelve a activar la facturación automática, vuelve a vincular la cuenta conectada, espera al tipo de cambio. - Exige el scope de escritura `integration_events:write`, nunca el scope de lectura de la bandeja. **Qué puede provocar** > **Esta acción puede tener consecuencias fiscales reales.** Si la causa ya está resuelta, el reproceso PUEDE EMITIR UNA FACTURA REAL, con su número de serie y su registro en VeriFactu. Confírmalo con el titular de la cuenta antes de llamarlo. **Qué devuelve** - Un `202` significa aceptado y encolado, **no** completado. - El cuerpo devuelve el evento tal y como está ahora, no el resultado del reintento. - El resultado aparece como un evento NUEVO en la bandeja: consulta `GET /v1/integrations/events` para ver cómo acabó. - Nunca duplica facturas: el reproceso pasa por la misma comprobación de idempotencia que el intento original. - [Consulta un evento de integración](https://docs.factuarea.com/es/api-reference/integration-events/public-api.v1.integrations.events.show): Consulta un evento de integración por su id, típicamente después de encontrarlo en el listado, para saber exactamente por qué un cobro no produjo su factura y qué hacer a continuación. Además de los campos del listado, el detalle añade `recommended_action`, una frase imperativa con el siguiente paso, y `is_replayable`, que te dice si la operación de reproceso aceptaría el evento. - [Listar la actividad de la factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.activities): Devuelve la línea de tiempo de actividad paginada por cursor (log de auditoría) de una sola factura: transiciones de estado, emails, recordatorios y cambios de metadatos. - [Anular una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.annul): Retira una factura emitida **con un motivo documentado**. Aquí `reason` es obligatorio (3–500 caracteres); esa es la única diferencia con `POST /v1/invoices/{id}/void`, que hace exactamente la misma operación y persiste un texto de relleno cuando lo omites. Prefiere este endpoint siempre que el motivo tenga que ser trazable: el texto que envías se conserva en el rastro de auditoría de la factura y, cuando la empresa está acogida a VeriFactu, pasa a ser el `motivo` del registro de anulación ante la AEAT. La factura pasa a `annulled` y `voided_at` empieza a informar de cuándo ocurrió. El estado es terminal y la operación es **irreversible**: no hay vuelta a `sent` ni a `draft`, y el número correlativo de la serie ni se libera ni se reutiliza. **Efecto en la AEAT.** Con VeriFactu activo, anular encola un registro de *anulación* a la AEAT de forma **asíncrona**: un `200` significa que la factura está anulada en Factuarea, no que la AEAT ya lo haya procesado — consulta la factura para ver su estado VeriFactu. El registro de *alta* original no se borra ni se reescribe; la AEAT conserva ambos apuntes, la emisión y su anulación. Con VeriFactu inactivo la anulación es puramente interna y no se transmite nada. **¿Anular o rectificar?** La anulación retira el documento entero y solo funciona antes del cobro; no produce ningún documento rectificativo, así que nunca reexpresa un importe. Una rectificativa (`POST /v1/invoices/{id}/corrective`) crea una **nueva** factura que corrige a la original y es el único camino para una factura que ya está `paid` o que solo está mal en parte. Límites: solo se puede anular una factura en `sent` u `overdue`. Un `draft` no se anula, se borra; `paid`, `cancelled` y `annulled` devuelven 422. Una factura que **es** rectificativa no se puede anular nunca — emite en su lugar una nueva rectificativa de la original. Usa `GET /v1/invoices/{id}/can-annul` para comprobar la elegibilidad, y si se creará un registro de anulación VeriFactu, antes de llamar aquí. - [Asignar un número de factura real](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.assign_real_number): Promueve un borrador a factura definitiva asignándole su número de serie real. En empresas con VeriFactu habilitado esto ocurre automáticamente al enviar. - [Crear facturas en bloque](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.bulk_create): Crea hasta 100 facturas en una llamada, cada entrada un payload de factura completo. Con `dry_run=true` valida cada fila sin persistir y devuelve una clasificación por fila (`results[]`, incluyendo `external_id` duplicado y un aviso no bloqueante de censo AEAT); con `dry_run=false` crea solo las filas válidas y reporta el resto en `failures[]`. Devuelve la forma `BulkCreateResult`. - [Eliminación masiva de facturas](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.bulk_delete): Elimina varias facturas en una llamada con éxito parcial: cada id se evalúa de forma independiente y un fallo nunca aborta el lote. Solo se eliminan facturas en borrador; una factura emitida vuelve como fallo `resource_not_deletable` (usa `void` en su lugar). Devuelve un `BulkPartialSuccessResult` con `total`, `successful`, `failed` y una lista `failures` por id. ```json { "ids": ["0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f60", "0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f61"] } ``` Límites: `ids` acepta de 1 a 100 entradas UUID v7 por llamada. - [Descargar en bloque los PDF de facturas](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.bulk_pdf): Empaqueta los PDF de hasta 50 facturas (por id) en un único ZIP. Los ids no encontrados o sin PDF generable no abortan la petición: el ZIP lleva solo los válidos y los contadores por recurso viajan en las cabeceras de respuesta `X-Bulk-*`. - [Enviar facturas en bloque](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.bulk_send): Envía hasta 200 facturas por email (encolado) en una sola llamada, reutilizando la ruta de envío individual por id. Devuelve un `BulkPartialSuccessResult` con los contadores `total`, `successful` y `failed` más una lista `failures` (`id` + `error_code` + `error_message` en español) por cada factura que no se pudo enviar (no encontrada, estado terminal o sin destinatario resoluble). - [Cambiar en bloque el estado de facturas](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.bulk_status): Transiciona varias facturas a un nuevo estado en una llamada, cada una a través del mismo guard del Aggregate, con éxito parcial (un id rechazado nunca aborta el lote). `new_status` es `sent` o `paid`; cuando es `paid`, `payment_date` es obligatorio y se propaga como la fecha de pago real de cada factura (nunca `now()`). Devuelve un `BulkPartialSuccessResult` con `total`, `successful`, `failed` y una lista `failures` por id (`resource_not_found` o `invalid_status_transition`). ```json { "ids": ["0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f60"], "new_status": "paid", "payment_date": "2026-06-30" } ``` Límites: `ids` acepta de 1 a 50 entradas; `payment_date` es obligatorio cuando `new_status` es `paid` y no puede estar en el futuro. - [Comprobar elegibilidad para anulación](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.can_annul): Valida si la factura puede anularse y si se creará un registro de anulación de VeriFactu. Llámalo antes de hacer POST a /annul. - [Generar factura rectificativa](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.corrective): Emite una factura rectificativa (RD 1619/2012 art. 15) que corrige a una factura ya emitida. Devuelve `201` con la **nueva** factura: `is_corrective: true`, `corrective` apuntando a la original y un número derivado del de esta en la misma serie (`F-2026-0042-REC1`, `-REC2`… para rectificativas sucesivas). Flujo: la original debe estar ya emitida (`sent` o `paid`) → la rectificativa nace **ya emitida**, nunca como borrador → cuando VeriFactu está activo su *alta* se transmite a la AEAT de forma **asíncrona**, así que un `201` no significa que la AEAT ya la haya aceptado. La original no se modifica nunca: conserva su número, su estado y su propio registro VeriFactu. Una rectificativa es un documento adicional, no una edición. **Total o parcial.** `correction_type: full` es una sustitución (naturaleza VeriFactu `S`): las `lines` que envías son los *importes finales correctos*, y omitir `lines` por completo la convierte en una anulación total, donde cada línea original se copia negada y con el prefijo `[ANULACION]`. `correction_type: partial` es una rectificación por diferencias (naturaleza `I`): `lines` es obligatorio y cada una es un delta — típicamente negativo — con el prefijo `[AJUSTE]`. En una rectificación parcial una línea solo mueve stock si declara su propio `product_id`; en una sustitución el producto se hereda de la línea original del mismo índice. **Código R de la AEAT.** Por defecto se deriva de `correction_reason`: `error_fundado` → R1, `concurso` → R2, `incobrable` → R3, el resto → R4; una rectificativa de una factura simplificada (F2) nace siempre R5 sea cual sea el motivo. `correction_code` sobrescribe esa derivación, pero se valida contra la matriz legal — original F2 → solo `R5`; original F1/F3 → solo `R1`–`R4`. Cualquier otra combinación devuelve 422 con los `allowed_values` legales. Límites: las originales en `draft`, `overdue`, `cancelled` y `annulled` devuelven 422 (una factura `overdue` hay que cobrarla o anularla antes); una rectificativa no se puede rectificar a su vez — emite en su lugar una nueva rectificativa de la original. Lista todas las rectificativas de una factura con `GET /v1/invoices/{id}/correctives`. - [Listar facturas rectificativas](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.correctives): Devuelve todas las facturas rectificativas asociadas a la factura original. Se usa para reconstruir el árbol original → rectificativa. - [Crea una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.create): Crea una factura de venta. Se crea en `draft` por defecto; pasa `options.issue_directly: true` para emitirla de inmediato (asignando el número correlativo y congelando el documento según AEAT), o emítela más tarde. El *alta* VeriFactu se transmite a AEAT de forma asíncrona: un `201` no significa que AEAT haya aceptado aún la factura, así que consúltala para el estado AEAT. ```json { "client_id": "0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f60", "lines": [{ "description": "Consulting", "quantity": 1, "unit_price": 1000, "tax_rate": 21 }], "options": { "issue_directly": true } } ``` Límites: se requiere al menos una línea; envía una `Idempotency-Key` (≤255 caracteres, recordada 24 h) para reintentos seguros; un `external_id` duplicado hace upsert de la factura existente en lugar de crear una nueva. - [Crear una factura recurrente a partir de una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.create_recurring): Crea una plantilla de factura recurrente que reutiliza las líneas, el cliente y la serie de una factura existente, aplicando la cadencia (frecuencia, fecha de inicio, fecha de fin opcional y límites) aportada en el cuerpo. Devuelve la nueva factura recurrente. - [Elimina una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.delete): Elimina una factura en borrador. Las facturas emitidas no se pueden eliminar (usa `void` en su lugar). - [Duplicar una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.duplicate): Crea una nueva factura en borrador copiando las líneas, el cliente y los metadatos de una factura existente. La nueva factura obtiene un `uuid` y un número nuevos. - [Exportar facturas a una hoja de cálculo](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.export_excel): Exporta una selección de facturas a una hoja de cálculo (`xlsx` o `csv`) y la devuelve como adjunto en streaming. Acótala con los filtros (`invoice_ids[]`, `client_id`, `series_id`, `status`, `date_from`, `date_to`, `search`) u omítelos para exportar todo. `format` elige la disposición: `SUMMARY` (una fila por factura) o `ITEMS` (una fila por línea). ```http GET /v1/invoices/export?format=SUMMARY&status=paid&date_from=2026-01-01&date_to=2026-03-31 ``` Límites: la selección está limitada a 5.000 facturas; una más amplia devuelve 422 `export_limit_exceeded`. - [Buscar una factura por external ID](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.find_by_external_id): Busca una única factura por su `external_id` (enviado en el body JSON), la clave de integración que la mapea a un registro en un sistema de terceros (ERP/CRM/e-commerce). Distinto del número fiscal y del `uuid`. Devuelve la factura coincidente o 404 `invoice_not_found` si ninguna factura usa ese external_id dentro de tu empresa. - [Buscar una factura por número](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.find_by_number): Busca una única factura por su número, con un `year` opcional para desambiguar entre ejercicios fiscales. Devuelve 404 si no se encuentra y 422 si el número es ambiguo y no se proporciona `year`. - [Listar todas las facturas](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.list): Lista tus facturas de venta con paginación por cursor. Admite filtrado por `status[in]`, `client_id`, `series_id`, `issued_on[gte|lte]` y `total[gte|lte]`. - [Marca la factura como pagada](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.mark_paid): Marca una factura como totalmente pagada. Idempotente: si ya está pagada, devuelve la factura sin cambios. Devuelve 422 si la factura está en un estado que no puede transicionar a `paid`. - [Marca una factura como enviada](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.mark_sent): Transiciona una factura en borrador a `sent` sin enviar email. Útil cuando el documento se entregó por un canal externo. - [Descargar el PDF del recibo de pago](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.payment_receipt): Transmite el PDF del justificante de una factura pagada. Devuelve 422 si la factura no está en estado `paid`. - [Registrar un pago](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.payments_create): Registra un pago parcial (o total) contra una factura. La factura transiciona a `partially_paid` mientras el importe pagado acumulado está por debajo del total, y a `paid` una vez lo alcanza. Devuelve 422 si la factura está en un estado que no admite pagos. - [Listar pagos de factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.payments_list): Lista los pagos registrados contra una factura, ordenados por fecha de pago. Devuelve un array vacío cuando aún no se ha registrado ningún pago. - [Descargar el PDF de la factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.pdf): Descarga la representación en PDF de una factura. Devuelve el flujo binario del PDF (`application/pdf`). - [Generar enlace temporal a PDF](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.pdf_link): Devuelve una URL temporal al PDF de la factura en lugar de transmitir los bytes. Cómodo para incrustar en emails o apps de mensajería. Contrato dual: 200 con la URL cuando el PDF ya está materializado; 202 con `status: pendiente` cuando la generación se ha encolado (el PDF se renderiza en la cola `pdf`) — reintenta hasta obtener el 200. - [Previsualizar el PDF de un borrador de factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.pdf_preview): Devuelve en streaming un PDF borrador no fiscal (`application/pdf`) de una factura marcada como BORRADOR, con un número de marcador de posición y sin QR de VeriFactu. No se persiste nada: el contador de la serie y la huella permanecen intactos. Devuelve 422 para una factura ya emitida — usa el endpoint `pdf` estándar en su lugar. - [Recupera el enlace público de la factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.public_link_get): Devuelve la URL pública para compartir de la factura (/d/{uuid}) junto con su estado, expiración y los días máximos de extensión permitidos por el plan. - [Actualizar el enlace público de una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.public_link_update): Aplica una acción al enlace público: `revoke`, `activate`, `extend` (con `extend_days`) o `reset` al valor por defecto del plan. - [Lista los trimestres con facturas](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.quarterly.available): Devuelve los trimestres que tienen al menos una factura, con desglose por tipo de factura (F1/F2/F3/R5). Útil para poblar selectores de "trimestre a exportar". - [Generar archivo ZIP trimestral](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.quarterly.download_zip): Construye un ZIP con todos los PDFs de facturas del trimestre indicado. Devuelve metadatos del ZIP (ruta, recuentos procesados, errores). - [Enviar por email el ZIP trimestral al asesor](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.quarterly.send_email): Genera el ZIP trimestral y lo envía por email al destinatario, normalmente el asesor fiscal. - [Vista previa de un email de recordatorio de pago](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.reminder_preview): Renderiza el HTML, el asunto y los destinatarios resueltos del email de recordatorio sin enviarlo. Mismos campos de override que send-reminder. - [Reprogramar una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.reschedule): Mueve la fecha de emisión de una factura ya programada. La factura **sigue en `scheduled` todo el tiempo** — a diferencia de `unschedule` seguido de `schedule`, no vuelve nunca a `draft`, así que en ningún momento intermedio es editable ni borrable, y no hay ventana en la que el barrido pudiera encontrarla sin programar. **Qué puedes cambiar:** `scheduled_for`, y solo eso. `scheduled_action` se conserva — una programación creada como `issue_and_send` sigue enviando el email al cliente en la fecha nueva, y una creada como `draft` sigue sin hacerlo. Para cambiar la acción tienes que hacer `unschedule` y volver a programar. Esta llamada no toca el contenido de la factura (líneas, cliente, serie, totales): para eso usa `PATCH /v1/invoices/{id}` mientras siga siendo un borrador. Límites: solo se puede reprogramar una factura en `scheduled` — un `draft` (nunca programado) o una factura ya emitida devuelven 422 — y el nuevo `scheduled_for` tiene que estar estrictamente en el futuro (422 si no). Todo lo documentado en `schedule` sobre qué ocurre cuando llega la fecha (número asignado en ese momento, snapshots congelados, *alta* asíncrona en VeriFactu, email solo con `issue_and_send`, reintento por factura si falla) se aplica igual a la fecha nueva. - [Programar una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.schedule): Reserva la emisión de una factura borrador para un instante futuro. La factura pasa a `scheduled` y **todavía no ocurre nada fiscal**: conserva su número de relleno `BORRADOR`, no consume ningún contador de serie y no se registra nada en VeriFactu. Programar no quema numeración nunca. **Qué ocurre en `scheduled_for`.** Un barrido se ejecuta cada minuto y, en la primera pasada a partir de ese instante: (1) asigna el número correlativo definitivo de la serie **en ese momento**, no cuando programaste — así que un documento programado hoy y emitido el mes que viene toma el número que corresponde al mes que viene; (2) congela los snapshots de destinatario y emisor a ese instante, que es lo que mostrarán el PDF y el XML fiscal; (3) pasa la factura a `sent`; (4) encola el *alta* en VeriFactu ante la AEAT de forma **asíncrona** cuando la empresa está acogida; y (5) envía el email al cliente **solo** cuando `scheduled_action` es `issue_and_send` y el cliente tiene email registrado — con `scheduled_action: draft` la factura se emite pero no se entrega nunca, y `issue_and_send` sin email de destinatario la emite igualmente, omitiendo la entrega en silencio. **Zona horaria.** `scheduled_for` es una fecha-hora ISO 8601. Si lleva un desfase explícito (`2027-01-15T09:00:00Z`, `…+01:00`) se respeta ese desfase; sin él se interpreta en la zona horaria de servidor de la cuenta, `Europe/Madrid`. La resolución es de minuto: espera la emisión dentro del minuto siguiente al instante que pediste, nunca antes. **Si la emisión programada falla**, cada factura se aísla en su propia transacción: la que falla se queda en `scheduled` con su fecha en el pasado, el error se registra, el resto del lote no se ve afectado y el siguiente barrido la reintenta. Una emisión correcta no se repite nunca, porque `scheduled → sent` solo puede ocurrir una vez. Límites: solo se puede programar un `draft` (cualquier otro estado devuelve 422) y `scheduled_for` tiene que estar estrictamente en el futuro (422 si no). Mientras siga en `scheduled` puedes llamar a `unschedule` para devolverla a `draft`, o a `reschedule` para mover solo la fecha. - [Envía la factura por email](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.send): Envía una factura al cliente por email. Usa el email registrado salvo que se sobrescriba en el payload. - [Envía un recordatorio de pago](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.send_reminder): Envía por email un recordatorio de pago al cliente para esta factura. Acepta valores opcionales `email`, `subject`, `message`, `cc`, `bcc` para sobrescribir. - [Recupera una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.show): Obtiene una factura de venta por su `uuid`. - [Comprobar elegibilidad de factura simplificada](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.simplified_eligibility): Determina si una factura puede emitirse como simplificada (F2) según el Real Decreto 1619/2012 art. 4 en función del importe y los datos de la contraparte. - [Obtener estadísticas de facturas](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.stats): Devuelve KPIs agregados de la empresa: recuentos por estado, ingresos, totales pendientes y vencidos, días medios hasta el pago y recuentos de rectificativas. Filtrable por periodo (por defecto el año actual). - [Listar estados de factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.statuses): Lista el catálogo cerrado de estados de factura con su `value` público, su `label` localizada y su `color` de UI. Úsalo para poblar filtros o selectores de estado en lugar de codificar valores a mano. - [Sustituir facturas simplificadas por factura completa](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.substitute_simplified): Agrupa N facturas simplificadas (F2) bajo una única factura completa sustitutiva (F3) con los datos completos del receptor. Marca las originales como sustituidas. - [Desprogramar una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.unschedule): Cancela una emisión programada. La factura vuelve a `draft`, `scheduled_for` y `scheduled_action` se ponen de nuevo a `null`, y vuelve a ser editable y borrable como cualquier otro borrador. Desprogramar no deja **ningún rastro fiscal**, porque todavía no había ocurrido nada fiscal: no se consumió ningún número correlativo de la serie (la factura conserva su número de relleno `BORRADOR`), no se registró nada en VeriFactu y no se envió ningún email. Esto no es una anulación y no aparece en ningún registro de la AEAT. **Ventana de uso.** Solo se aplica mientras la factura está en `scheduled`. Un `draft` que nunca se programó devuelve 422, y una factura que el barrido ya ha emitido, también: desde ese instante está en `sent`, tiene número definitivo y — donde aplique VeriFactu — un registro ante la AEAT, así que la vuelta atrás ya no es `unschedule` sino `void`/`annul` para retirarla (solo mientras esté sin cobrar) o `corrective` para rectificarla. En la práctica la carrera es real: una factura cuyo `scheduled_for` acaba de pasar puede haberse emitido ya cuando llegue tu llamada. Si solo quieres mover la fecha, usa `PATCH /v1/invoices/{id}/reschedule` en su lugar — evita el viaje de ida y vuelta por `draft` y la ventana en la que el documento es editable. - [Anular el envío de una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.unsend): Limpia la marca de envío (`sent_at`) de una factura `sent` manteniendo su estado `sent`. El número correlativo y el registro VeriFactu quedan intactos: la factura no se revierte a borrador y sigue siendo inmutable según AEAT. Úsalo para deshacer un marcado-como-enviada accidental. Idempotente: no hace nada cuando `sent_at` ya es null. - [Actualizar una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.update): Actualiza una factura en borrador. Una vez emitida una factura (estado `issued`), la mayoría de los campos se vuelven inmutables por cumplimiento de la AEAT. - [Anular una factura](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.invoices.void): Retira una factura emitida. La factura pasa a `annulled`, `voided_at` empieza a informar de cuándo ocurrió y el estado es terminal: anular es **irreversible** y no hay vuelta a `sent` ni a `draft`. **¿Anular o rectificar?** Anula cuando el documento entero nunca debería haber existido y no se ha cobrado — la factura se retira en bloque y no se produce ningún documento rectificativo. Emite una rectificativa (`POST /v1/invoices/{id}/corrective`) cuando la factura ya estaba cobrada, o cuando solo está mal en parte (importe, destinatario, devolución parcial): una factura `paid` no se puede anular nunca, y anular no corrige jamás una cifra. Lo que anular **no** hace: el número correlativo de la serie ni se libera ni se reutiliza (el contador de la serie solo avanza), la factura original no se borra y su registro de *alta* en VeriFactu no se retira. Cuando la empresa está acogida a VeriFactu, se encola un registro de anulación ante la AEAT de forma **asíncrona** con tu `reason` como `motivo` — un `200` significa que la factura está anulada de nuestro lado, no que la AEAT ya haya procesado la anulación. Con VeriFactu inactivo la anulación es puramente interna. Límites: solo se puede anular una factura en `sent` u `overdue`. Un `draft` no es anulable (bórralo en su lugar), y `paid`, `cancelled` y `annulled` devuelven 422. Una factura que **es** rectificativa no se puede anular nunca — para deshacer una rectificativa equivocada, emite una nueva rectificativa de la original. Fíjate en que lo inverso sí se admite: tener rectificativas no impide anular la original. Llama antes a `GET /v1/invoices/{id}/can-annul` si necesitas comprobar la elegibilidad sin intentar el cambio. Aquí `reason` es opcional y se persiste un texto de relleno cuando lo omites. `POST /v1/invoices/{id}/annul` es exactamente la misma operación con `reason` obligatorio — prefiérela siempre que el motivo tenga que quedar documentado. - [Listar métodos de pago](https://docs.factuarea.com/es/api-reference/invoices/public-api.v1.payment_methods.list): Lista el catálogo cerrado de métodos de pago con su `value` público y su `label` localizado. Úsalo para poblar el campo `payment_method` al registrar un pago en lugar de hardcodear valores. - [Cerrar un registro de jornada mensual](https://docs.factuarea.com/es/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.create): Congela el cierre mensual inalterable del registro de jornada para un `(year, month)` finalizado: toma una instantánea de los totales del saldo de cada empleado activo y de su desglose/saldos de ausencias (reutilizando el contrato de saldo, sin recomputar nunca) y bloquea el periodo frente a entradas retroactivas y correcciones. `year` y `month` (1-12) son obligatorios. Un mes que aún no ha terminado devuelve 422 en español; un periodo ya cerrado devuelve 409. Reabrir un periodo previamente reabierto lo vuelve a cerrar, manteniendo su `id` original. Devuelve 201 con el cierre creado y una cabecera `Location`. - [Descargar el registro cerrado (RD-ley 8/2019)](https://docs.factuarea.com/es/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.export): Descarga el registro de jornada diario de un periodo cerrado como hoja de cálculo en el formato `rdley_8_2019`, leído del registro bloqueado y a prueba de manipulaciones (entradas de solo adición + cadena de hashes) del periodo. `format` es opcional y toma por defecto `rdley_8_2019`; un formato fuera del catálogo devuelve 422. Un periodo sin cierre devuelve 404. La respuesta es una descarga de archivo binario. - [Listar todos los cierres mensuales de registro de jornada](https://docs.factuarea.com/es/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.list): Lista los cierres mensuales del registro de jornada de tu empresa con paginación por cursor, ordenados por periodo descendente. Admite filtrar por `year`. Cada elemento expone su estado (`closed`/`reopened`), los límites del periodo y el número de empleados. - [Reabrir un cierre de registro de jornada mensual](https://docs.factuarea.com/es/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.reopen): Reabre un cierre mensual `closed` por su `id` (UUID v7) — una recuperación auditada de un cierre erróneo que rehabilita las escrituras del periodo. El cierre mantiene su `id`; su estado pasa a `reopened`. Un cierre que no puede reabrirse devuelve 422 en español, y uno perteneciente a otra empresa devuelve 404. Devuelve 200 con el cierre reabierto. - [Obtener el informe de un periodo cerrado](https://docs.factuarea.com/es/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.report): Devuelve el informe mensual de un periodo cerrado por el `id` (UUID v7) del cierre, leído de la instantánea congelada sin recomputar, así que los totales nunca divergen de la hoja en el momento del cierre. Contiene los totales agregados de la empresa y una fila por empleado con totales, desglose de ausencias y saldos, y el detalle diario. Los totales están en minutos. Un periodo sin cierre devuelve 404. Un recurso computado: expone `close_id`, nunca un `id` propio. - [Sellar un registro de jornada mensual](https://docs.factuarea.com/es/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.seal): Sella (firma digitalmente) un registro de jornada mensual `closed` por el `id` (UUID v7) del cierre: congela un digest canónico SHA-256 de la instantánea del cierre y una firma RSA-SHA256 separada hecha con el certificado de la empresa, de modo que el registro es a prueba de manipulaciones y verificable de forma independiente. Un cierre que no está `closed` devuelve 422 en español, un periodo ya sellado devuelve 409 (un sello por cierre, sin re-sellado) y una empresa sin un certificado activo utilizable devuelve 422. Un cierre perteneciente a otra empresa devuelve 404. Devuelve 201 con el sello (incluido su estado de verificación en vivo) y una cabecera `Location`. - [Obtener el sello de un registro mensual](https://docs.factuarea.com/es/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.seal_show): Obtén el sello digital de un registro de jornada mensual por el `id` (UUID v7) del cierre, junto con su estado de verificación recomputado en vivo contra la instantánea actual: `verified` es `true` cuando la instantánea y la firma están intactas; en otro caso `verification_reason` explica el desajuste (`snapshot_mismatch`, `signature_invalid` o `certificate_unreadable`). El sello expone su digest, firma y certificado de firma para que un tercero pueda verificarlo. Un cierre sin sello — o perteneciente a otra empresa — devuelve 404 `monthly_register_signature_not_found` (anti-enumeración). - [Obtener un cierre de registro de jornada mensual](https://docs.factuarea.com/es/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.show): Obtén un único cierre mensual por su `id` (UUID v7). Un cierre perteneciente a otra empresa devuelve 404 `monthly_time_record_close_not_found` (anti-enumeración). - [Descargar la exportación de nómina de un mes cerrado](https://docs.factuarea.com/es/api-reference/payroll-exports/public-api.v1.monthly_time_record_closes.payroll_export): Descarga el archivo de incidencias de nómina de un mes cerrado en el formato de un software de nómina español (`a3` para A3 Wolters Kluwer, `sage` para Sage, `nominasol` para NominaSOL), leído de la instantánea congelada del cierre mensual sin recomputar. Cada fila es un empleado con su identidad fiscal (NIF y nombre), minutos trabajados vs esperados, horas extra, saldo y las ausencias aprobadas desglosadas por tipo. `format` es opcional y toma por defecto `a3`; un formato fuera del catálogo devuelve 422. Un periodo sin cierre devuelve 404. La respuesta es una descarga de hoja de cálculo binaria. - [Listar los formatos de exportación de nómina soportados](https://docs.factuarea.com/es/api-reference/payroll-exports/public-api.v1.payroll_export_formats.list): Lista los formatos de software de nómina soportados por la exportación de nómina (`a3`, `sage`, `nominasol`), cada uno con su etiqueta comercial, para que una integración pueda ofrecer un selector de software sin hardcodear los valores. Un catálogo plano de solo lectura sin paginación. - [Listar las declaraciones de presencialidad oficina/remoto](https://docs.factuarea.com/es/api-reference/presence/public-api.v1.presence.daily): Lista las declaraciones de presencialidad oficina/remoto de tu empresa con paginación por cursor. Admite filtrar por `employee_id` (UUID v7), por día exacto (`date`) o por rango de fechas (`from`/`to`, `YYYY-MM-DD`). Cada registro es la ubicación de trabajo declarada por un empleado para un día. De solo lectura en la API pública — las declaraciones se hacen desde la app (solo SPA). - [Obtener la presencia del equipo en vivo](https://docs.factuarea.com/es/api-reference/presence/public-api.v1.presence.live): Devuelve el panel de presencia en vivo de tu equipo para el módulo de Control Horario: un elemento `employee_presence` por empleado activo, con el estado de la jornada derivado del registro inalterable de jornada (`working`/`paused`/`finished`/`away`), el flag de llegada tarde (primer fichaje vs inicio previsto) y la ubicación oficina/remoto declarada hoy. Un recurso computado de solo lectura: cada elemento expone el UUID v7 del empleado como su `id`, nunca un id de registro de presencia. Sin filtros ni paginación. - [Obtener la presencia en vivo de un empleado](https://docs.factuarea.com/es/api-reference/presence/public-api.v1.presence.show): Obtén la presencia en vivo de un único empleado por su `id` (UUID v7): el estado de la jornada derivado del registro, el flag de llegada tarde y la ubicación oficina/remoto declarada hoy. Un empleado que no existe o pertenece a otra empresa devuelve 404 `employee_presence_not_found` (anti-enumeración). Un recurso computado: expone el UUID v7 del empleado como su `id`. - [Listar la línea temporal de actividad del producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.activities): Devuelve la línea de tiempo de auditoría de un producto combinando sus propios eventos de dominio más los eventos de documento cuyas líneas lo referencian. Paginada con los query params page y per_page (50 por defecto). - [Elimina varios productos de forma masiva](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.bulk_delete): Elimina hasta 200 productos en una sola petición. Devuelve un `BulkPartialSuccessResult` con los contadores `total`, `successful` y `failed` más una lista `failures` (`id` + `error_code` + `error_message` en español); los productos incluidos en packs se reportan en `failures`. Decrementa el contador de uso del plan en consecuencia. - [Cambiar en bloque el estado activo de productos](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.bulk_status): Mueve hasta 50 productos (por id) al `new_status` destino (`active` o `inactive`). Idempotente respecto al destino: un producto ya en el estado solicitado cuenta como `successful` sin cambiar. Devuelve un `BulkPartialSuccessResult`; los productos no encontrados vuelven en `failures[]`. - [Actualizar el stock de varios productos](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.bulk_update_stock): Aplica una operación de stock a varios productos en una sola petición (hasta 500). Los UUID que no pertenecen a tu empresa se ignoran silenciosamente. - [Crear un producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.create): Crea un nuevo producto en tu catálogo. - [Elimina un producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.delete): Elimina un producto. Devuelve 422 si el producto está referenciado por alguna línea de documento. - [Buscar un producto por external ID](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.find_by_external_id): Busca un único producto por su `external_id` (enviado en el body JSON), la clave de integración que lo mapea a un registro en un sistema de terceros (ERP/CRM/e-commerce). Ortogonal al `sku` del catálogo. Devuelve el producto coincidente o 404 si ningún producto usa ese external_id dentro de tu empresa. - [Buscar un producto por SKU](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.find_by_sku): Busca un único producto por su `sku` (enviado en el cuerpo JSON). Devuelve el producto coincidente o 404 si ningún producto usa ese SKU dentro de tu empresa. - [Elimina una imagen de la galería de un producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.gallery.delete): Elimina una imagen de la galería por su índice de base 0. Las imágenes restantes desplazan sus posiciones para llenar el hueco. - [Descargar el binario de una imagen de la galería de un producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.gallery.download): Transmite el binario en bruto de una imagen de la galería del producto por su índice basado en 0. Devuelve 404 si el índice no existe o el archivo no está en disco. - [Sube una imagen de galería a un producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.gallery.upload): Adjunta una imagen (jpeg, png, jpg, gif o webp; hasta 3 MB) a la galería del producto. Devuelve el producto actualizado. Falla con 422 si se supera el límite de la galería. - [Listar todos los productos](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.list): Lista los productos de tu catálogo con paginación por cursor. - [Lista los productos por debajo del umbral de stock](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.low_stock_report): Devuelve los productos cuyo stock actual está por debajo de su umbral de stock bajo configurado. Útil para alertas de inventario. - [Obtener analíticas de ventas de productos](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.sales_analytics): Devuelve unidades vendidas, ingresos, número de facturas, variación mes a mes, tendencia mensual de los últimos 6 meses, último comprador y feed de actividad reciente de un solo producto. - [Busca productos](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.search): Busca productos por consulta de texto libre contra `name` y `sku`. Limitado a 50 resultados. - [Obtener un producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.show): Obtiene un producto por su `uuid`. - [Obtener estadísticas de productos](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.stats): KPIs agregados de tu catálogo de productos: número total de productos, número de activos, número por debajo del umbral de stock bajo, valor de stock acumulado y totales por categoría. Devuelto como `{ "data": ProductStats }`. - [Alternar el estado activo del producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.toggle_active): Cambia un producto entre activo e inactivo. Los productos inactivos se ocultan de los selectores de líneas en documentos nuevos. - [Actualizar un producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.update): Actualiza un producto de tu catálogo. - [Actualizar el stock de un producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.update_stock): Reemplaza, incrementa o reduce la cantidad de stock de un producto. Por defecto es set (reemplazar); add y subtract son alias aceptados de increase y decrease. Falla con 422 si el stock resultante fuera negativo. - [Elimina el vídeo del producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.video.delete): Elimina el vídeo asociado al producto y libera el almacenamiento. Idempotente: devuelve 204 incluso cuando no había ningún vídeo adjunto. - [Descargar el binario del vídeo de un producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.video.download): Transmite el binario en bruto del vídeo del producto. Devuelve 404 si el producto no tiene vídeo o el archivo no está en disco. - [Sube un vídeo a un producto](https://docs.factuarea.com/es/api-reference/products/public-api.v1.products.video.upload): Adjunta un archivo de vídeo (mp4, mov, avi o webm; hasta 50 MB) al producto. Reemplaza cualquier vídeo existente. - [Aceptar una proforma](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.accept): Marca una proforma como aceptada por el cliente. Devuelve 422 si la proforma está en un estado que no puede transicionar a `accepted`. - [Eliminación masiva de proformas](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.bulk_delete): Elimina hasta 100 proformas en una sola llamada. Devuelve un `BulkPartialSuccessResult` con los contadores `total`, `successful` y `failed` más una lista `failures` (`id` + `error_code` + `error_message` en español) por cada entrada que no se pudo eliminar. - [Descargar en bloque los PDF de proformas](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.bulk_pdf): Empaqueta los PDF de hasta 50 proformas (por id) en un único ZIP. Los ids no encontrados o sin PDF generable no abortan la petición: el ZIP lleva solo los válidos y los contadores por recurso viajan en las cabeceras de respuesta `X-Bulk-*`. - [Enviar proformas en bloque](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.bulk_send): Envía hasta 200 proformas por email (encolado) en una sola llamada, reutilizando la ruta de envío individual por id. Devuelve un `BulkPartialSuccessResult` con los contadores `total`, `successful` y `failed` más una lista `failures` (`id` + `error_code` + `error_message` en español) por cada proforma que no se pudo enviar (no encontrada, estado no enviable o sin destinatario resoluble). - [Cambiar en bloque el estado de proformas](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.bulk_status): Transiciona hasta 50 facturas proforma (por id) a un estado del conjunto cerrado `[accepted, rejected]`, cada una a través del guard de estado del documento. Devuelve un `BulkPartialSuccessResult`; las proformas cuya transición se rechaza (no encontradas o no transicionables) vuelven en `failures[]`. - [Convertir proforma en factura](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.convert): Convierte una proforma en una factura de venta final. La nueva factura referencia la proforma de origen; la proforma pasa al estado `converted`. - [Crea una proforma](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.create): Crea una nueva factura proforma en estado `draft`. Las proformas pueden convertirse luego en facturas finales. - [Elimina una proforma](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.delete): Elimina una proforma. Devuelve 422 si la proforma se ha convertido en factura. - [Duplicar una proforma](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.duplicate): Crea una nueva proforma en borrador copiando líneas, cliente y metadatos de una proforma existente. - [Buscar una proforma por external ID](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.find_by_external_id): Busca una única proforma por su `external_id` (enviado en el body JSON), la clave de integración que la mapea a un registro en un sistema de terceros (ERP/CRM/e-commerce). Devuelve la proforma coincidente o 404 `proforma_not_found` si ninguna proforma usa ese external_id dentro de tu empresa. - [Listar todas las proformas](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.list): Lista tus facturas proforma con paginación por cursor. - [Descargar el PDF de la proforma](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.pdf): Descarga la representación en PDF de una proforma. - [Recupera el enlace público de la proforma](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.public_link_get): Devuelve la URL pública para compartir de la proforma (/d/{uuid}) junto con su estado, expiración y los días máximos de extensión permitidos por el plan. - [Actualizar el enlace público de una proforma](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.public_link_update): Aplica una acción al enlace público: `revoke`, `activate`, `extend` (con `extend_days`) o `reset` al valor por defecto del plan. - [Rechazar una proforma](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.reject): Marca una proforma como rechazada por el cliente. Devuelve 422 si la proforma está en un estado que no puede transicionar a `rejected`. - [Envía la proforma por email](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.send): Envía una proforma al cliente por email. - [Obtener una proforma](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.show): Obtiene una factura proforma por su `uuid`. - [Obtener estadísticas de proformas](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.stats): KPIs agregados de la empresa autenticada: número y importe total de proformas, número por estado, número de expiradas y número convertidas a factura. Devuelto como `{ "data": ProformaStats }`. - [Lista los estados de proforma](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.statuses): Devuelve el catálogo cerrado de estados de proforma con su `value` público, `label` localizada y `color` de UI. Úsalo para poblar filtros o selectores de estado en lugar de codificar valores a mano. - [Actualizar una proforma](https://docs.factuarea.com/es/api-reference/proformas/public-api.v1.proformas.update): Actualiza una proforma en borrador. Una vez convertida, la proforma se vuelve inmutable. - [Adjuntar un archivo a una factura de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.attach_file): Sube el documento PDF original de una factura de compra como `multipart/form-data`. Reemplaza cualquier archivo adjunto previamente. Devuelve la factura de compra actualizada. - [Eliminación masiva de facturas de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.bulk_delete): Elimina hasta 100 facturas de compra por UUID en una sola petición. Devuelve un `BulkPartialSuccessResult` con los contadores `total`, `successful` y `failed` más una lista `failures` (`id` + `error_code` + `error_message` en español) por cada entrada que no se pudo eliminar. - [Cambiar en bloque el estado de facturas de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.bulk_status): Transiciona hasta 50 facturas de compra (por id) a `paid` en una llamada, cada una a través del guard de estado del documento. La `payment_date` requerida se propaga tal cual a cada factura (nunca `now()`). Devuelve un `BulkPartialSuccessResult`; las facturas que no pudieron transicionar (no encontradas o ya pagadas) vuelven en `failures[]`. - [Crea una factura de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.create): Registra una factura recibida de un proveedor. - [Elimina una factura de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.delete): Elimina una factura de compra. - [Elimina un archivo de una factura de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.delete_file): Elimina el fichero original adjunto a una factura de compra y libera su almacenamiento. Idempotente: tiene éxito incluso cuando no había ningún fichero adjunto. - [Descargar el archivo original de la factura de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.file): Transmite el PDF original adjunto a la factura de compra cuando se subió. Devuelve 404 si no hay ningún adjunto. - [Buscar una factura de compra por external ID](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.find_by_external_id): Busca una única factura de compra por su `external_id` (enviado en el body JSON), la clave de integración que la mapea a un registro en un sistema de terceros (ERP/CRM/e-commerce). Ortogonal al `external_invoice_number` proporcionado por el proveedor (el número fiscal del proveedor). Devuelve la factura de compra coincidente o 404 `purchase_invoice_not_found` si ninguna usa ese external_id dentro de tu empresa. - [Listar todas las facturas de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.list): Lista las facturas de compra recibidas de proveedores con paginación por cursor. - [Listar pagos de factura de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.list_payments): Devuelve el libro de pagos completo de una factura de compra como `{ "data": [...] }`, ordenado por fecha de pago descendente. El libro de una sola factura está acotado, así que se devuelve el conjunto completo sin paginación por cursor. Una factura sin pagos devuelve un array vacío, nunca un `404`; un `404` aquí significa que la factura no existe o pertenece a otra empresa. - [Marca la factura de compra como pagada](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.mark_paid): Registra el pago de una factura de compra. Establece `paid_at` con la marca de tiempo actual. - [Listar facturas de compra vencidas](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.overdue): Devuelve las facturas de compra cuya fecha de vencimiento ha pasado y siguen impagadas. - [Descargar el recibo de pago de una factura de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.payment_receipt): Transmite el PDF del justificante de pago de una factura de compra pagada. Devuelve 409 si la factura aún no se ha pagado. - [Listar facturas de compra pendientes](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.pending): Devuelve las facturas de compra en estado de pago pendiente, paginadas. - [Registrar un pago de factura de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.register_payment): Registra un pago parcial (o total) contra una factura de compra y lo añade a su libro de pagos. Cuerpo: `amount`, `paid_on`, `payment_method`, más los opcionales `bank_account_id`, `reference` y `notes`. Se comprueban tres invariantes que devuelven `422`: el importe tiene que ser mayor que cero y no superior al saldo pendiente, `paid_on` tiene que caer entre la fecha de emisión de la factura y hoy, y una factura cancelada no admite pagos. En cuanto los pagos acumulados cubren el total, la factura se salda sola — no hace falta que llames además a `mark_paid`. Devuelve `201` con el pago recién creado y un header `Location` apuntando al libro de pagos. - [Obtener una factura de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.show): Obtiene una factura de compra por su `uuid`. - [Obtener estadísticas de facturas de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.stats): KPIs agregados de tus facturas de compra: número e importe total, recuentos por estado, totales pendientes y vencidos, e importes por proveedor. Devuelto como `{ "data": PurchaseInvoiceStats }`. - [Actualizar una factura de compra](https://docs.factuarea.com/es/api-reference/purchase-invoices/public-api.v1.purchase_invoices.update): Actualiza una factura de compra. - [Aceptar un presupuesto](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.accept): Marca un presupuesto como aceptado por el cliente. Establece `accepted_at` en el timestamp actual. - [Eliminación masiva de presupuestos](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.bulk_delete): Elimina hasta 100 presupuestos en una sola llamada. Devuelve un `BulkPartialSuccessResult` con los contadores `total`, `successful` y `failed` más una lista `failures` (`id` + `error_code` + `error_message` en español) por cada entrada que no se pudo eliminar. - [Descargar en bloque los PDF de presupuestos](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.bulk_pdf): Empaqueta los PDF de hasta 50 presupuestos (por id) en un único ZIP. Los ids no encontrados o sin PDF generable no abortan la petición: el ZIP lleva solo los válidos y los contadores por recurso viajan en las cabeceras de respuesta `X-Bulk-*`. - [Enviar presupuestos en bloque](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.bulk_send): Envía hasta 200 presupuestos por email (encolado) en una sola llamada, reutilizando la ruta de envío individual por id. Devuelve un `BulkPartialSuccessResult` con los contadores `total`, `successful` y `failed` más una lista `failures` (`id` + `error_code` + `error_message` en español) por cada presupuesto que no se pudo enviar (no encontrado, estado terminal o sin destinatario resoluble). - [Cambiar en bloque el estado de presupuestos](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.bulk_status): Transiciona hasta 50 presupuestos (por id) a un estado del conjunto cerrado `[approved, rejected]`, cada uno a través del guard de estado del documento. Devuelve un `BulkPartialSuccessResult`; los presupuestos cuya transición se rechaza (no encontrados o no transicionables) vuelven en `failures[]`. - [Convertir presupuesto en factura](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.convert): Convierte un presupuesto aceptado en una factura de venta. La nueva factura referencia el presupuesto de origen mediante metadatos; el presupuesto pasa al estado `converted`. - [Crea un presupuesto](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.create): Crea un nuevo presupuesto de venta en estado `draft`. Los presupuestos pueden convertirse luego en facturas mediante `POST /quotes/{quote}/convert`. - [Elimina un presupuesto](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.delete): Elimina un presupuesto. Devuelve 422 si el presupuesto se ha convertido en factura. - [Duplicar un presupuesto](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.duplicate): Crea un nuevo presupuesto en borrador copiando las líneas, el cliente y los metadatos de un presupuesto existente. - [Buscar un presupuesto por external ID](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.find_by_external_id): Busca un único presupuesto por su `external_id` (enviado en el body JSON), la clave de integración que lo mapea a un registro en un sistema de terceros (ERP/CRM/e-commerce). Devuelve el presupuesto coincidente o 404 `quote_not_found` si ningún presupuesto usa ese external_id dentro de tu empresa. - [Listar todos los presupuestos](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.list): Lista tus presupuestos de venta con paginación por cursor. Admite filtrado por `status[in]`, `client_id`, `issued_on[gte|lte]`. - [Descargar el PDF del presupuesto](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.pdf): Descarga la representación en PDF de un presupuesto. - [Recupera el enlace público del presupuesto](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.public_link_get): Devuelve la URL pública para compartir del presupuesto (/d/{uuid}) junto con su estado, expiración y los días máximos de extensión permitidos por el plan. - [Actualizar el enlace público de un presupuesto](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.public_link_update): Aplica una acción al enlace público: `revoke`, `activate`, `extend` (con `extend_days`) o `reset` al valor por defecto del plan. - [Rechazar un presupuesto](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.reject): Marca un presupuesto como rechazado por el cliente. Establece `rejected_at` en el timestamp actual. - [Envía el presupuesto por email](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.send): Envía un presupuesto al cliente por email. - [Obtener un presupuesto](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.show): Obtiene un presupuesto de venta por su `uuid`. - [Obtener estadísticas de presupuestos](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.stats): KPIs agregados de la empresa autenticada: número e importe total de presupuestos, número por estado, número de expirados y número de convertidos. Devuelto como `{ "data": QuoteStats }`. - [Lista los estados de presupuesto](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.statuses): Devuelve la lista canónica de estados de presupuesto disponibles en la API junto con su etiqueta legible y su color de UI. Útil para construir desplegables y filtros. - [Actualizar un presupuesto](https://docs.factuarea.com/es/api-reference/quotes/public-api.v1.quotes.update): Actualiza un presupuesto en borrador. Una vez aceptado/rechazado/convertido, el presupuesto se vuelve inmutable. - [Activar factura recurrente](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.activate): Activa una factura recurrente pausada. La siguiente factura se generará según la programación. Es un alias semántico de `POST /recurring_invoices/{recurring_invoice}/resume` — ambos apuntan al mismo handler y se comportan igual; ninguno está obsoleto. - [Lista la actividad de facturas recurrentes](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.activities): Devuelve la línea de tiempo de actividad paginada por cursor (eventos de dominio: activación, pausa, reanudación, generación, fallo, cancelación, etc.) de una factura recurrente. Los metadatos se sanean para no exponer nunca identificadores internos. - [Eliminación masiva de facturas recurrentes](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.bulk-delete): Elimina varias facturas recurrentes en una sola petición (POST con un body de `ids`). Devuelve el recuento de recursos eliminados y una lista de fallos con su motivo. Las facturas recurrentes que ya han generado facturas no se pueden eliminar. - [Anular factura recurrente](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.cancel): Anula una factura recurrente. A diferencia de `pause`, este es un estado terminal e irreversible: una factura recurrente anulada no puede reanudarse ni reactivarse nunca. Las facturas generadas previamente no se ven afectadas. - [Crea una factura recurrente](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.create): Crea una plantilla de factura recurrente que genera facturas automáticamente con una cadencia fija (semanal, mensual, trimestral, anual). - [Elimina una factura recurrente](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.delete): Elimina una plantilla de factura recurrente. Las facturas futuras dejan de generarse; las facturas existentes se conservan. - [Buscar una factura recurrente por external ID](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.find_by_external_id): Busca una única plantilla de factura recurrente por su `external_id` (enviado en el body JSON), la clave de integración que la mapea a un registro en un sistema de terceros (ERP/CRM/e-commerce). Devuelve la factura recurrente coincidente o 404 `recurring_invoice_not_found` si ninguna usa ese external_id dentro de tu empresa. - [Genera una factura a partir de una plantilla recurrente](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.generate): Dispara la generación inmediata de factura a partir de la configuración recurrente, fuera del ciclo programado. - [Listar todas las facturas recurrentes](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.list): Lista tus plantillas de facturas recurrentes con paginación por cursor. - [Lista los logs de ejecución de facturas recurrentes](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.logs): Devuelve el historial paginado de generaciones, fallos y otros eventos de esta plantilla recurrente. - [Pausar factura recurrente](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.pause): Pausa una factura recurrente. No se generarán nuevas facturas hasta que se reanude. Reversible — usa `resume`/`activate` para reactivarla. Para una parada permanente e irreversible usa `cancel`. - [Vista previa de las próximas fechas de la factura recurrente](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.preview): Devuelve las próximas fechas de ejecución programadas con sus fechas de vencimiento e importes estimados. Por defecto 5 ocurrencias. - [Reanudar factura recurrente](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.resume): Reanuda una factura recurrente pausada. Es un alias semántico de `POST /recurring_invoices/{recurring_invoice}/activate` — ambos apuntan al mismo handler y se comportan de forma idéntica; ninguno está deprecado. - [Obtener una factura recurrente](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.show): Obtiene una plantilla de factura recurrente por su `uuid`. - [Omitir la próxima generación de la factura recurrente](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.skip): Avanza la factura recurrente a su siguiente ejecución programada sin generar una factura para el ciclo actual. La ocurrencia omitida no cuenta contra ningún límite de ocurrencias. Las facturas recurrentes canceladas o completadas devuelven 422. - [Recupera las estadísticas de facturas recurrentes](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.stats): KPIs agregados de tus facturas recurrentes: recuentos por estado, vencen hoy / esta semana, generadas y fallidas este mes, desglose por frecuencia, próximas ejecuciones programadas e ingresos estimados este mes. - [Actualizar una factura recurrente](https://docs.factuarea.com/es/api-reference/recurring-invoices/public-api.v1.recurring_invoices.update): Actualiza una plantilla de factura recurrente. La cadencia y las líneas se aplican a las facturas generadas tras la actualización; las facturas generadas previamente no se ven afectadas. - [Listar series activas por tipo de documento](https://docs.factuarea.com/es/api-reference/series/public-api.v1.series.active): Devuelve todas las series no archivadas del tipo de documento indicado dentro de tu empresa. - [Lista la línea temporal de actividad de la serie](https://docs.factuarea.com/es/api-reference/series/public-api.v1.series.activities): Devuelve la línea de tiempo de auditoría de una serie combinando sus propios eventos de dominio (creación, archivado/desarchivado, cambios de predeterminado, consumo de numeración). Paginada con un cursor de número de página (`starting_after` es el número de la siguiente página). - [Archivar una serie](https://docs.factuarea.com/es/api-reference/series/public-api.v1.series.archive): Archiva una serie para que deje de aparecer como disponible para nuevos documentos. Falla con 409 si la serie es la predeterminada y la única serie activa de su tipo. Devuelve 204 en caso de éxito. - [Crea las series por defecto de una empresa](https://docs.factuarea.com/es/api-reference/series/public-api.v1.series.bootstrap): Deja a una empresa en condiciones de emitir documentos en una sola llamada: para cada tipo de documento de la superficie pública (`invoice`, `quote`, `delivery_note`, `proforma`) que no tenga serie activa, crea su serie por defecto con el código y el nombre canónicos. Sin cuerpo de petición. **Qué devuelve** - Una entrada por tipo de documento, con un `status` de `created`, `existing` o `no_default`. - `no_default` significa que el tipo tiene series activas pero ninguna marcada por defecto — archivar la serie por defecto la degrada sin promover un sustituto — y la empresa sigue sin poder emitir ese documento. - Trata `no_default` como trabajo pendiente, no como éxito: las series activas llegan en `candidates` y lo resuelves con `POST /v1/series/{id}/default`. **Por qué no elige por ti** Elegir qué serie numera los documentos de una empresa tiene consecuencias registrales que solo tú puedes decidir, así que el bootstrap nunca promueve ninguna en tu lugar. **Si lo llamas dos veces** - Idempotente por regla de negocio: una segunda llamada no crea nada, no falla y vuelve a informar del estado. - INDEPENDIENTE del header `Idempotency-Key`: con el header, una clave repetida repite el cuerpo original — entradas `created` incluidas — en lugar de informar del estado actual. - [Crea una serie](https://docs.factuarea.com/es/api-reference/series/public-api.v1.series.create): Crea una serie de numeración de documentos. El opcional `number_format` fija la máscara de numeración (p. ej. `{code}-{YYYY}-{00000}`) e `initial_number` (≥1) arranca el contador para continuar una numeración existente. El mismo código puede reutilizarse entre tipos de documento (multi-series). Una serie es inmutable una vez creada según AEAT (`PUT` devuelve 405), así que esto solo puede fijarse aquí. - [Obtener la serie por defecto para un tipo de documento](https://docs.factuarea.com/es/api-reference/series/public-api.v1.series.default): Devuelve la serie de numeración predeterminada para el tipo de documento indicado (invoice, quote, proforma, delivery_note). Devuelve 404 cuando no hay predeterminado configurado. - [Buscar una serie por código](https://docs.factuarea.com/es/api-reference/series/public-api.v1.series.find_by_code): Busca una serie por su `code` (cuerpo JSON, sin distinguir mayúsculas). Un `code` no es único entre tipos de documento (multi-series), así que pasa `document_type` para resolver la serie `(code, document_type)` exacta. Si lo omites, el código se busca en todos los tipos: se devuelve una única coincidencia, pero un código ambiguo devuelve 422 `document_type_required_for_ambiguous_code` en lugar de elegir uno en silencio. Devuelve 404 si no existe ninguna. - [Listar todas las series](https://docs.factuarea.com/es/api-reference/series/public-api.v1.series.list): Lista tus series de numeración de documentos con paginación por cursor. - [Marca una serie como predeterminada para su tipo](https://docs.factuarea.com/es/api-reference/series/public-api.v1.series.set_default): Promueve una serie a predeterminada para su tipo de documento. Si otra serie era la predeterminada para el mismo tipo, se degrada de forma atómica. Devuelve 204 en caso de éxito. - [Obtener una serie](https://docs.factuarea.com/es/api-reference/series/public-api.v1.series.show): Obtiene una serie por su `uuid`. Las series son **inmutables** por cumplimiento fiscal (AEAT VeriFactu — continuidad legal de la numeración): `PUT`, `PATCH` y `DELETE` sobre `/v1/series/{uuid}` devuelven `405 Method Not Allowed` con `error.code = "series_immutable"` y la cabecera `Allow: GET, POST`. Para "eliminar" una serie usa `POST /v1/series/{uuid}/archive`; para cambiar la numeración, crea una nueva serie y márcala como predeterminada. - [Obtener estadísticas de series](https://docs.factuarea.com/es/api-reference/series/public-api.v1.series.stats): KPIs agregados de tus series de numeración de documentos: número total de series, número de activas y archivadas, y desglose por tipo de documento. Devuelto como `{ "data": SeriesStats }`. - [Desarchivar una serie](https://docs.factuarea.com/es/api-reference/series/public-api.v1.series.unarchive): Devuelve una serie archivada al conjunto activo. No cambia el predeterminado actual de su tipo. Devuelve 204 si tiene éxito. - [Listar payouts de Stripe](https://docs.factuarea.com/es/api-reference/stripe/public-api.v1.payouts.list): Lista los payouts de Stripe ingeridos para tu empresa, con paginación por cursor. Cada uno expone los importes neto/comisiones/bruto, la moneda, la fecha de llegada, el `status` de conciliación (`ingested`/`reconciled`) y una `composition` informativa. Filtra por `status` y por ventana de fecha de llegada. Los payouts son de solo lectura; la conciliación bancaria ocurre en el dashboard. - [Obtener un payout de Stripe](https://docs.factuarea.com/es/api-reference/stripe/public-api.v1.payouts.show): Obtén un payout de Stripe por su `id` (UUID v7). Devuelve los importes, la divisa, la fecha de llegada, el estado de conciliación (`bank_transaction_ref` una vez conciliado) y la `composition` informativa de los cobros componentes. Devuelve 404 si el payout no existe o pertenece a otra empresa. - [Desconectar una cuenta Stripe conectada](https://docs.factuarea.com/es/api-reference/stripe/public-api.v1.stripe_autoinvoicing.accounts.disconnect): Desconecta una cuenta de Stripe conectada sin tocar las demás. La cuenta se marca `disconnected` (sus facturas ya emitidas y su histórico se conservan; los webhooks posteriores se registran sin procesar). Responde 204 sin cuerpo. Una cuenta inexistente o de otra empresa devuelve 404. - [Listar cuentas Stripe conectadas](https://docs.factuarea.com/es/api-reference/stripe/public-api.v1.stripe_autoinvoicing.accounts.list): Lista las cuentas de Stripe conectadas (Stripe Connect, multi-tienda) de tu empresa. Cada una expone su `id`, `name`, `external_account_id` (`acct_xxx`), la `series_id` asignada, su configuración por cuenta (`autoinvoicing_enabled`, `simplified_threshold_cents`, `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`), `status` y `connected_at`. Los cargos se autofacturan con la serie y la configuración de esa cuenta. - [Obtener una cuenta Stripe conectada](https://docs.factuarea.com/es/api-reference/stripe/public-api.v1.stripe_autoinvoicing.accounts.show): Obtiene una cuenta Stripe conectada por su `id` (UUID v7). Devuelve su nombre, id de cuenta externa, serie asignada (`series_id`), la configuración efectiva de auto-facturación por cuenta y su estado. Devuelve 404 si la cuenta no existe o pertenece a otra empresa. - [Actualizar una cuenta Stripe conectada](https://docs.factuarea.com/es/api-reference/stripe/public-api.v1.stripe_autoinvoicing.accounts.update): Actualiza una cuenta de Stripe conectada: su `name`, la `series_id` de autofacturación (`null` la borra, volviendo a la serie por defecto de la empresa) y la política fiscal por cuenta (`autoinvoicing_enabled`, `simplified_threshold_cents`, `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`). Todos los campos son opcionales; los omitidos mantienen su valor. - [Obtener la configuración de auto-facturación de Stripe](https://docs.factuarea.com/es/api-reference/stripe/public-api.v1.stripe_autoinvoicing.config.show): Devuelve el estado de la integración de Stripe Connect y la configuración de autofacturación: si Stripe está conectado y activado, la serie usada, el gating por plan, y la política fiscal (`simplified_threshold_cents`, `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`). Con varias cuentas conectadas devuelve 422 `per_account_config_required` —lee cada una vía `GET /v1/connected-accounts`. - [Actualizar la configuración de auto-facturación de Stripe](https://docs.factuarea.com/es/api-reference/stripe/public-api.v1.stripe_autoinvoicing.config.update): Activa o desactiva la autofacturación de los cargos de Stripe Connect y elige la serie usada. Opcionalmente ajusta la política fiscal (`simplified_threshold_cents` en céntimos [0, 300000], `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`); los campos omitidos mantienen su valor. Con varias cuentas conectadas devuelve 422 `per_account_config_required` —configura cada cuenta individualmente. - [Listar las rectificativas auto-facturadas de Stripe](https://docs.factuarea.com/es/api-reference/stripe/public-api.v1.stripe_autoinvoicing.correctives.list): Lista las facturas rectificativas generadas automáticamente a partir de devoluciones de Stripe (`charge.refunded`), con paginación por cursor. El `id` público es la factura rectificativa (UUID v7); `original_invoice_id` enlaza con la factura original, y `refund_id` es la devolución de origen de la pasarela. - [Listar cobros auto-facturados de Stripe](https://docs.factuarea.com/es/api-reference/stripe/public-api.v1.stripe_autoinvoicing.payments.list): Lista los cargos de Stripe que generaron una factura (flujos A y B más ciclos de suscripción), con paginación por cursor. La factura y el cliente generados se devuelven como `invoice_id`/`client_id`. Los cargos de ciclo de suscripción también exponen `subscription_id` (externo `sub_xxx`), `stripe_invoice_id` y el periodo facturado. Filtra por `origin` (`subscription`/`oneshot`). - [Lista la línea temporal de actividad del proveedor](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.activities): Devuelve la línea de tiempo de auditoría de un proveedor combinando sus propios eventos de dominio más los eventos de factura de compra y contrato que lo referencian. Paginada con los query params page y per_page (50 por defecto). - [Elimina varios proveedores de forma masiva](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.bulk_delete): Elimina hasta 200 proveedores en una sola petición. Devuelve un `BulkPartialSuccessResult` con los contadores `total`, `successful` y `failed` más una lista `failures` (`id` + `error_code` + `error_message` en español); los proveedores con contratos asociados se reportan en `failures`. Los UUIDs de otros tenants se ignoran. - [Cambiar en bloque el estado activo de proveedores](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.bulk_status): Mueve hasta 50 proveedores (por id) al `new_status` destino (`active` o `inactive`). Idempotente respecto al destino: un proveedor ya en el estado solicitado cuenta como `successful` sin cambiar. Devuelve un `BulkPartialSuccessResult`; los proveedores no encontrados vuelven en `failures[]`. - [Crea un proveedor](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.create): Crea un nuevo proveedor para tu empresa. El objeto devuelto incluye el `uuid` generado. - [Elimina un proveedor](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.delete): Elimina un proveedor. Devuelve 422 si el proveedor está referenciado por alguna factura de compra. - [Buscar un proveedor por external ID](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.find_by_external_id): Busca un proveedor por su `external_id` (enviado en el body JSON), la clave de integración persistente que lo mapea a un registro en un sistema de terceros (ERP/CRM). Distinto del `tax_id` fiscal y del `Idempotency-Key` a nivel de petición. Devuelve el proveedor coincidente o 404 si ningún proveedor usa ese external_id dentro de tu empresa. - [Buscar un proveedor por tax ID](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.find_by_tax_id): Busca un proveedor por su identificador fiscal español (NIF/CIF/NIE/VAT). Devuelve el proveedor coincidente o 404 si ningún proveedor usa ese tax_id dentro de tu empresa. - [Listar todos los proveedores](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.list): Lista tus proveedores con paginación por cursor. Admite filtrado por `is_active`, `created_at[gte|lte]`. - [Busca proveedores](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.search): Busca proveedores por consulta de texto libre contra `name`, `tax_id`, `vat_id`, `email` y `phone`. Limitado a 50 resultados. - [Obtener un proveedor](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.show): Obtiene un proveedor por su `uuid`. - [Obtener estadísticas de proveedores](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.stats): KPIs agregados de la empresa autenticada: número total de proveedores, número de activos, número con contratos e importes totales por estado. Devuelto como `{ "data": SupplierStats }`. - [Alternar el estado activo del proveedor](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.toggle_active): Cambia un proveedor entre activo e inactivo. Los proveedores inactivos se ocultan de los selectores de líneas en facturas de compra nuevas. - [Actualizar un proveedor](https://docs.factuarea.com/es/api-reference/suppliers/public-api.v1.suppliers.update): Actualiza un proveedor. Solo se modifican los campos presentes en el payload. - [Lista las actividades de informes de impuestos](https://docs.factuarea.com/es/api-reference/tax-reports/public-api.v1.tax_reports.activities): Devuelve la línea de tiempo de actividad paginada por cursor (generación, descarga, etc.) de una única generación de informe fiscal. - [Descargar el archivo del informe de impuestos](https://docs.factuarea.com/es/api-reference/tax-reports/public-api.v1.tax_reports.download): Descarga el fichero generado de un informe fiscal. Añade el header `X-Tax-Report-Hash` para verificación de integridad. - [Buscar un informe de impuestos por periodo](https://docs.factuarea.com/es/api-reference/tax-reports/public-api.v1.tax_reports.find_by_period): Busca el informe fiscal generado más reciente para un tipo y periodo dados. Devuelve el informe o 404 `tax_report_not_found` cuando no existe ninguno para el periodo. - [Generar Modelo 130](https://docs.factuarea.com/es/api-reference/tax-reports/public-api.v1.tax_reports.generate_130): Genera el Modelo 130 español (pago fraccionado trimestral del IRPF, estimación directa) para el año y trimestre dados en el formato solicitado (txt_aeat, pdf, excel; por defecto pdf). El cálculo es acumulativo desde el inicio del año (del 1 de enero al cierre del trimestre). - [Generar Modelo 303](https://docs.factuarea.com/es/api-reference/tax-reports/public-api.v1.tax_reports.generate_303): Genera el Modelo 303 español (IVA trimestral) para el año y trimestre indicados en el formato solicitado (txt_aeat, pdf, excel). - [Generar Modelo 347](https://docs.factuarea.com/es/api-reference/tax-reports/public-api.v1.tax_reports.generate_347): Genera el Modelo 347 español (operaciones anuales con terceros > 3,005.06 EUR) para el año indicado. - [Lista el historial de informes de impuestos](https://docs.factuarea.com/es/api-reference/tax-reports/public-api.v1.tax_reports.history): Devuelve el histórico paginado de informes fiscales generados de la empresa. Filtros opcionales: type, year. - [Vista previa de un informe de impuestos](https://docs.factuarea.com/es/api-reference/tax-reports/public-api.v1.tax_reports.preview): Calcula el desglose de un informe fiscal sin persistir una generación ni escribir ficheros. Ideal para UIs interactivas que confirman los totales antes de consolidar. - [Recupera las estadísticas del informe de impuestos](https://docs.factuarea.com/es/api-reference/tax-reports/public-api.v1.tax_reports.stats): Devuelve KPIs agregados del histórico de informes fiscales generados: totales por tipo y formato, tamaño de fichero acumulado, y el trimestre/año fiscal actual. - [Obtener el saldo horario de un empleado para un periodo](https://docs.factuarea.com/es/api-reference/time-balances/public-api.v1.time_balances.employee): Devuelve el saldo horario de un periodo arbitrario de un empleado: minutos esperados vs trabajados, el saldo y las horas extra por día, y los totales del periodo. El empleado es el `{employee}` (UUID v7) de la ruta; `from` y `to` (`YYYY-MM-DD`) son obligatorios. Es el mismo contrato que el cierre mensual reutiliza sobre periodos cerrados. Un rango donde `to` es anterior a `from` devuelve 422. Los totales están en minutos. Un recurso computado: expone `employee_id`, nunca un `id`. - [Obtener la hoja horaria mensual de un empleado](https://docs.factuarea.com/es/api-reference/time-balances/public-api.v1.time_balances.monthly_sheet): Devuelve la hoja horaria mensual en vivo de un empleado para el periodo abierto (en curso): minutos esperados vs trabajados, el saldo y las horas extra por día, y los totales mensuales. `employee_id` (UUID v7) es obligatorio; `month` (`YYYY-MM`) toma por defecto el mes actual. La hoja se recomputa en cada petición desde el registro inalterable, así que un fichaje recién registrado se refleja sin cerrar el mes. Los minutos esperados descuentan festivos y ausencias aprobadas. Los totales están en minutos. Un recurso computado: expone `employee_id`, nunca un `id`. - [Obtener el resumen de saldo horario del equipo](https://docs.factuarea.com/es/api-reference/time-balances/public-api.v1.time_balances.team_summary): Devuelve el resumen de saldo horario del equipo (vista de responsable) para un mes: una fila por empleado activo con sus minutos esperados, trabajados, saldo y horas extra. `month` (`YYYY-MM`) toma por defecto el mes actual. Solo se incluyen los empleados activos con un horario. Los totales están en minutos. Un recurso computado sin `id`. - [Aprobar una corrección de fichaje](https://docs.factuarea.com/es/api-reference/time-corrections/public-api.v1.time_corrections.approve): Aprueba una solicitud de corrección pendiente por su `id` (UUID v7), añadiendo la `correction_entry` resolutoria enlazada al fichaje original. Puede aportarse una `note` opcional del aprobador. Una solicitud que no está pendiente devuelve 422 (ya resuelta), y aprobar tu propia solicitud devuelve 422 (la autoaprobación está prohibida). Devuelve 200 con la corrección resuelta. - [Solicitar una corrección de fichaje](https://docs.factuarea.com/es/api-reference/time-corrections/public-api.v1.time_corrections.create): Solicita la corrección de un fichaje (RD-ley 8/2019). `time_entry_id` (UUID v7 de la entrada a corregir), `kind` (`add_missing_entry`/`adjust_time`/`remove_entry`), un `reason` y los valores `proposed` son obligatorios. Una corrección es una nueva entrada de solo adición que referencia la entrada original sin mutarla (análogo a una factura rectificativa); el flujo queda `pending` hasta que un responsable la aprueba o rechaza. Devuelve 201 con la solicitud creada y una cabecera `Location`. - [Listar todas las correcciones de fichaje](https://docs.factuarea.com/es/api-reference/time-corrections/public-api.v1.time_corrections.list): Lista las solicitudes de corrección de fichaje de tu empresa con paginación por cursor, ordenadas por hora de solicitud. Admite filtrar por `status` (`pending` es la bandeja del responsable, `approved`/`rejected` están resueltas), `employee_id` (UUID v7) y un rango de fechas (`from`/`to`). - [Rechazar una corrección de fichaje](https://docs.factuarea.com/es/api-reference/time-corrections/public-api.v1.time_corrections.reject): Rechaza una solicitud de corrección pendiente por su `id` (UUID v7) con un `reason` obligatorio, resolviéndola sin tocar el fichaje original. Una solicitud que no está pendiente devuelve 422 (ya resuelta). Devuelve 200 con la corrección resuelta. - [Obtener una corrección de fichaje](https://docs.factuarea.com/es/api-reference/time-corrections/public-api.v1.time_corrections.show): Obtén una única solicitud de corrección por su `id` (UUID v7), incluido su estado derivado. Una solicitud perteneciente a otra empresa devuelve 404 `correction_request_not_found` (anti-enumeración). - [Validar la cadena de hashes del registro de jornada](https://docs.factuarea.com/es/api-reference/time-entries/public-api.v1.time_entries.chain.validate): Recomputa la cadena de hashes SHA-256 (`huella`) del registro de jornada de tu empresa y la compara con los valores persistidos sin mutar datos. Devuelve si la cadena está intacta y, si no, el `id` (UUID v7) del primer registro corrupto — las huellas en sí nunca se exponen. Limitado a 1 petición/minuto y rechazado con 422 `dataset_too_large` para conjuntos de más de 50.000 registros. - [Fichar la entrada de un empleado](https://docs.factuarea.com/es/api-reference/time-entries/public-api.v1.time_entries.clock_in): Ficha el inicio de la jornada de un empleado, abriendo un nuevo tramo de trabajo. `employee_id` (UUID v7) y `source` (`web`/`mobile`) son obligatorios; `occurred_at` toma por defecto la hora del servidor. Válido solo cuando el empleado no ha fichado ya la entrada; una transición inválida devuelve 422 en español. Devuelve 201 con la entrada `clock_in` creada. - [Fichar la salida de un empleado](https://docs.factuarea.com/es/api-reference/time-entries/public-api.v1.time_entries.clock_out): Ficha el fin del tramo de trabajo actual del empleado (desde `working` o `paused`). `employee_id` (UUID v7) y `source` son obligatorios. Válido solo cuando hay un tramo abierto; una transición inválida devuelve 422 en español. Devuelve 201 con la entrada `clock_out` creada. - [Obtener el estado de jornada actual de un empleado](https://docs.factuarea.com/es/api-reference/time-entries/public-api.v1.time_entries.current): Devuelve el estado derivado de la jornada actual de un empleado (`not_started`/`working`/`paused`/`finished`), reconstruido desde el tramo de trabajo abierto en el registro inalterable — no hay tabla de sesión. `employee_id` (UUID v7) es obligatorio como parámetro de query. - [Listar todos los fichajes](https://docs.factuarea.com/es/api-reference/time-entries/public-api.v1.time_entries.list): Lista los fichajes de tu empresa con paginación por cursor, ordenados por `occurred_at`. Admite filtrar por `employee_id` (UUID v7), un rango de fechas (`from`/`to`) y `entry_type` (`clock_in`/`pause_start`/`pause_end`/`clock_out`). - [Registrar una entrada manual retroactiva](https://docs.factuarea.com/es/api-reference/time-entries/public-api.v1.time_entries.manual): Registra un tramo de trabajo pasado de un empleado (una entrada manual retroactiva). `employee_id` (UUID v7), `started_at`, `ended_at` y un `reason` son obligatorios; los `pauses` opcionales añaden intervalos de pausa. Las entradas se almacenan con `is_retroactive: true` y `source: manual`, y se escribe una entrada de log de auditoría. `ended_at` anterior a `started_at`, o un motivo ausente, devuelve 422 en español. Devuelve 201 con la entrada `clock_out` del tramo creado. - [Iniciar una pausa](https://docs.factuarea.com/es/api-reference/time-entries/public-api.v1.time_entries.pause): Inicia una pausa en el tramo de trabajo actual del empleado. `employee_id` (UUID v7) y `source` son obligatorios. Válido solo cuando el empleado está `working`; una transición inválida devuelve 422 en español. Devuelve 201 con la entrada `pause_start` creada. - [Reanudar tras una pausa](https://docs.factuarea.com/es/api-reference/time-entries/public-api.v1.time_entries.resume): Reanuda la jornada del empleado tras una pausa. `employee_id` (UUID v7) y `source` son obligatorios. Válido solo cuando el empleado está `paused`; una transición inválida devuelve 422 en español. Devuelve 201 con la entrada `pause_end` creada. - [Obtener un fichaje](https://docs.factuarea.com/es/api-reference/time-entries/public-api.v1.time_entries.show): Obtén un único fichaje por su `id` (UUID v7). Una entrada perteneciente a otra empresa devuelve 404 `time_record_entry_not_found` (anti-enumeración). - [Obtener la configuración de control horario](https://docs.factuarea.com/es/api-reference/time-tracking-settings/public-api.v1.time_tracking_settings.show): Devuelve la configuración de control horario de tu empresa: la base de cómputo de horas extra (`weekly`/`daily`) y los umbrales, la tolerancia de redondeo y los ajustes del recordatorio de fichaje olvidado. Si tu empresa aún no la ha configurado, se devuelven los valores por defecto con `id: null` — la primera actualización materializa la fila. - [Actualizar la configuración de control horario](https://docs.factuarea.com/es/api-reference/time-tracking-settings/public-api.v1.time_tracking_settings.update): Crea o actualiza la configuración de control horario de tu empresa: `overtime_basis` (`weekly`/`daily`), los umbrales opcionales de horas extra diario/semanal en minutos (`null` los deriva del horario), la tolerancia de redondeo `overtime_tolerance_minutes`, y el interruptor del recordatorio de fichaje y sus minutos de gracia. Un umbral o tolerancia negativos devuelven 422 en español. Devuelve los ajustes actualizados con `id` = UUID v7 de la fila. - [Forzar la creación del registro VeriFactu de una factura](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.invoices.verifactu_create): Crea el registro de alta VeriFactu para una factura ya emitida y encola la transmisión a la AEAT. Úsalo cuando se omitió la creación automática al enviar. - [Recupera el registro VeriFactu de la factura](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.invoices.verifactu_get): Devuelve el registro VeriFactu (SIF de la AEAT) asociado a la factura si existe. Responde con `data: null` cuando la factura aún no tiene registro. - [Listar registros de acceso de AEAT](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.aeat_access.list): Devuelve el libro de accesos AEAT disociado (anonimizado) con paginación por cursor. Los identificadores fiscales de terceros (NIF) nunca se exponen; el cursor usa el UUID v7 del registro subyacente solo para ordenar. - [Obtener un registro de acceso a AEAT](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.aeat_access.show): Obtiene un único registro de acceso AEAT disociado por su `id` (UUID v7). Devuelve 404 si el registro no existe o pertenece a otra empresa. - [Activar un certificado de empresa](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.certificates.activate): Convierte en activo un certificado subido previamente. Cualquier otro certificado activo se desactiva de forma atómica. Devuelve 404 si el certificado no existe en tu empresa. - [Recupera el certificado activo](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.certificates.active): Devuelve el certificado FNMT actualmente activo usado para firmar las transmisiones VeriFactu. Devuelve 404 si aún no se ha subido ningún certificado. - [Listar certificados de la empresa](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.certificates.list): Lista los certificados FNMT (PKCS#12) subidos de tu empresa. La contraseña del certificado nunca se expone en esta representación. - [Revoca un certificado de empresa](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.certificates.revoke): Revoca (elimina) un certificado de la empresa para que ya no pueda firmar transmisiones VeriFactu. Devuelve 404 si el certificado no existe en tu empresa. - [Sube un certificado de empresa](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.certificates.upload): Sube un certificado FNMT (PKCS#12, `.p12`/`.pfx`) como `multipart/form-data` con `certificate_file` y `certificate_password`. El fichero se valida por magic bytes (ASN.1 DER) y se limita a 100 KB; la contraseña se cifra en reposo. El certificado subido se activa automáticamente (los anteriores se desactivan). El header `Location` apunta a `/v1/verifactu/certificates/active`. - [Valida la cadena de hashes de VeriFactu](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.chain.validate): Recalcula la cadena de huellas VeriFactu (`huella`) de tu empresa y la compara con los valores persistidos sin mutar datos. Devuelve si la cadena está íntegra y, si no, el primer registro corrupto. Limitado a 1 petición/minuto y rechazado con 422 `dataset_too_large` para conjuntos de más de 50,000 registros. - [Recupera la configuración de VeriFactu](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.config): Devuelve la configuración VeriFactu de tu empresa (modo, entorno, estado de alta). La contraseña del certificado nunca se expone. Se devuelve como `{ "data": VeriFactuConfig }`. - [Recupera la declaración responsable actual](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.declaracion.current): Devuelve la versión vigente (la más reciente) de la Declaración Responsable VeriFactu a nivel de productor. Solo lectura: la declaración es global del productor del sistema (Factuarea), no por empresa. Devuelve 404 `declaracion_not_found` si no se ha publicado ninguna. - [Listar el historial de declaración responsable](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.declaracion.history): Devuelve todas las versiones de la Declaración Responsable VeriFactu a nivel de productor (la declaración de cumplimiento SIF emitida por Factuarea), ordenadas por `version` descendente. Solo lectura: la declaración es global del productor del sistema, no por empresa. - [Lista los eventos de VeriFactu](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.events.list): Lista los eventos SIF de VeriFactu de tu empresa (transmisiones de alta/anulación, reintentos, respuestas de la AEAT) con paginación por cursor. - [Reintenta un evento de VeriFactu](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.events.retry): Re-encola la transmisión a la AEAT de un evento VeriFactu fallido. Devuelve 404 si el evento no existe, 422 `business_rule_violation` / `event_already_processed` si ya fue aceptado, y 422 `max_retries_exceeded` cuando se alcanza el límite de reintentos. - [Obtener un evento VeriFactu](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.events.show): Obtiene un único evento SIF de VeriFactu por su `id` (UUID v7). Devuelve 404 si el evento no existe o pertenece a otra empresa. - [Obtener el resumen de eventos de VeriFactu](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.events.summary): Devuelve un resumen agregado de tus eventos SIF de VeriFactu agrupados por tipo y resultado. Útil para dashboards. Se devuelve como `{ "data": VeriFactuEventSummary }`. - [Lista la línea temporal de actividad del registro VeriFactu](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.records.activities): Devuelve la línea de tiempo de auditoría de un único registro VeriFactu (creación, intentos de transmisión, aceptación/rechazo de la AEAT). Paginada con un cursor de número de página. - [Buscar un registro VeriFactu por CSV de la AEAT](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.records.find_by_csv): Busca un registro VeriFactu por el `aeat_csv` (Código Seguro de Verificación) devuelto por la AEAT al aceptar, enviado en el cuerpo JSON. Devuelve el registro coincidente o 404 `verifactu_record_not_found`. - [Buscar un registro VeriFactu por hash](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.records.find_by_huella): Busca un registro VeriFactu por su `huella` (la huella SHA-256 encadenada, enviada en el cuerpo JSON). Devuelve el registro coincidente o 404 `verifactu_record_not_found` si no existe ninguno en tu empresa. - [Buscar un registro VeriFactu por número de factura](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.records.find_by_invoice_number): Busca el registro VeriFactu asociado a un número de factura dado (enviado en el cuerpo JSON). Devuelve el registro coincidente o 404 `verifactu_record_not_found` si la factura no tiene registro en tu empresa. - [Lista los registros VeriFactu](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.records.list): Lista los registros VeriFactu (SIF de la AEAT) de tu empresa con paginación por cursor. Cada registro captura el alta/anulación presentada a la AEAT, su cadena de huellas (`huella`), el `aeat_csv` y el estado de transmisión. Admite filtrado por `status`, `type`, `date_from`/`date_to` y `environment`. - [Reintenta la transmisión a VeriFactu](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.records.retry): Re-encola un registro VeriFactu fallido para su transmisión a la AEAT. Conflicto (409) si ya fue aceptado, 422 si se superó el límite de reintentos. - [Obtener un registro VeriFactu](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.records.show): Obtiene un registro VeriFactu por su `id` (UUID v7). Devuelve 404 `verifactu_record_not_found` si el registro no existe o pertenece a otra empresa. - [Subsanar un registro VeriFactu rechazado](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.records.subsanar): Subsana un registro VeriFactu rechazado por AEAT: regenera el contenido subsanable a partir de la factura de origen conservando la `huella` original, reinicia la ronda de transmisión y vuelve a encolar la transmisión a AEAT (202). Devuelve 422 `record_not_rejected` si el registro no está rechazado, o `requires_annulment` cuando la subsanación afecta a campos de la huella (en su lugar hace falta anular + nueva alta). - [Actualizar la configuración de VeriFactu](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.settings.update): Actualiza la configuración VeriFactu de tu empresa (p. ej. modo/entorno). Devuelve 422 `business_rule_violation` cuando una transición está bloqueada por cumplimiento AEAT (por ejemplo, una vez activado el modo VeriFactu no puede desactivarse silenciosamente). - [Obtener estadísticas de VeriFactu](https://docs.factuarea.com/es/api-reference/verifactu/public-api.v1.verifactu.stats): KPIs agregados de tus registros VeriFactu: recuento total, recuentos por estado (pending, submitted, accepted, rejected, error), desglose por tipo de registro y de factura, y fecha de la última transmisión. Acepta los filtros opcionales `date_from`, `date_to` y `environment`. Se devuelve como `{ "data": VeriFactuStats }`. - [Crea un webhook endpoint](https://docs.factuarea.com/es/api-reference/webhooks/public-api.v1.webhook_endpoints.create): Crea un webhook endpoint que recibe notificaciones de eventos mediante callbacks HTTPS. El `secret` de firma se devuelve **una sola vez** en esta respuesta y nunca más — guárdalo de forma segura. - [Elimina un webhook endpoint](https://docs.factuarea.com/es/api-reference/webhooks/public-api.v1.webhook_endpoints.delete): Elimina un webhook endpoint. Las entregas en curso no se cancelan, pero no se encolan entregas nuevas. - [Lista las entregas de webhook](https://docs.factuarea.com/es/api-reference/webhooks/public-api.v1.webhook_endpoints.deliveries.list): Lista los intentos de entrega de un webhook endpoint con paginación por cursor. Cada entrega captura el estado de la respuesta HTTP, el cuerpo (truncado), la duración y la programación de reintentos. - [Reenviar entrega de webhook](https://docs.factuarea.com/es/api-reference/webhooks/public-api.v1.webhook_endpoints.deliveries.replay): Reencola una entrega de webhook. Se crea un nuevo intento de entrega (con `attempt: 1`) para el mismo par evento/endpoint. - [Recupera la entrega del webhook](https://docs.factuarea.com/es/api-reference/webhooks/public-api.v1.webhook_endpoints.deliveries.show): Obtiene un único intento de entrega por su `uuid`, incluyendo el payload completo del evento que se entregó. - [Listar todos los webhook endpoints](https://docs.factuarea.com/es/api-reference/webhooks/public-api.v1.webhook_endpoints.list): Lista tus webhook endpoints con paginación por cursor. - [Hacer ping al webhook endpoint](https://docs.factuarea.com/es/api-reference/webhooks/public-api.v1.webhook_endpoints.ping): Envía un evento de prueba (`webhook.ping`) al endpoint para verificar que es accesible y que el handshake de firma funciona. La entrega sintética aparece en `GET /webhook_endpoints/{webhook_endpoint}/deliveries`. - [Rota el secreto del webhook](https://docs.factuarea.com/es/api-reference/webhooks/public-api.v1.webhook_endpoints.rotate_secret): Rota el secreto de firma de un webhook endpoint. El nuevo secreto se devuelve **una sola vez** en esta respuesta. El secreto anterior sigue siendo válido durante un periodo de gracia de 24 horas (ver `previous_secret_valid_until`) para permitir una rotación sin tiempo de inactividad. - [Obtener un webhook endpoint](https://docs.factuarea.com/es/api-reference/webhooks/public-api.v1.webhook_endpoints.show): Obtiene un webhook endpoint por su `uuid`. El secreto de firma nunca se expone en esta representación. - [Enviar un evento de prueba](https://docs.factuarea.com/es/api-reference/webhooks/public-api.v1.webhook_endpoints.test_event): Lanza una entrega de prueba de un tipo de evento real del catálogo a este endpoint, marcada `test: true` en el envoltorio entregado. A diferencia de `ping` (un `webhook.ping` sintético), esto registra un `Event` real (visible en `GET /events`) y encola un `WebhookDelivery` firmado y con reintentos. Opcionalmente pasa `type` para elegir qué evento suscrito simular. La entrega llega solo a este endpoint. - [Actualizar un webhook endpoint](https://docs.factuarea.com/es/api-reference/webhooks/public-api.v1.webhook_endpoints.update): Actualiza un webhook endpoint (URL, descripción, eventos habilitados, estado, lista de acceso de IP). - [Archivar un horario de trabajo](https://docs.factuarea.com/es/api-reference/work-schedules/public-api.v1.work_schedules.archive): Archiva un horario de trabajo (transición `active` → `archived`), retirándolo del uso pero conservándolo. Sin cuerpo de la petición. Devuelve 422 si ya está archivado. Reversible mediante desarchivar. - [Asignar un horario a un empleado](https://docs.factuarea.com/es/api-reference/work-schedules/public-api.v1.work_schedules.assign): Asigna el horario de trabajo a un empleado con una fecha de inicio de vigencia. `employee_id` (UUID v7, debe pertenecer a tu empresa) y `effective_from` (`Y-m-d`) son obligatorios. Asignar cierra la asignación abierta anterior del empleado y abre la nueva (un empleado tiene como máximo una asignación abierta; se conserva el histórico). Un empleado desconocido devuelve 422 `assigned_employee_not_found`; un horario desconocido devuelve 404. Devuelve la asignación creada. - [Listar las asignaciones de un horario](https://docs.factuarea.com/es/api-reference/work-schedules/public-api.v1.work_schedules.assignments): Lista los empleados con una asignación abierta (`effective_to` = null) a este horario de trabajo, como una lista plana bajo `{ "data": [ … ] }`. - [Crear un horario de trabajo](https://docs.factuarea.com/es/api-reference/work-schedules/public-api.v1.work_schedules.create): Crea un horario de trabajo semanal para la empresa autenticada (resuelta desde la API key, nunca desde el payload). `name` y `week_pattern` son obligatorios; `mode` toma por defecto `validated`. El `week_pattern` es una lista de días de la semana (ISO 8601 1..7) cada uno con sus franjas horarias `HH:MM` ordenadas y sin solaparse (un `ranges` vacío significa día de descanso). Devuelve el horario creado con su `id` generado (UUID v7); `weekly_hours` se deriva del patrón. - [Obtener el horario actual de un empleado](https://docs.factuarea.com/es/api-reference/work-schedules/public-api.v1.work_schedules.employee_schedule): Resuelve el horario de trabajo actualmente en vigor (hoy) para un empleado por su `id` (UUID v7). Devuelve 404 `schedule_assignment_not_found` cuando el empleado no tiene horario en vigor (o pertenece a otra empresa). El resultado es el horario resuelto (`id` = UUID v7 del horario), no la asignación. - [Listar todos los horarios de trabajo](https://docs.factuarea.com/es/api-reference/work-schedules/public-api.v1.work_schedules.list): Lista los horarios de trabajo semanales de tu empresa con paginación por cursor. Admite filtrar por `status` (`active`/`archived`) y `mode` (`validated`/`real_clocking`), más una `search` de texto libre sobre el nombre del horario. - [Obtener un horario de trabajo](https://docs.factuarea.com/es/api-reference/work-schedules/public-api.v1.work_schedules.show): Obtén un único horario de trabajo por su `id` (UUID v7). Un horario perteneciente a otra empresa devuelve 404 `work_schedule_not_found` (anti-enumeración). - [Obtener las estadísticas de horarios de trabajo](https://docs.factuarea.com/es/api-reference/work-schedules/public-api.v1.work_schedules.stats): KPIs agregados de tus horarios de trabajo: total, número de activos y archivados, un desglose por modo (`validated`/`real_clocking`) y el número de empleados con un horario asignado. Se devuelve como `{ "data": … }`. - [Desarchivar un horario de trabajo](https://docs.factuarea.com/es/api-reference/work-schedules/public-api.v1.work_schedules.unarchive): Desarchiva un horario de trabajo (transición `archived` → `active`), devolviéndolo al uso. Sin cuerpo de la petición. Devuelve 422 si ya está activo. - [Desasignar un horario de un empleado](https://docs.factuarea.com/es/api-reference/work-schedules/public-api.v1.work_schedules.unassign): Cierra la asignación abierta del empleado a este horario. `employee_id` (UUID v7) es obligatorio; `effective_to` (`Y-m-d`) es opcional y toma por defecto la fecha de hoy. Devuelve 404 cuando no hay asignación abierta. Responde 204 No Content. - [Actualizar un horario de trabajo](https://docs.factuarea.com/es/api-reference/work-schedules/public-api.v1.work_schedules.update): Reemplaza por completo un horario de trabajo: `name`, `mode` y el `week_pattern` completo son obligatorios (no hay actualización parcial del patrón). `weekly_hours` se recomputa a partir del nuevo patrón. Devuelve el horario actualizado. - [Todos los error codes](https://docs.factuarea.com/es/guides/errors/all): Referencia completa de cada error code de la API pública, agrupado por bounded context, con su estado HTTP y type. - [Gestión de errores](https://docs.factuarea.com/es/guides/errors): Envoltorio de error normalizado, catálogo de type y code con anclas estables, y estrategia de reintentos. - [Consulta el catálogo fiscal](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.tax-catalog.show): Devuelve, en un solo documento, el conocimiento fiscal español que necesitas para construir un formulario de facturación conforme: regímenes de imposición indirecta (IVA, IGIC, IPSI) con sus tipos legales y su código L1 de VeriFactu, regímenes de operación a nivel de cabecera con la mención legal que exige cada uno, causas de exención con su código AEAT, su mención legal y su artículo de la Ley del IVA, los tipos de retención de IRPF del sistema y la matriz cerrada de pares legales de IVA/recargo de equivalencia. Sustituye a la tabla hardcodeada que toda integración acaba manteniendo a mano. El catálogo no lleva ningún dato de la empresa autenticada: dos empresas distintas reciben cuerpos idénticos byte a byte para el mismo idioma, y `retention_rates` nunca incluye los impuestos personalizados que una empresa crea con `POST /v1/taxes`. Los tipos de retención se publican en POSITIVO, así que aplícalos como una deducción sobre la base imponible. Este es el catálogo de lo que la plataforma admite, NO una lista normativa exhaustiva de todos los regímenes, exenciones o tipos de retención que define la ley española. Úsalo para saber qué puedes enviar a esta API; no lo leas como asesoramiento fiscal ni como sustituto de la legislación. Cada entrada lleva su `label` (y, en los dos bloques normativos, su `description`) en español, inglés y catalán a la vez. `Accept-Language` solo elige el idioma que se informa en `primary_language`; nunca filtra el payload, así que con un documento cacheado basta para pintar un selector multiidioma. La respuesta es cacheable: lleva `ETag` y un `Cache-Control` público, y devolver el validador en `If-None-Match` responde un 304 sin cuerpo. Dos idiomas producen dos `ETag` distintos, porque el idioma negociado viaja dentro del cuerpo. - [Listar impuestos activos](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.active): Devuelve los impuestos activos disponibles para tu empresa, combinando los predeterminados del sistema más las definiciones específicas de la empresa. - [Lista los impuestos filtrados por tipo](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.by_type): Devuelve los impuestos filtrados por categoría mediante el query param type (vat, retention, surcharge, other). Por defecto vat cuando se omite. - [Calcular un impuesto sobre un importe base](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.calculate): Aplica el impuesto referenciado a un importe base y devuelve el desglose: base, tax_rate, tax_amount, total_amount y el objeto de impuesto completo. - [Calcular totales para un conjunto de líneas](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.calculate_totals): Calcula la base imponible, el IVA, el recargo, la retención y el total general para un array de líneas con cantidad, precio, descuento y tipos impositivos. Devuelve los totales del documento más el desglose por línea. - [Crea un impuesto](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.create): Registra un nuevo impuesto con nombre, código único, tipo (vat, retention, surcharge u other), tasa y ámbito (sale, purchase o both). El código de país ISO-2 es obligatorio. - [Obtener los impuestos por defecto para un tipo de documento](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.defaults): Devuelve los impuestos predeterminados configurados (vat, retention, surcharge) para el tipo de documento indicado, en el ámbito de tu empresa. Cada espacio es un Tax o null cuando no hay predeterminado configurado. - [Elimina un impuesto](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.delete): Elimina un impuesto. Falla con 409 si el impuesto está referenciado por documentos existentes. Los impuestos de sistema (is_system=true) no se pueden eliminar. - [Lista los impuestos aplicables a las compras](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.for_purchases): Devuelve los impuestos disponibles para documentos de compra (facturas de proveedor). - [Lista los impuestos aplicables a las ventas](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.for_sales): Devuelve los impuestos disponibles para documentos de venta (facturas, presupuestos, proformas, albaranes). - [Comprobar si un impuesto está en uso](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.is_in_use): Devuelve si el impuesto está referenciado por documentos existentes. Útil para comprobaciones de borrado seguro antes de llamar a DELETE. - [Listar todos los impuestos](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.list): Lista los tipos impositivos disponibles para tu empresa (IVA, IRPF, recargo españoles, etc.). - [Marca un impuesto como predeterminado para su tipo](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.set_default): Promueve un impuesto al predeterminado a nivel de sistema para su categoría (vat, retention o surcharge). Si otro impuesto era el predeterminado para el mismo tipo, se degrada automáticamente. - [Establece el impuesto predeterminado para un tipo de documento](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.set_default_for_document): Asigna un impuesto como predeterminado para un tipo de documento específico (invoice, quote, proforma, delivery_note, purchase_invoice, recurring_invoice). - [Obtener un impuesto](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.show): Obtiene un tipo impositivo por su `uuid`. - [Obtener estadísticas de impuestos](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.stats): KPIs agregados de los tipos impositivos disponibles para tu empresa: número total de impuestos, número de activos y desglose por tipo (vat, retention, surcharge, other). Devuelto como `{ "data": TaxStats }`. - [Alternar el estado activo del impuesto](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.toggle): Cambia un impuesto entre activo e inactivo. Los impuestos inactivos se ocultan de los selectores pero siguen disponibles para documentos ya emitidos. - [Actualizar un impuesto](https://docs.factuarea.com/es/api-reference/taxes/public-api.v1.taxes.update): Actualización parcial de un impuesto: name, code, rate, applies_to, country y description. Los impuestos del sistema (is_system=true) no son editables. - [FAQ](https://docs.factuarea.com/ca/faq): Respostes ràpides a les preguntes que més sorgeixen en integrar l'API pública de Factuarea — claus, mode de prova, diners, dates, idempotència i límits de peticions. - [API de Factuarea](https://docs.factuarea.com/ca): L'API REST de Factuarea per automatitzar el teu SaaS de facturació multi-tenant per a empreses espanyoles. - [Preus i límits de l'API](https://docs.factuarea.com/ca/pricing): Què costa l'API, quin tier atorga cada pla i els topalls per tier de peticions, API keys i endpoints de webhook. - [Suport](https://docs.factuarea.com/ca/support): Com contactar amb l'equip de l'API de Factuarea, què incloure en reportar un problema, com funciona l'accés a l'API, la pàgina d'estat i el changelog. - [Launch](https://docs.factuarea.com/ca/changelog/launch): El llançament de la plataforma pública de Factuarea — l'API REST v1 (413 operacions en 37 recursos), els SDKs oficials de TypeScript i PHP, el CLI, el servidor MCP per a agents d'IA, el compliment fiscal espanyol, els pagaments i l'operativa d'empreses gestionades, tot amb un sandbox de prova. - [Agents i scripting](https://docs.factuarea.com/ca/cli/agents): El contracte agent-first del CLI factuarea — JSON estable per stdout, errors estructurats per stderr, exit codes semàntics, el manifest commands --json, scope-check local i confirmació tipada d'operacions irreversibles. - [Devloop](https://docs.factuarea.com/ca/cli/devloop): Prova els webhooks de Factuarea en local sense desplegar ni ngrok — factuarea listen reenvia els esdeveniments del teu compte a localhost amb un cos signat, factuarea trigger produeix esdeveniments reals en sandbox. - [Resum de la CLI](https://docs.factuarea.com/ca/cli): Instal·la i autentica el CLI oficial factuarea — maneja l'API REST v1 des del teu terminal amb brew, npm o un instal·lador curl. Agent-first, inspirat en Stripe. - [Ús](https://docs.factuarea.com/ca/cli/usage): L'arbre de comandes de factuarea — list, show, create, accions de domini, descàrregues binàries, pujades multipart, l'escape hatch genèric api i el manifest commands --json. - [Absències](https://docs.factuarea.com/ca/guides/absences): Configura tipus i polítiques d'absència, gestiona les sol·licituds i llegeix els saldos i el calendari d'equip sobre l'API v1. - [Personalització del compte](https://docs.factuarea.com/ca/guides/account-personalization): Fixa l'idioma d'emissió de factures, la plantilla PDF i el color d'accent del teu compte — i llegeix-los des del recurs Account. - [Actuar en nom d'una filla](https://docs.factuarea.com/ca/guides/acting-on-behalf): Maneja qualsevol empresa filla des d'una sola master key amb el header X-Active-Profile — resolució del perfil, el guard de propietat i com els scopes es mantenen fixos. - [Imports i dates](https://docs.factuarea.com/ca/guides/amounts-and-dates): Com representa l'API els diners (EUR, dos decimals), les dates (YYYY-MM-DD), els timestamps (ISO-8601) i la zona horària Europe/Madrid emprada per al reinici de quotes. - [Anul·lar o rectificar](https://docs.factuarea.com/ca/guides/annul-vs-correct): Quatre operacions semblen «desfer una factura» i només una és correcta en cada cas — eliminar, cancel·lar, anul·lar i rectificar. Si tries malament, perds un document fiscal o presentes una declaració que no pretenies. - [API keys (autoservei)](https://docs.factuarea.com/ca/guides/api-keys): Llista, crea, rota i revoca les teves API keys des de l'API v1 — el secret es mostra un cop, els environments són live/test i el tier el deriva el teu pla. - [Autenticació](https://docs.factuarea.com/ca/guides/authentication): API keys amb prefixos fact_live_ / fact_test_, scopes granulars, rotació amb període de gràcia i llista d'accés per IP. - [Operacions en lot](https://docs.factuarea.com/ca/guides/bulk-operations): Contracte d'èxit parcial per a endpoints bulk — total, successful, failed i una llista failures per fila. - [Verificació censal AEAT](https://docs.factuarea.com/ca/guides/census-verification): Contrasta el parell raó social + NIF de la teva empresa — i el dels teus clients — contra el cens de l'AEAT abans d'emetre factures VeriFactu — estats deterministes, NIFs màgics del sandbox i comportament fail-open. - [API keys d'empreses filles](https://docs.factuarea.com/ca/guides/child-api-keys): Emet, rota i revoca API keys acotades a una sola empresa filla, derivant els seus scopes de la key que crida — els endpoints api_keys sota una empresa gestionada. - [Empreses gestionades](https://docs.factuarea.com/ca/guides/companies): Dona d'alta, aprovisiona i opera empreses filles sota el teu tenant mestre — el model de gestoria des de l'API v1, amb cobrament per-seat i un cicle de vida activa/desactivada. - [Factures rectificatives](https://docs.factuarea.com/ca/guides/corrective-invoices): De R1 a R5, substitució davant diferències, i com es construeixen les línies d'una rectificativa — les quatre decisions que determinen el que reben de debò l'AEAT i la declaració d'IVA. - [Suplerts](https://docs.factuarea.com/ca/guides/disbursements): Els diners que pagues per compte del teu client —taxes judicials, aranzels registrals, visats— no són ingrés teu. Com facturar-los perquè quedin fora de la teva base imposable, del teu IVA i de la teva declaració anual d'operacions amb tercers. - [Facturació de places d'empleat](https://docs.factuarea.com/ca/guides/employee-seats): L'add-on de facturació per empleat — una subscripció mensual dedicada el nombre de places de la qual segueix els teus empleats actius, amb una plaça pagada que cobreix tot el període. - [Esdeveniments](https://docs.factuarea.com/ca/guides/events): Objectes event de només lectura amb un id opac. Consulta històrica via l'API i entrega per webhook. - [Exportació i importació](https://docs.factuarea.com/ca/guides/export-and-import): Exporta factures a un full de càlcul Excel/CSV (SUMMARY o ITEMS, amb límit de 5000) i importa clients des d'un CSV amb previsualització dry-run, mapatge de columnes, plantilla descarregable i partial-success. - [Facturació FACe (B2G)](https://docs.factuarea.com/ca/guides/face-invoicing): Envia factures FacturaE 3.2.2 a FACe — codis DIR3, XML signat XAdES-EPES, estats de tramitació, anul·lació, simulació en sandbox i l'scope facturae:write. - [Receptari fiscal](https://docs.factuarea.com/ca/guides/fiscal-cookbook): Sis receptes d'extrem a extrem — emetre i esperar l'acceptació de l'AEAT, corregir un import, substituir factures simplificades, repercutir un suplert, facturar fora de la UE i reparar un registre rebutjat. - [Exemples fiscals de factura](https://docs.factuarea.com/ca/guides/fiscal-invoice-examples): Els 21 escenaris fiscals espanyols de facturació, quins quatre d'ells es publiquen com a exemples de request llestos per enviar a la Referència de l'API i un exemple de rectificativa per cada codi R de l'AEAT (R1–R5). - [Glossari](https://docs.factuarea.com/ca/guides/glossary): Termes fiscals i de domini espanyols usats a tota l'API de Factuarea — NIF, VeriFactu, AEAT, FacturaE, Modelo 303/347, sèries, rectificativa, huella, CSV i més. - [Idempotència](https://docs.factuarea.com/ca/guides/idempotency): Header Idempotency-Key amb TTL de 24 h. Reintenta un POST sense duplicar recursos. - [Clients internacionals](https://docs.factuarea.com/ca/guides/international-customers): Identificar un destinatari no espanyol amb el catàleg d'identificació alternativa de l'AEAT, i el mapa d'escenari a qualificació per a lliuraments intracomunitaris, inversió del subjecte passiu, exportacions i vendes per finestreta única. - [Classificació fiscal i exempcions per línia](https://docs.factuarea.com/ca/guides/line-tax-classification-and-exemptions): E1–E6 i N1–N2 per línia, la retenció d'IRPF que resta, i la matriu tancada de parells legals d'IVA i recàrrec d'equivalència — els quatre camps que decideixen què diu el desglossament que arriba a l'AEAT. - [Migració des de Holded](https://docs.factuarea.com/ca/guides/migration-from-holded): Mapeig de recursos Holded → Factuarea, nomenclatura, endpoints equivalents i script en Python. - [Tancament mensual del registre](https://docs.factuarea.com/ca/guides/monthly-time-close): Congela el registre de jornada mensual inalterable, segella'l amb una signatura digital i exporta l'informe o el fitxer d'incidències per a nòmines. - [Paginació](https://docs.factuarea.com/ca/guides/pagination): Paginació per cursor amb starting_after i ending_before. Sense ?page=, semàntica a l'estil Stripe. - [Registrar pagaments](https://docs.factuarea.com/ca/guides/payments): Registra pagaments parcials contra factures i factures de compra, i consulta el saldo en curs des del ledger. - [Presència](https://docs.factuarea.com/ca/guides/presence): Consulta qui treballa ara mateix i qui és a l'oficina o en remot — una vista derivada i de només lectura sobre el ledger de jornada, els horaris i la plantilla. - [Inici ràpid](https://docs.factuarea.com/ca/guides/quickstart): La teva primera factura en 5 minuts — verifica la teva key, aconsegueix una sèrie i un impost, crea un client, emet una factura i envia-la. Una sola seqüència de copiar i enganxar contra una key fact_test_. - [Límits de peticions](https://docs.factuarea.com/ca/guides/rate-limits): Quotes per minut i mensuals segons el tier. Capçaleres X-RateLimit-* i back-off recomanat. - [Factures recurrents](https://docs.factuarea.com/ca/guides/recurring-invoices): Omet un cicle, crea una recurrència des d'una factura, configura l'enviament automàtic, previsualitza el pròxim document i defineix camps fiscals per línia. - [Claus de règim](https://docs.factuarea.com/ca/guides/regime-keys): A la facturació espanyola s'anomenen «règim» tres coses diferents. Aquesta pàgina aclareix quina fixes tu, quina es deriva i quin és el catàleg tancat de disset codis AEAT que pot declarar una línia. - [Abast i limitacions](https://docs.factuarea.com/ca/guides/scope-and-limitations): El que l'API de Factuarea no fa a propòsit, el que encara no fa, i la manera equivalent de resoldre cada cas — més quatre capacitats que pots donar per absents i no ho estan. - [Scopes i irreversibilitat](https://docs.factuarea.com/ca/guides/scopes-and-irreversibility): Com llegir el scope requerit i la irreversibilitat de cada endpoint des de l'especificació OpenAPI — les extensions x-required-scope i x-irreversible — i el catàleg d'operacions irreversibles. - [Factures simplificades o completes](https://docs.factuarea.com/ca/guides/simplified-vs-full-invoices): F1, F2 i F3 — quan és legal una factura simplificada, el topall de 3.000 € que sí que s'aplica de debò, i la substitució en una sola crida que converteix un lot de tiquets en una factura completa. - [Etiquetes i camps personalitzats](https://docs.factuarea.com/ca/guides/tags-and-custom-fields): Classifica documents amb tags i adjunta custom_fields tipats. Filtra llistats per tag. En què es diferencien de metadata. - [Impostos territorials — IVA, IGIC i IPSI](https://docs.factuarea.com/ca/guides/territorial-taxes): Espanya té tres impostos indirectes, no un. Quins tipus són legals a cadascun, com es tria el règim per document, què declara el desglossament de l'AEAT i per què l'IGIC i l'IPSI no apareixen mai a la declaració trimestral d'IVA. - [Mode de prova i sandbox](https://docs.factuarea.com/ca/guides/test-mode): Crea la teva integració de forma segura amb claus fact_test_ — dades de sandbox aïllades i AEAT, email i webhooks desactivats. - [Fitxatges](https://docs.factuarea.com/ca/guides/time-clock): Fitxar entrada i sortida, pauses, fitxatges retroactius i el flux de correccions sobre el ledger de jornada de només apèndix. - [Alta automàtica a VeriFactu](https://docs.factuarea.com/ca/guides/verifactu-auto-submission): No hi ha cap botó d'«enviar a l'AEAT». L'alta es crea quan la factura surt de draft — aquesta és la llista de comportes que decideixen si passa, i les úniques palanques manuals que existeixen després. - [Estats d'enviament VeriFactu](https://docs.factuarea.com/ca/guides/verifactu-submission-states): El cicle de vida d'un registre de facturació VeriFactu — pending, submitted, accepted, rejected, error —, què signifiquen el CSV i la huella, com funciona el pressupost de reintents i quan reintentar en lloc d'esmenar. - [Esmena de registres VeriFactu](https://docs.factuarea.com/ca/guides/verifactu-subsanacion): Corregeix i reenvia registres de facturació VeriFactu rebutjats per l'AEAT — quan aplica l'esmena (subsanación), quan necessites una anul·lació o una rectificativa, i el flux exacte de l'API. - [Versionat](https://docs.factuarea.com/ca/guides/versioning): Política de versionat pla /v1 amb la capçalera Factuarea-Version. Compromisos d'estabilitat i deprecació. - [Webhooks](https://docs.factuarea.com/ca/guides/webhooks): Notificacions POST signades amb HMAC SHA256. Verificació, reintents exponencials i rotació de secret. - [Horaris de treball](https://docs.factuarea.com/ca/guides/work-schedules): Defineix patrons setmanals de treball, el seu mode de compliment i les assignacions efectiu-datades a empleats sobre l'API v1. - [Visió general del control horari](https://docs.factuarea.com/ca/guides/workforce-overview): El sistema de control horari sobre l'API v1 — el registre de jornada inalterable (RD-llei 8/2019), el rol d'empleat només-portal, l'add-on per plaça i els vuit dominis que el componen. - [Plugin de Claude Code](https://docs.factuarea.com/ca/mcp/claude-code-plugin): Dos plugins oficials en un mateix marketplace — factuarea-mcp connecta Claude Code al servidor MCP de Factuarea, i factuarea-api porta cinc skills per construir la mateixa integració. - [Connectar un client](https://docs.factuarea.com/ca/mcp/connect): Connecta Claude Code, Claude Desktop, el MCP Inspector o qualsevol client MCP al servidor MCP de Factuarea — amb OAuth 2.1 o una API key, i en mode de prova. - [Errors i límits de peticions](https://docs.factuarea.com/ca/mcp/errors): Formes d'error JSON-RPC mapejades des del contracte v1, la taula completa de codis i throttling per token / per pla amb Retry-After. - [Resum de MCP](https://docs.factuarea.com/ca/mcp): Connecta agents d'IA a Factuarea sobre el Model Context Protocol — 391 tools de facturació, catàleg, compliment, control horari i webhooks, amb autenticació OAuth 2.1 i API key. - [Scopes i permisos](https://docs.factuarea.com/ca/mcp/scopes): El catàleg de scopes del consentiment OAuth, com es mapeja als scopes detallats que apliquen les tools, el super-scope i el gating per pla/mòdul. - [Catàleg de tools](https://docs.factuarea.com/ca/mcp/tools): Les 391 tools del MCP de Factuarea agrupades per domini, amb el scope que requereix cadascuna i la seva categoria de límit de peticions. - [Integració GoCardless](https://docs.factuarea.com/ca/payments/gocardless): Estat de la integració amb GoCardless — encara no alliberada, què existeix ja darrere del flag, i la superfície v1 i MCP exacta que apareix el dia que s'encén. - [Safata d'esdeveniments d'integració](https://docs.factuarea.com/ca/payments/integration-events-inbox): Per què un cobrament no va acabar en factura — els motius de descart tipats, quins t'avisen, quins aparquen l'esdeveniment perquè el puguis reprocessar, i com funciona la finestra de retenció de 30 dies. - [Conciliar amb la metadata de sistema](https://docs.factuarea.com/ca/payments/metadata-reconciliation): Les claus de metadata que Factuarea escriu a les factures auto-emeses des d'un cicle de subscripció de Stripe, i com fer servir el filtre de metadata per treure totes les factures d'una subscripció o d'un període de facturació. - [Integració MONEI](https://docs.factuarea.com/ca/payments/monei): Estat de la integració amb MONEI — encara no alliberada, què existeix ja darrere del flag, per què no té recurs de mandats, i la superfície v1 i MCP exacta que apareix en alliberar-se. - [Payouts i conciliació bancària](https://docs.factuarea.com/ca/payments/payouts-reconciliation): Com Factuarea ingereix els payouts de Stripe, els vincula amb els cobraments que agrupen, els concilia contra el teu extracte Norma 43 i emet l'esdeveniment payout.reconciled. - [Auto-facturació amb Stripe](https://docs.factuarea.com/ca/payments/stripe-autoinvoicing): Emet factures automàticament des dels cobraments de Stripe Connect — captura de NIF al Checkout, llindar de factura simplificada, exigir NIF i quins cobraments es deriven a revisió manual. - [account_not_found](https://docs.factuarea.com/ca/errors/account_not_found): No es va poder resoldre el compte associat a la clau, cosa que sol voler dir que la clau ja no apunta a una empresa viva. - [addon_not_active](https://docs.factuarea.com/ca/errors/addon_not_active): La funcionalitat pertany a un add-on que ara mateix no està actiu per a l'empresa. - [addon_required](https://docs.factuarea.com/ca/errors/addon_required): Crear endpoints de webhook pertany a l'add-on Developer API, i l'empresa no el té actiu: el nivell gratuït permet zero endpoints. - [alta_record_not_found](https://docs.factuarea.com/ca/errors/alta_record_not_found): La factura no té registre d'alta, així que l'operació que en depèn no té sobre què treballar. - [alternative_id_type_invalid](https://docs.factuarea.com/ca/errors/alternative_id_type_invalid): El tipus d'identificador alternatiu queda fora del catàleg `nif_iva`, `passport`, `country_id`, `residence_certificate`, `other_document`, `not_registered`. - [anulacion_record_already_exists](https://docs.factuarea.com/ca/errors/anulacion_record_already_exists): La factura ja té un registre d'anul·lació a la cadena, i l'anul·lació es declara una sola vegada. - [api_key_already_revoked](https://docs.factuarea.com/ca/errors/api_key_already_revoked): La clau ja estava revocada, i una clau revocada no admet més operacions: la revocació és terminal. - [api_key_expired](https://docs.factuarea.com/ca/errors/api_key_expired): La clau va passar la seva data de caducitat. - [api_key_not_found](https://docs.factuarea.com/ca/errors/api_key_not_found): L'identificador no correspon a cap clau API de l'empresa autenticada. - [api_key_revoked](https://docs.factuarea.com/ca/errors/api_key_revoked): La clau va ser revocada, i una clau revocada no torna a autenticar mai: revocar és justament la manera de tallar una credencial filtrada. - [api_version_invalid_format](https://docs.factuarea.com/ca/errors/api_version_invalid_format): La versió de payload de l'endpoint no és una data `YYYY-MM-DD`. - [api_version_unsupported](https://docs.factuarea.com/ca/errors/api_version_unsupported): La versió de payload està ben formada però no és entre les que serveix la plataforma. - [attachment_invalid_filename](https://docs.factuarea.com/ca/errors/attachment_invalid_filename): El nom del fitxer no és utilitzable: és buit, porta components de ruta, o supera els 200 caràcters. - [attachment_mime_not_allowed](https://docs.factuarea.com/ca/errors/attachment_mime_not_allowed): El tipus de fitxer queda fora del conjunt admès: PDF, PNG, JPEG, XML i HTML. - [attachment_missing](https://docs.factuarea.com/ca/errors/attachment_missing): La factura de compra existeix però no té fitxer adjunt, així que no hi ha res a descarregar. - [attachment_too_large](https://docs.factuarea.com/ca/errors/attachment_too_large): El fitxer supera la mida màxima permesa per a un adjunt de document. - [business_rule_violation](https://docs.factuarea.com/ca/errors/business_rule_violation): Una invariant del domini va rebutjar l'operació. Aquest codi indica la família; `error.subcode` anomena la regla concreta i `error.message` l'explica. - [cannot_archive_last_default_series](https://docs.factuarea.com/ca/errors/cannot_archive_last_default_series): La sèrie és l'única activa del seu tipus de document. Arxivar-la deixaria l'empresa sense numeració disponible i congelaria aquest tipus de document. - [cannot_attach_to_cancelled_purchase_invoice](https://docs.factuarea.com/ca/errors/cannot_attach_to_cancelled_purchase_invoice): La factura està cancel·lada, i adjuntar documents a un registre cancel·lat alteraria documentació ja tancada. - [cannot_have_both_tax_id_and_alternative_id](https://docs.factuarea.com/ca/errors/cannot_have_both_tax_id_and_alternative_id): El client envia `tax_id` i un identificador alternatiu alhora. La identitat fiscal és una: l'identificador alternatiu existeix precisament per a parts sense NIF espanyol. - [census_requires_tax_id](https://docs.factuarea.com/ca/errors/census_requires_tax_id): La verificació censal contrasta el parell nom + NIF contra l'AEAT, i en falta un dels dos. - [certificate_expired](https://docs.factuarea.com/ca/errors/certificate_expired): El certificat està fora de la seva finestra de validesa: ha caducat, o encara no és vàlid. - [certificate_nif_mismatch](https://docs.factuarea.com/ca/errors/certificate_nif_mismatch): El NIF del titular del certificat no coincideix amb el de l'empresa. Els registres AEAT es signen en nom de l'empresa, així que tots dos han de ser el mateix. - [certificate_not_found](https://docs.factuarea.com/ca/errors/certificate_not_found): L'empresa no té cap certificat FNMT que correspongui a l'identificador, o no en té cap de pujat. - [certificate_too_large](https://docs.factuarea.com/ca/errors/certificate_too_large): El fitxer supera el límit de 100 KB, quan un certificat FNMT real pesa uns pocs kilobytes. - [client_has_documents](https://docs.factuarea.com/ca/errors/client_has_documents): El client està referenciat per documents emesos. Esborrar-lo deixaria factures, pressupostos o albarans sense la part a qui es van emetre, i els registres fiscals han de seguir sent traçables. - [client_import_too_large](https://docs.factuarea.com/ca/errors/client_import_too_large): El CSV supera el límit de files que admet la importació síncrona, ja que el fitxer sencer es processa dins de la mateixa petició. - [client_not_found](https://docs.factuarea.com/ca/errors/client_not_found): L'identificador no resol a cap client de l'empresa autenticada. - [client_requires_tax_identity](https://docs.factuarea.com/ca/errors/client_requires_tax_identity): El client no té identitat fiscal: ni `tax_id` ni identificador alternatiu, i no es pot emetre una factura a una part sense identificar. - [clock_drift_exceeded](https://docs.factuarea.com/ca/errors/clock_drift_exceeded): El rellotge del servidor es va desviar de l'NTP per sobre del marge permès. La marca de temps de generació entra a l'empremta AEAT, així que un rellotge desincronitzat produiria registres que l'AEAT rebutja. - [company_inactive](https://docs.factuarea.com/ca/errors/company_inactive): El perfil que indica `X-Active-Profile` és una de les teves empreses gestionades, però està desactivada i no es pot operar fins que torni a estar activa. - [conflicting_pagination_params](https://docs.factuarea.com/ca/errors/conflicting_pagination_params): `starting_after` i `ending_before` van viatjar a la mateixa petició. Recorren la col·lecció en sentits oposats, així que només se'n pot aplicar un. - [corrective_invoice_inanulable](https://docs.factuarea.com/ca/errors/corrective_invoice_inanulable): La factura és al seu torn una rectificativa, i les rectificatives no s'anul·len mai: la cadena de correcció ha de seguir sent auditable de punta a punta. - [custom_header_blocklisted](https://docs.factuarea.com/ca/errors/custom_header_blocklisted): Una de les capçaleres personalitzades està reservada: la gestiona la capa HTTP (`host`, `content-type`, `content-length`, `user-agent`), l'envia Factuarea com a part del contracte signat (`factuarea-*`), o pertany al proxy (`x-forwarded-*`). - [custom_header_value_too_long](https://docs.factuarea.com/ca/errors/custom_header_value_too_long): El valor d'una capçalera personalitzada supera els 1024 caràcters. - [custom_tax_creation_disabled](https://docs.factuarea.com/ca/errors/custom_tax_creation_disabled): La creació d'impostos personalitzats està deshabilitada per a aquesta empresa. - [declaracion_already_exists](https://docs.factuarea.com/ca/errors/declaracion_already_exists): L'empresa ja té presentada la declaració responsable del SIF d'aquest període. - [declaracion_not_found](https://docs.factuarea.com/ca/errors/declaracion_not_found): L'empresa no té presentada la declaració responsable del SIF del període sol·licitat. - [delivery_note_not_found](https://docs.factuarea.com/ca/errors/delivery_note_not_found): L'identificador no resol a cap albarà de l'empresa autenticada. - [delivery_note_section_not_editable_in_status](https://docs.factuarea.com/ca/errors/delivery_note_section_not_editable_in_status): La secció logística —transportista, vehicle, conductor— està congelada perquè l'albarà ja està lliurat, facturat o cancel·lat. - [dependency_unavailable](https://docs.factuarea.com/ca/errors/dependency_unavailable): Un servei extern del qual depèn l'operació no va respondre a temps. - [direct_debit_requires_default_bank_account](https://docs.factuarea.com/ca/errors/direct_debit_requires_default_bank_account): Es va triar domiciliació bancària com a mètode de pagament, però el client no té compte bancari per defecte on carregar. - [document_type_required_for_ambiguous_code](https://docs.factuarea.com/ca/errors/document_type_required_for_ambiguous_code): Aquest codi de sèrie existeix per a més d'un tipus de document, així que per si sol no identifica una única sèrie. - [driver_tax_id_requires_name](https://docs.factuarea.com/ca/errors/driver_tax_id_requires_name): Es va enviar el NIF del conductor sense el seu nom, i un identificador sense nom no identifica ningú al document de lliurament. - [duplicate_tax_default_for_document_type](https://docs.factuarea.com/ca/errors/duplicate_tax_default_for_document_type): Ja hi ha un altre impost del mateix tipus marcat com a default per a aquest tipus de document, i el parell (tipus d'impost, tipus de document) admet un únic default. - [employee_seat_charge_failed](https://docs.factuarea.com/ca/errors/employee_seat_charge_failed): El cobrament immediat del prorrateig del seient d'empleat va ser rebutjat: la targeta es va denegar, necessita autenticació, o el proveïdor de pagament era inaccessible. L'empleat no s'activa si el seient no es cobra. - [employee_seat_payment_method_required](https://docs.factuarea.com/ca/errors/employee_seat_payment_method_required): Donar d'alta o reactivar un empleat cobra un seient immediatament, i l'empresa opera en mode real sense mètode de pagament configurat. - [event_already_processed](https://docs.factuarea.com/ca/errors/event_already_processed): Aquest esdeveniment del SIF ja consta a la cadena d'esdeveniments, i cada esdeveniment es processa exactament una vegada. - [event_not_found](https://docs.factuarea.com/ca/errors/event_not_found): L'identificador no correspon a cap esdeveniment de l'empresa autenticada, o l'esdeveniment va ser purgat per la política de retenció de 30 dies. - [export_limit_exceeded](https://docs.factuarea.com/ca/errors/export_limit_exceeded): La selecció filtrada supera el límit de 5.000 factures de l'exportació, així que el fitxer es rebutja d'entrada en lloc de truncar-se en silenci. - [external_id_already_exists](https://docs.factuarea.com/ca/errors/external_id_already_exists): L'`external_id` amb què concilies contra el teu sistema ja està assignat a un altre objecte del mateix tipus en aquesta empresa. - [face_transmission_failed](https://docs.factuarea.com/ca/errors/face_transmission_failed): La plataforma FACe —el punt d'entrada de les administracions públiques— era inaccessible o va respondre amb una fallada. El problema és aigües amunt, no a la teva petició. - [facturae_signing_failed](https://docs.factuarea.com/ca/errors/facturae_signing_failed): No es va poder produir la signatura XAdES del fitxer Facturae, normalment perquè el certificat de signatura no és utilitzable en aquell moment. - [feature_not_available_in_plan](https://docs.factuarea.com/ca/errors/feature_not_available_in_plan): La funcionalitat no està inclosa en el pla de l'empresa. - [forbidden_action](https://docs.factuarea.com/ca/errors/forbidden_action): L'acció està bloquejada per a aquest recurs encara que l'abast sigui el correcte: el recurs pertany a un catàleg compartit, o el canvi va per un altre endpoint. - [gestoria_module_required](https://docs.factuarea.com/ca/errors/gestoria_module_required): La gestoria té un pla vigent, però sense el mòdul de gestoria, així que no pot crear ni operar empreses gestionades. - [gestoria_plan_required](https://docs.factuarea.com/ca/errors/gestoria_plan_required): La gestoria no té una subscripció de pagament activa, així que no hi ha subscripció sobre la qual cobrar el seient. - [idempotency_key_in_use](https://docs.factuarea.com/ca/errors/idempotency_key_in_use): Hi ha una altra petició amb la mateixa `Idempotency-Key` encara en curs, i encara no se'n coneix el resultat. - [idempotency_key_invalid](https://docs.factuarea.com/ca/errors/idempotency_key_invalid): La `Idempotency-Key` no encaixa amb el format admès: entre 1 i 255 caràcters ASCII imprimibles. - [idempotency_key_reused](https://docs.factuarea.com/ca/errors/idempotency_key_reused): Aquesta `Idempotency-Key` ja es va fer servir amb un payload diferent. La clau identifica una operació concreta, així que reutilitzar-la per a una altra buidaria de sentit el replay. - [Codis d'error de Compte](https://docs.factuarea.com/ca/errors/index-account): Tots els codis d'error de l'API pública que emet Compte, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error d'Autenticació](https://docs.factuarea.com/ca/errors/index-authentication): Tots els codis d'error de l'API pública que emet Autenticació, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error d'Autorització](https://docs.factuarea.com/ca/errors/index-authorization): Tots els codis d'error de l'API pública que emet Autorització, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Clients](https://docs.factuarea.com/ca/errors/index-clients): Tots els codis d'error de l'API pública que emet Clients, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error d'Empreses](https://docs.factuarea.com/ca/errors/index-companies): Tots els codis d'error de l'API pública que emet Empreses, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error d'Albarans](https://docs.factuarea.com/ca/errors/index-delivery-notes): Tots els codis d'error de l'API pública que emet Albarans, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error d'Empleats](https://docs.factuarea.com/ca/errors/index-employees): Tots els codis d'error de l'API pública que emet Empleats, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error d'Events](https://docs.factuarea.com/ca/errors/index-events): Tots els codis d'error de l'API pública que emet Events, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error d'Idempotency](https://docs.factuarea.com/ca/errors/index-idempotency): Tots els codis d'error de l'API pública que emet Idempotency, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Factures](https://docs.factuarea.com/ca/errors/index-invoices): Tots els codis d'error de l'API pública que emet Factures, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Notificacions](https://docs.factuarea.com/ca/errors/index-notifications): Tots els codis d'error de l'API pública que emet Notificacions, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Pagaments](https://docs.factuarea.com/ca/errors/index-payments): Tots els codis d'error de l'API pública que emet Pagaments, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Productes](https://docs.factuarea.com/ca/errors/index-products): Tots els codis d'error de l'API pública que emet Productes, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Factures proforma](https://docs.factuarea.com/ca/errors/index-proformas): Tots els codis d'error de l'API pública que emet Factures proforma, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Factures de compra](https://docs.factuarea.com/ca/errors/index-purchase-invoices): Tots els codis d'error de l'API pública que emet Factures de compra, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Pressupostos](https://docs.factuarea.com/ca/errors/index-quotes): Tots els codis d'error de l'API pública que emet Pressupostos, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Límit de peticions](https://docs.factuarea.com/ca/errors/index-rate-limit): Tots els codis d'error de l'API pública que emet Límit de peticions, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Factures recurrents](https://docs.factuarea.com/ca/errors/index-recurring-invoices): Tots els codis d'error de l'API pública que emet Factures recurrents, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Request](https://docs.factuarea.com/ca/errors/index-request): Tots els codis d'error de l'API pública que emet Request, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Series](https://docs.factuarea.com/ca/errors/index-series): Tots els codis d'error de l'API pública que emet Series, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Servidor](https://docs.factuarea.com/ca/errors/index-server): Tots els codis d'error de l'API pública que emet Servidor, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Proveïdors](https://docs.factuarea.com/ca/errors/index-suppliers): Tots els codis d'error de l'API pública que emet Proveïdors, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error d'Informes fiscals](https://docs.factuarea.com/ca/errors/index-tax-reports): Tots els codis d'error de l'API pública que emet Informes fiscals, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error d'Impostos](https://docs.factuarea.com/ca/errors/index-taxes): Tots els codis d'error de l'API pública que emet Impostos, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de VeriFactu](https://docs.factuarea.com/ca/errors/index-verifactu): Tots els codis d'error de l'API pública que emet VeriFactu, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error de Webhooks](https://docs.factuarea.com/ca/errors/index-webhooks): Tots els codis d'error de l'API pública que emet Webhooks, amb el seu estat HTTP, el seu type i una pàgina per codi. - [Codis d'error per categoria](https://docs.factuarea.com/ca/errors): Tots els codis d'error de l'API pública agrupats per categoria, amb una pàgina per codi on s'explica la seva causa i què fer. - [indirect_tax_regime_invalid](https://docs.factuarea.com/ca/errors/indirect_tax_regime_invalid): El règim indirecte queda fora del catàleg `iva`, `igic`, `ipsi`. - [insufficient_data_for_report](https://docs.factuarea.com/ca/errors/insufficient_data_for_report): El període no té dades a declarar, o a una factura del període li falta un camp obligatori per a aquest model, típicament el NIF del client. - [insufficient_scope](https://docs.factuarea.com/ca/errors/insufficient_scope): La clau autentica correctament però no porta l'abast que exigeix aquesta operació. Els abasts es concedeixen en emetre la clau i no s'amplien en temps de crida. - [internal_error](https://docs.factuarea.com/ca/errors/internal_error): Alguna cosa s'ha trencat al nostre costat en processar la petició. La condició no la provoca el teu payload. - [invalid_aeat_code](https://docs.factuarea.com/ca/errors/invalid_aeat_code): El codi d'operació AEAT queda fora del catàleg tancat `S1`, `S2`, `S3`, `E1`-`E6`, `N1`, `N2` que fan servir VeriFactu i el SII. - [invalid_api_key](https://docs.factuarea.com/ca/errors/invalid_api_key): La clau no correspon a cap clau activa. Pot estar mal copiada, truncada, o pertànyer a un altre entorn: les claus de prova i les de producció no són intercanviables. - [invalid_certificate_format](https://docs.factuarea.com/ca/errors/invalid_certificate_format): El fitxer no és un contenidor PKCS#12: els seus primers bytes no corresponen a l'estructura ASN.1 que exigeix el format, digui el que digui l'extensió. - [invalid_certificate_password](https://docs.factuarea.com/ca/errors/invalid_certificate_password): La contrasenya no obre el fitxer del certificat. - [invalid_correction_nature](https://docs.factuarea.com/ca/errors/invalid_correction_nature): `correction_nature` només accepta `S` (substitució: la rectificativa porta els imports corregits complets) o `I` (per diferències: només porta el delta). - [invalid_correction_reason](https://docs.factuarea.com/ca/errors/invalid_correction_reason): El motiu de rectificació queda fora de la llista fiscal tancada (`error_fundado`, `concurso`, `incobrable`, `error_importe`, `error_cliente`, `devolucion`, `descuento`, `otras`), que mapeja als codis AEAT R1 a R4. - [invalid_country_aeat_zone](https://docs.factuarea.com/ca/errors/invalid_country_aeat_zone): La zona territorial AEAT queda fora del catàleg `peninsula`, `canarias`, `ceuta`, `melilla`. - [invalid_country_code](https://docs.factuarea.com/ca/errors/invalid_country_code): El codi de país no té exactament dos caràcters, així que no és un codi ISO 3166-1 alfa-2 vàlid. - [invalid_customer_visible_label](https://docs.factuarea.com/ca/errors/invalid_customer_visible_label): L'etiqueta que es mostra al client al document supera la longitud permesa. - [invalid_description](https://docs.factuarea.com/ca/errors/invalid_description): La descripció supera la longitud màxima permesa per al camp. - [invalid_document_type](https://docs.factuarea.com/ca/errors/invalid_document_type): El tipus de document queda fora del catàleg: `invoice`, `quote`, `delivery_note`, `proforma`, `purchase_invoice`, `recurring_invoice`. - [invalid_expiry_date](https://docs.factuarea.com/ca/errors/invalid_expiry_date): La data de venciment és anterior a la d'emissió, o la supera en més de 365 dies. - [invalid_frequency_interval](https://docs.factuarea.com/ca/errors/invalid_frequency_interval): L'interval és menor que 1, així que la recurrència mai avançaria a una execució següent. - [invalid_frequency_type](https://docs.factuarea.com/ca/errors/invalid_frequency_type): La freqüència queda fora del catàleg `daily`, `weekly`, `biweekly`, `monthly`, `bimonthly`, `quarterly`, `semiannual`, `annual`, `custom`. - [invalid_holiday_handling](https://docs.factuarea.com/ca/errors/invalid_holiday_handling): La política de festius queda fora del catàleg `skip`, `before`, `after`, `same`. - [invalid_invoice_id](https://docs.factuarea.com/ca/errors/invalid_invoice_id): La referència de factura rebuda no és un identificador vàlid; sol voler dir que s'ha colat un valor intern on l'API espera l'`id` públic. - [invalid_invoice_number](https://docs.factuarea.com/ca/errors/invalid_invoice_number): El número de factura no segueix el format canònic `SÈRIE-AAAA-NNN`, més el sufix `-RECn` a les rectificatives. - [invalid_invoice_status](https://docs.factuarea.com/ca/errors/invalid_invoice_status): El valor enviat com a estat de factura queda fora del catàleg del cicle de vida (`draft`, `scheduled`, `sent`, `paid`, `overdue`, `cancelled`, `annulled`). - [invalid_invoice_uuid](https://docs.factuarea.com/ca/errors/invalid_invoice_uuid): L'identificador de factura de la ruta o del payload no és un UUID vàlid. - [invalid_param_format](https://docs.factuarea.com/ca/errors/invalid_param_format): Un form request antic va rebutjar la forma d'un valor. Els endpoints migrats reporten el mateix com a `parameter_invalid_format` o `parameter_invalid_integer`. - [invalid_param_value](https://docs.factuarea.com/ca/errors/invalid_param_value): Un form request antic va rebutjar el valor d'un camp. Els endpoints migrats reporten el mateix com a `parameter_invalid_enum` o `parameter_invalid_range`. - [invalid_payment_date](https://docs.factuarea.com/ca/errors/invalid_payment_date): La data de pagament queda fora de la finestra admesa: no pot ser anterior a la data d'emissió de la factura ni situar-se al futur. - [invalid_payment_method](https://docs.factuarea.com/ca/errors/invalid_payment_method): El mètode de pagament queda fora de l'allowlist tancada: `bank_transfer`, `cash`, `credit_card`, `sepa_direct_debit`, `paypal`, `bizum`, `other`. - [invalid_period](https://docs.factuarea.com/ca/errors/invalid_period): El període no identifica una declaració: l'any queda fora del rang admès, o falta el trimestre o és fora del rang 1 a 4 en un model trimestral. - [invalid_proforma_id](https://docs.factuarea.com/ca/errors/invalid_proforma_id): La referència de proforma rebuda no és un identificador vàlid, normalment perquè un valor intern va substituir l'`id` públic. - [invalid_proforma_number](https://docs.factuarea.com/ca/errors/invalid_proforma_number): El número de proforma no segueix el format canònic de numeració de la seva sèrie. - [invalid_proforma_status](https://docs.factuarea.com/ca/errors/invalid_proforma_status): El valor enviat com a estat queda fora del catàleg `draft`, `accepted`, `rejected`, `expired`, `invoiced`, `cancelled`. - [invalid_proforma_uuid](https://docs.factuarea.com/ca/errors/invalid_proforma_uuid): L'identificador de proforma de la ruta o del payload no és un UUID vàlid. - [invalid_purchase_invoice_id](https://docs.factuarea.com/ca/errors/invalid_purchase_invoice_id): La referència de factura de compra rebuda no és un identificador vàlid, normalment perquè un valor intern va substituir l'`id` públic. - [invalid_purchase_invoice_number](https://docs.factuarea.com/ca/errors/invalid_purchase_invoice_number): El número de factura és buit o no encaixa amb el format admès. En una factura de compra el número és el que va imprimir el proveïdor, no un que generi Factuarea. - [invalid_purchase_invoice_uuid](https://docs.factuarea.com/ca/errors/invalid_purchase_invoice_uuid): L'identificador de factura de compra de la ruta o del payload no és un UUID vàlid. - [invalid_rate_for_tax_regime](https://docs.factuarea.com/ca/errors/invalid_rate_for_tax_regime): El tipus no pertany a la graella legal del seu règim: l'IGIC admet 0, 3, 5, 7, 9,5, 15 i 20 %; l'IPSI admet 0, 0,5, 1, 2, 4, 8 i 10 %. - [invalid_recurring_invoice_id](https://docs.factuarea.com/ca/errors/invalid_recurring_invoice_id): La referència de recurrència rebuda no és un identificador vàlid, normalment perquè un valor intern va substituir l'`id` públic. - [invalid_recurring_invoice_uuid](https://docs.factuarea.com/ca/errors/invalid_recurring_invoice_uuid): L'identificador de recurrència de la ruta o del payload no és un UUID vàlid. - [invalid_series_code](https://docs.factuarea.com/ca/errors/invalid_series_code): El codi de la sèrie és buit, massa llarg, o porta caràcters que no corresponen a un prefix fiscal. - [invalid_series_name](https://docs.factuarea.com/ca/errors/invalid_series_name): El nom de la sèrie és buit o supera la longitud permesa. - [invalid_series_number](https://docs.factuarea.com/ca/errors/invalid_series_number): El número inicial no és vàlid: no és un enter positiu, o queda a l'últim número ja emès o per sota, cosa que reemetria números ja consumits. - [invalid_series_uuid](https://docs.factuarea.com/ca/errors/invalid_series_uuid): L'identificador de sèrie de la ruta o del payload no és un UUID vàlid. - [invalid_series_year](https://docs.factuarea.com/ca/errors/invalid_series_year): L'exercici no és un any de quatre xifres vàlid per a una sèrie de numeració. - [invalid_status_transition](https://docs.factuarea.com/ca/errors/invalid_status_transition): L'estat sol·licitat no és assolible des de l'estat en què es troba ara mateix el document. - [invalid_tax_code](https://docs.factuarea.com/ca/errors/invalid_tax_code): El codi de l'impost és buit o supera els 50 caràcters. - [invalid_tax_name](https://docs.factuarea.com/ca/errors/invalid_tax_name): El nom de l'impost és buit o supera els 255 caràcters. - [invalid_tax_rate](https://docs.factuarea.com/ca/errors/invalid_tax_rate): El tipus impositiu queda fora del rang permès per a la seva classe: IVA 0-27 %, retenció 0-47 %, recàrrec d'equivalència 0-10 %, altres 0-100 %. - [invalid_tax_type_filter](https://docs.factuarea.com/ca/errors/invalid_tax_type_filter): El filtre `type` del llistat per tipus porta un valor fora de l'enum `vat`, `retention`, `surcharge`, `other`. - [invalid_validity_window](https://docs.factuarea.com/ca/errors/invalid_validity_window): La finestra de vigència està invertida: `valid_until` és anterior a `valid_from`. - [invoice_already_annulled](https://docs.factuarea.com/ca/errors/invoice_already_annulled): La factura ja estava anul·lada. L'anul·lació és terminal i, amb VeriFactu actiu, el seu registre d'anul·lació ja va arribar a l'AEAT. - [invoice_already_paid](https://docs.factuarea.com/ca/errors/invoice_already_paid): La factura ja està cobrada. `paid` és un estat terminal i comptablement tancat: l'IVA repercutit ja s'ha declarat, o es declararà en el període. - [invoice_already_sent](https://docs.factuarea.com/ca/errors/invoice_already_sent): La factura ja va ser emesa: té número definitiu de sèrie i, amb VeriFactu actiu, l'alta a l'AEAT. L'emissió no passa dues vegades. - [invoice_cannot_assign_number](https://docs.factuarea.com/ca/errors/invoice_cannot_assign_number): Es va demanar número definitiu per a una factura que no és esborrany, o que ja en té. La numeració de sèrie és monòtona i els números no es reassignen. - [invoice_invalid_status_transition](https://docs.factuarea.com/ca/errors/invoice_invalid_status_transition): L'estat destí no és assolible des de l'actual. El cicle de vida és dirigit: `draft` passa a `scheduled` o `sent`, `sent` a `paid`, `overdue` o `annulled`, i `paid`, `cancelled` i `annulled` són terminals. - [invoice_not_cancellable_in_current_state](https://docs.factuarea.com/ca/errors/invoice_not_cancellable_in_current_state): Cancel·lar retira un esborrany que encara no és fiscalment vinculant, així que només s'aplica mentre la factura està en `draft`. - [invoice_not_correctable_in_current_state](https://docs.factuarea.com/ca/errors/invoice_not_correctable_in_current_state): Una rectificativa només s'emet contra una factura ja emesa (`sent` o `paid`). Un esborrany, una factura cancel·lada o una anul·lada no tenen res a rectificar. - [invoice_not_deletable_in_current_state](https://docs.factuarea.com/ca/errors/invoice_not_deletable_in_current_state): Només s'esborren les factures en `draft` i `cancelled`. Una factura numerada no desapareix mai: la sèrie correlativa ha de seguir sent auditable. - [invoice_not_editable_in_current_state](https://docs.factuarea.com/ca/errors/invoice_not_editable_in_current_state): Només un esborrany admet edició. Un cop emesa, la factura és immutable i el seu contingut queda congelat juntament amb el seu registre fiscal. - [invoice_not_eligible_for_action](https://docs.factuarea.com/ca/errors/invoice_not_eligible_for_action): L'acció sol·licitada no s'aplica a aquesta factura: el seu tipus o el seu estat actual la deixen fora de l'abast de l'operació. - [invoice_not_found](https://docs.factuarea.com/ca/errors/invoice_not_found): L'identificador no resol a cap factura de l'empresa autenticada. Les factures d'una altra empresa responen exactament igual. - [invoice_not_modifiable_in_current_state](https://docs.factuarea.com/ca/errors/invoice_not_modifiable_in_current_state): El camp que intentes canviar està congelat per a l'estat actual — per exemple el règim fiscal d'una factura anul·lada. - [invoice_not_paid](https://docs.factuarea.com/ca/errors/invoice_not_paid): Es va demanar un justificant de pagament d'una factura sense cobrament registrat, així que no hi ha res a certificar. - [invoice_not_reschedulable_in_current_state](https://docs.factuarea.com/ca/errors/invoice_not_reschedulable_in_current_state): Reprogramar mou la data d'emissió d'una factura que espera en `scheduled`, i aquesta factura no està esperant. - [invoice_not_schedulable_in_current_state](https://docs.factuarea.com/ca/errors/invoice_not_schedulable_in_current_state): Només un esborrany es pot programar: la programació reserva un moment futur d'emissió sense consumir encara número de sèrie. - [invoice_not_unschedulable_in_current_state](https://docs.factuarea.com/ca/errors/invoice_not_unschedulable_in_current_state): Desprogramar torna la factura de `scheduled` a `draft`, així que només s'aplica mentre segueix esperant a emetre's. - [invoice_not_unsendable_in_current_state](https://docs.factuarea.com/ca/errors/invoice_not_unsendable_in_current_state): Desfer la marca de lliurament només s'aplica a una factura `sent`: neteja `sent_at` i manté la factura emesa. - [invoice_requires_at_least_one_line](https://docs.factuarea.com/ca/errors/invoice_requires_at_least_one_line): La factura no porta cap línia d'operació, així que no té base imposable i no es pot emetre. Passa tant quan no envies línies com quan totes les que envies són de suplert: un suplert és una quantitat pagada per compte del client (art. 78.Tres.3 LIVA), no una operació teva. - [invoice_year_required_for_ambiguous_number](https://docs.factuarea.com/ca/errors/invoice_year_required_for_ambiguous_number): Aquest número de factura existeix en més d'un exercici, així que per si sol no identifica una única factura. - [ip_not_allowed](https://docs.factuarea.com/ca/errors/ip_not_allowed): La clau restringeix les adreces que accepta, i la petició va arribar des d'una que no és a la llista. - [length_required](https://docs.factuarea.com/ca/errors/length_required): Va arribar una petició amb body en codificació chunked, sense declarar-ne la mida. L'API necessita conèixer la longitud per avançat per rebutjar payloads excessius abans de carregar-los a memòria. - [line_total_checksum_mismatch](https://docs.factuarea.com/ca/errors/line_total_checksum_mismatch): El `line_total` declarat no coincideix amb el que calcula Factuarea per a aquella línia (quantitat × preu − descompte + IVA − retenció + recàrrec) i la desviació supera el cèntim de tolerància. L'import que es factura i es declara a l'AEAT és sempre el calculat aquí, així que la discrepància vol dir que el teu sistema i la factura emesa no quadrarien. - [line_type_invalid](https://docs.factuarea.com/ca/errors/line_type_invalid): El tipus de línia queda fora del catàleg tancat `NORMAL` / `SUPLIDO`. Una factura emesa només distingeix dues naturaleses: el que véns tu, que forma base imposable i porta IVA, i el suplert, que són diners avançats en nom i per compte del client i per això queda fora de la base (art. 78.Tres.3 LIVA). - [maintenance](https://docs.factuarea.com/ca/errors/maintenance): La plataforma és en finestra de manteniment i les escriptures es retenen a propòsit. - [max_api_keys_exceeded](https://docs.factuarea.com/ca/errors/max_api_keys_exceeded): L'empresa va arribar al nombre de claus API que permet el seu pla. - [max_retries_exceeded](https://docs.factuarea.com/ca/errors/max_retries_exceeded): El registre va esgotar el pressupost de reintents tècnics de reenviament de l'XML emmagatzemat. Reintentar el mateix contingut tornaria a fallar igual. - [max_webhook_endpoints_exceeded](https://docs.factuarea.com/ca/errors/max_webhook_endpoints_exceeded): L'empresa va arribar al nombre d'endpoints de webhook que permet el seu nivell d'add-on. - [metadata_too_many_keys](https://docs.factuarea.com/ca/errors/metadata_too_many_keys): L'objecte `metadata` supera el límit de 50 claus per recurs. - [metadata_value_too_long](https://docs.factuarea.com/ca/errors/metadata_value_too_long): Un valor de `metadata` supera els 500 caràcters un cop serialitzat a text. - [method_not_allowed](https://docs.factuarea.com/ca/errors/method_not_allowed): La ruta existeix però no accepta el verb HTTP utilitzat. - [missing_api_key](https://docs.factuarea.com/ca/errors/missing_api_key): La petició no porta credencials: ni capçalera `Authorization` ni `X-API-Key`. - [missing_required_param](https://docs.factuarea.com/ca/errors/missing_required_param): Un form request antic va detectar que faltava un camp obligatori. Els endpoints ja migrats als parsers canònics reporten el mateix com a `parameter_missing`. - [mode_switch_blocked_until_year_end](https://docs.factuarea.com/ca/errors/mode_switch_blocked_until_year_end): El mode VeriFactu es va activar en aquest exercici i ja es va emetre com a mínim un registre de facturació. Fer marxa enrere degradaria la integritat d'una cadena ja declarada a l'AEAT. - [module_not_available_in_sandbox](https://docs.factuarea.com/ca/errors/module_not_available_in_sandbox): El recurs pertany a un mòdul vetat en mode test. La sandbox mai toca l'AEAT, els bancs ni cobraments reals, així que aquests mòduls queden fora a propòsit. - [monthly_quota_exceeded](https://docs.factuarea.com/ca/errors/monthly_quota_exceeded): L'empresa va esgotar la quota mensual de crides que inclou el seu pla. - [monthly_requires_month_segmented_format](https://docs.factuarea.com/ca/errors/monthly_requires_month_segmented_format): El comptador es reinicia cada mes però la màscara de numeració no segrega per mes, així que dos mesos arrencarien al mateix correlatiu i produirien números duplicats dins de l'any. - [no_invoices_in_period](https://docs.factuarea.com/ca/errors/no_invoices_in_period): L'operació trimestral no va trobar factures en el període demanat, així que no hi ha res a empaquetar ni a enviar. - [notification_not_found](https://docs.factuarea.com/ca/errors/notification_not_found): L'identificador no correspon a cap notificació de l'empresa autenticada, o la notificació va quedar fora de la finestra de retenció. - [operation_regime_invalid](https://docs.factuarea.com/ca/errors/operation_regime_invalid): El règim d'operació queda fora del catàleg `general`, `intracomunitaria`, `importacion_exportacion`, `isp`. - [origin_not_allowed](https://docs.factuarea.com/ca/errors/origin_not_allowed): La petició ve d'un origen de navegador que la clau no accepta. - [pack_in_use](https://docs.factuarea.com/ca/errors/pack_in_use): El pack està referenciat per documents emesos, així que esborrar-lo trencaria la seva composició. - [pack_not_found](https://docs.factuarea.com/ca/errors/pack_not_found): L'identificador no resol a cap pack de l'empresa autenticada. - [pack_share_link_failed](https://docs.factuarea.com/ca/errors/pack_share_link_failed): No es va poder generar l'enllaç per compartir el pack. El pack en si no queda afectat. - [parameter_invalid](https://docs.factuarea.com/ca/errors/parameter_invalid): Un value object construït a partir del payload va rebutjar el valor rebut. `error.subcode` diu quin: codi d'impost, codi de país, tipus impositiu, etc. - [parameter_invalid_boolean](https://docs.factuarea.com/ca/errors/parameter_invalid_boolean): Un paràmetre que ha de ser booleà va rebre un valor fora de les representacions acceptades (`true`/`false`, `1`/`0`). - [parameter_invalid_cursor](https://docs.factuarea.com/ca/errors/parameter_invalid_cursor): El cursor `starting_after` o `ending_before` no és un UUID vàlid, així que no pot apuntar a cap fila de la col·lecció. - [parameter_invalid_empty](https://docs.factuarea.com/ca/errors/parameter_invalid_empty): Un paràmetre va arribar amb el valor buit: un filtre `in` sense elements, una comparació sense res després de l'operador, o un filtre d'igualtat amb la cadena buida. - [parameter_invalid_enum](https://docs.factuarea.com/ca/errors/parameter_invalid_enum): El valor queda fora del conjunt tancat que accepta el paràmetre. En els llistats cobreix a més un operador de filtre diferent de `eq`, `gte`, `lte`, `gt`, `lt`, `in` o `contains`. - [parameter_invalid_format](https://docs.factuarea.com/ca/errors/parameter_invalid_format): El valor té el tipus correcte però no la forma que exigeix el paràmetre: una data, un patró d'identificador o una capçalera com `Factuarea-Version`. - [parameter_invalid_integer](https://docs.factuarea.com/ca/errors/parameter_invalid_integer): Un paràmetre que ha de ser un nombre enter va rebre alguna cosa que no es pot interpretar com a tal, per exemple `limit=abc`. - [parameter_invalid_iso8601](https://docs.factuarea.com/ca/errors/parameter_invalid_iso8601): Un filtre de rang (`gte`, `lte`, `gt`, `lt`) va rebre un valor que no és numèric ni una data ISO 8601. - [parameter_invalid_range](https://docs.factuarea.com/ca/errors/parameter_invalid_range): Un paràmetre numèric va quedar fora dels seus límits. El cas habitual és `limit`, que ha d'estar entre 1 i 100. - [parameter_invalid_string](https://docs.factuarea.com/ca/errors/parameter_invalid_string): Un paràmetre que ha de ser text va rebre un array, un objecte o un valor que no es pot llegir com a cadena. - [parameter_invalid_url](https://docs.factuarea.com/ca/errors/parameter_invalid_url): Un camp que ha de contenir una URL absoluta va rebre un valor que no ho és, normalment perquè li falta l'esquema o l'amfitrió. - [parameter_invalid_uuid](https://docs.factuarea.com/ca/errors/parameter_invalid_uuid): Un camp d'identificador va rebre un valor que no és un UUID vàlid. Tot `id` de recurs a v1 és un UUID. - [parameter_invalid_value](https://docs.factuarea.com/ca/errors/parameter_invalid_value): El valor és sintàcticament correcte però no admissible per a aquest recurs: fora del catàleg canònic del camp, o incoherent amb la resta del payload. - [parameter_missing](https://docs.factuarea.com/ca/errors/parameter_missing): L'endpoint exigeix un paràmetre que la petició no portava. `error.param` diu quin. - [parameter_unknown](https://docs.factuarea.com/ca/errors/parameter_unknown): La petició porta un paràmetre que l'endpoint no accepta: un filtre fora de la seva allowlist, un camp de `sort` no ordenable, o el `page` de paginació per offset — v1 pagina per cursor. - [payload_too_large](https://docs.factuarea.com/ca/errors/payload_too_large): El body de la petició supera la mida admesa: 1 MB amb caràcter general, 6 MB als endpoints que accepten fitxers. - [payment_method_invalid](https://docs.factuarea.com/ca/errors/payment_method_invalid): La mateixa allowlist tancada que `invalid_payment_method`, reportada quan el valor es rebutja en llegir el camp de mètode de pagament del payload. - [payment_method_required](https://docs.factuarea.com/ca/errors/payment_method_required): Donar d'alta una empresa gestionada cobra un seient immediatament, i la gestoria opera en mode real sense mètode de pagament configurat. - [payout_reconciliation_amount_mismatch](https://docs.factuarea.com/ca/errors/payout_reconciliation_amount_mismatch): L'import confirmat no coincideix amb el net de la liquidació, així que la conciliació tancaria amb una diferència que ningú justifica. - [pdf_generation_failed](https://docs.factuarea.com/ca/errors/pdf_generation_failed): El servei de renderitzat no va poder produir el PDF. El document i les seves dades són intactes: el que ha fallat és el fitxer. - [product_in_use](https://docs.factuarea.com/ca/errors/product_in_use): El producte està referenciat per documents emesos o per altres entrades del catàleg, i eliminar-lo deixaria aquestes referències penjant. - [product_not_found](https://docs.factuarea.com/ca/errors/product_not_found): L'identificador no resol a cap producte de l'empresa autenticada. - [profile_not_found](https://docs.factuarea.com/ca/errors/profile_not_found): La capçalera `X-Active-Profile` anomena una empresa que no existeix o que no pertany a l'arbre de gestoria de la clau autenticada. Tots dos casos responen igual perquè l'API mai reveli empreses d'altres tenants. - [proforma_already_accepted](https://docs.factuarea.com/ca/errors/proforma_already_accepted): El client ja va acceptar la proforma, i l'acceptació es registra una sola vegada. - [proforma_already_rejected](https://docs.factuarea.com/ca/errors/proforma_already_rejected): La proforma ja està marcada com a rebutjada. - [proforma_cannot_be_accepted](https://docs.factuarea.com/ca/errors/proforma_cannot_be_accepted): L'acceptació no escau des de l'estat actual: una proforma facturada, cancel·lada o expirada ja no l'admet. - [proforma_cannot_be_rejected](https://docs.factuarea.com/ca/errors/proforma_cannot_be_rejected): El rebuig no escau des de l'estat actual: un cop facturada, cancel·lada o expirada, la proforma està tancada. - [proforma_cannot_be_sent](https://docs.factuarea.com/ca/errors/proforma_cannot_be_sent): L'enviament per correu no s'aplica a una proforma en estat terminal: no hi ha oferta viva a lliurar. - [proforma_invalid_status_transition](https://docs.factuarea.com/ca/errors/proforma_invalid_status_transition): L'estat destí no és assolible des de l'actual: un esborrany s'accepta, es cancel·la o expira; una proforma acceptada es factura, es rebutja o expira; facturada, cancel·lada i expirada són terminals. - [proforma_not_convertible_in_current_state](https://docs.factuarea.com/ca/errors/proforma_not_convertible_in_current_state): Convertir en factura exigeix que el client hagi acceptat la proforma; des de qualsevol altre estat no hi ha acord a facturar. - [proforma_not_deletable_in_current_state](https://docs.factuarea.com/ca/errors/proforma_not_deletable_in_current_state): Només s'esborra una proforma en esborrany. Un cop acceptada, rebutjada o facturada forma part del rastre comercial. - [proforma_not_draft](https://docs.factuarea.com/ca/errors/proforma_not_draft): L'operació només té sentit mentre la proforma és un esborrany, i aquesta ja ha avançat. - [proforma_not_editable_in_current_state](https://docs.factuarea.com/ca/errors/proforma_not_editable_in_current_state): Només una proforma en esborrany admet edició. Un cop acceptada, rebutjada, expirada, facturada o cancel·lada, el seu contingut queda fixat. - [proforma_not_found](https://docs.factuarea.com/ca/errors/proforma_not_found): L'identificador no resol a cap proforma de l'empresa autenticada. - [proforma_requires_at_least_one_line](https://docs.factuarea.com/ca/errors/proforma_requires_at_least_one_line): La proforma no porta línies, així que no hi ha import a posar davant del client. - [public_link_expires_at_exceeds_max_days](https://docs.factuarea.com/ca/errors/public_link_expires_at_exceeds_max_days): La caducitat demanada per a l'enllaç públic supera la finestra màxima que permet el teu pla per a documents compartits. - [purchase_invoice_already_exists](https://docs.factuarea.com/ca/errors/purchase_invoice_already_exists): Aquest proveïdor ja té registrada una factura de compra amb el mateix número. El parell proveïdor + número identifica el document sense ambigüitat i evita comptabilitzar dues vegades la mateixa despesa. - [purchase_invoice_not_deletable_in_current_state](https://docs.factuarea.com/ca/errors/purchase_invoice_not_deletable_in_current_state): Només s'esborren les factures de compra en esborrany o cancel·lades. Una de pendent o pagada forma part del llibre de despeses. - [purchase_invoice_not_draft](https://docs.factuarea.com/ca/errors/purchase_invoice_not_draft): L'operació només s'aplica mentre la factura de compra és un esborrany, i aquesta ja està registrada. - [purchase_invoice_not_editable_in_current_state](https://docs.factuarea.com/ca/errors/purchase_invoice_not_editable_in_current_state): Només s'edita una factura de compra en esborrany. Un cop registrada com a pendent, pagada o cancel·lada, el seu contingut dona suport a un apunt comptable. - [purchase_invoice_not_found](https://docs.factuarea.com/ca/errors/purchase_invoice_not_found): L'identificador no resol a cap factura de compra de l'empresa autenticada. - [purchase_invoice_requires_at_least_one_line](https://docs.factuarea.com/ca/errors/purchase_invoice_requires_at_least_one_line): La factura de compra no porta línies, així que no hi ha despesa ni IVA suportat a registrar. - [quote_already_accepted](https://docs.factuarea.com/ca/errors/quote_already_accepted): El pressupost ja estava aprovat, i l'aprovació es registra una sola vegada. - [quote_already_rejected](https://docs.factuarea.com/ca/errors/quote_already_rejected): El pressupost ja està marcat com a rebutjat. - [quote_expired](https://docs.factuarea.com/ca/errors/quote_expired): El pressupost va passar la seva data de validesa, així que les condicions ofertes ja no vinculen i no es pot aprovar ni convertir tal com està. - [quote_not_found](https://docs.factuarea.com/ca/errors/quote_not_found): L'identificador no resol a cap pressupost de l'empresa autenticada. - [rate_limit_exceeded](https://docs.factuarea.com/ca/errors/rate_limit_exceeded): La clau va enviar més peticions de les que permet el seu ritme a la finestra actual. - [receipt_not_available](https://docs.factuarea.com/ca/errors/receipt_not_available): No hi ha justificant a emetre perquè el document no té cap cobrament registrat al darrere. - [record_already_accepted](https://docs.factuarea.com/ca/errors/record_already_accepted): L'AEAT ja va acceptar el registre. L'acceptació és terminal i el seu contingut queda congelat com a part de la cadena d'empremtes. - [record_immutable](https://docs.factuarea.com/ca/errors/record_immutable): El registre pertany a un ledger de només-addició: un cop escrit, el seu contingut fiscal queda tancat a modificacions i a esborrat. - [record_not_rejected](https://docs.factuarea.com/ca/errors/record_not_rejected): L'esmena només s'aplica a registres que l'AEAT va rebutjar per dades. Aquest registre està en un altre estat — una fallada tècnica, per exemple, la cobreix el reintent automàtic. - [record_not_subsanable](https://docs.factuarea.com/ca/errors/record_not_subsanable): El registre no es pot esmenar: no és un registre d'alta, o no té factura d'origen des de la qual regenerar-ne el contingut. - [recurring_already_active](https://docs.factuarea.com/ca/errors/recurring_already_active): La recurrència ja està en marxa, així que no hi ha res a activar. Codi antic conservat per compatibilitat: els endpoints actuals reporten això com a `recurring_invoice_already_active`. - [recurring_invoice_already_active](https://docs.factuarea.com/ca/errors/recurring_invoice_already_active): La recurrència ja està en marxa. - [recurring_invoice_already_cancelled](https://docs.factuarea.com/ca/errors/recurring_invoice_already_cancelled): La recurrència ja estava cancel·lada, i la cancel·lació és terminal. - [recurring_invoice_already_paused](https://docs.factuarea.com/ca/errors/recurring_invoice_already_paused): La recurrència ja està pausada, així que pausar-la un altre cop no canvia res. - [recurring_invoice_cancelled_cannot_resume](https://docs.factuarea.com/ca/errors/recurring_invoice_cancelled_cannot_resume): Una recurrència cancel·lada no es reprèn: la cancel·lació la tanca definitivament, a diferència de la pausa. - [recurring_invoice_cannot_run](https://docs.factuarea.com/ca/errors/recurring_invoice_cannot_run): La recurrència no pot generar una factura ara mateix: no està en marxa, el seu cicle s'ha acabat, o li falten dades que la factura necessita. `error.message` indica el motiu concret. - [recurring_invoice_has_generated_invoices](https://docs.factuarea.com/ca/errors/recurring_invoice_has_generated_invoices): La recurrència ja va generar factures, i aquestes factures en depenen per a la seva traçabilitat. - [recurring_invoice_not_found](https://docs.factuarea.com/ca/errors/recurring_invoice_not_found): L'identificador no resol a cap recurrència de l'empresa autenticada. - [recurring_invoice_requires_at_least_one_line](https://docs.factuarea.com/ca/errors/recurring_invoice_requires_at_least_one_line): La recurrència no porta línies, així que cada factura generada sortiria buida. - [recurring_not_active](https://docs.factuarea.com/ca/errors/recurring_not_active): L'operació necessita una recurrència en marxa i aquesta està pausada, completada o cancel·lada. Codi antic conservat per compatibilitat amb integracions velles. - [register_sealing_failed](https://docs.factuarea.com/ca/errors/register_sealing_failed): El segellat criptogràfic del registre no es va completar, així que el tancament va quedar sense signar en lloc de segellat amb una signatura trencada. - [reminder_not_applicable](https://docs.factuarea.com/ca/errors/reminder_not_applicable): El recordatori de pagament no escau: la factura no està en `sent` ni `overdue`, no hi ha adreça de destinatari, falta l'enllaç públic o està desactivat, o ja va sortir un altre recordatori les últimes 24 hores. - [replay_delivery_not_retryable](https://docs.factuarea.com/ca/errors/replay_delivery_not_retryable): Només es reenvien els lliuraments fallits. Un lliurament que va arribar bé, o un encara en curs, no té res a reenviar. - [replay_event_expired](https://docs.factuarea.com/ca/errors/replay_event_expired): L'esdeveniment que dona suport al lliurament va ser purgat per la política de retenció de 30 dies, així que ja no queda payload a reenviar. - [report_format_invalid](https://docs.factuarea.com/ca/errors/report_format_invalid): El format queda fora del catàleg `txt_aeat`, `pdf`, `excel`. - [requires_annulment](https://docs.factuarea.com/ca/errors/requires_annulment): El contingut regenerat canvia un camp que entra a l'empremta —NIF de l'emissor, sèrie i número, data d'expedició, tipus de factura, quota o import total— i la cadena no es pot reescriure. - [resource_already_exists](https://docs.factuarea.com/ca/errors/resource_already_exists): Crear l'objecte duplicaria un que ja existeix sota una clau única — NIF, SKU, external id. `error.details.existing_resource_id` apunta a l'objecte que ja ocupa aquest valor. - [resource_conflict](https://docs.factuarea.com/ca/errors/resource_conflict): L'operació va xocar amb l'estat actual del recurs i no s'aplica cap codi de conflicte més específic. - [resource_immutable](https://docs.factuarea.com/ca/errors/resource_immutable): L'objecte està tancat a canvis per a aquesta operació: el seu estat o el seu registre comptable impedeixen modificar-lo. - [resource_locked](https://docs.factuarea.com/ca/errors/resource_locked): Una altra operació reté el recurs fins que acaba: les escriptures concurrents sobre el mateix objecte se serialitzen en lloc d'entrellaçar-se. - [resource_not_deletable](https://docs.factuarea.com/ca/errors/resource_not_deletable): L'objecte existeix, però el seu estat o els seus dependents bloquegen l'esborrat. En els esborrats massius aquest és el codi per fila de cada entrada que no es va poder eliminar. - [resource_not_found](https://docs.factuarea.com/ca/errors/resource_not_found): L'identificador no resol a res visible per a l'empresa autenticada. Els objectes d'una altra empresa responen exactament igual, a propòsit. - [route_not_found](https://docs.factuarea.com/ca/errors/route_not_found): La ruta no correspon a cap endpoint de v1. Sol ser una errada, un prefix `/v1` absent o una ruta d'una altra àrea de l'API. - [scheduled_for_in_past](https://docs.factuarea.com/ca/errors/scheduled_for_in_past): `scheduled_for` no és estrictament futur, així que no hi ha cap espera a reservar. - [scope_not_allowed_by_plan](https://docs.factuarea.com/ca/errors/scope_not_allowed_by_plan): Un dels abasts demanats pertany a un mòdul que el pla no inclou, així que la clau naixeria amb un permís que mai podria exercir. - [scope_not_allowed_in_sandbox](https://docs.factuarea.com/ca/errors/scope_not_allowed_in_sandbox): Una clau de prova no pot néixer amb abasts de mòduls vetats a la sandbox. - [seat_charge_failed](https://docs.factuarea.com/ca/errors/seat_charge_failed): El cobrament immediat del prorrateig del seient va ser rebutjat: la targeta es va denegar, necessita autenticació, o el proveïdor de pagament era inaccessible. L'empresa no es crea si el seient no es cobra. - [send_failed](https://docs.factuarea.com/ca/errors/send_failed): El document no es va lliurar per correu: el proveïdor de correu va rebutjar el missatge o era inaccessible. - [series_already_archived](https://docs.factuarea.com/ca/errors/series_already_archived): La sèrie ja estava arxivada, i l'arxivat no es repeteix: una segona crida indica que el client ha perdut l'estat real. - [series_code_immutable_with_documents](https://docs.factuarea.com/ca/errors/series_code_immutable_with_documents): Canviar el prefix d'una sèrie que ja va emetre documents reescriuria retroactivament el seu identificador fiscal, mentre els clients i l'AEAT tenen el número original. - [series_has_documents](https://docs.factuarea.com/ca/errors/series_has_documents): La sèrie ja va numerar documents, així que no es pot eliminar: la seqüència correlativa ha de seguir sent auditable. - [series_immutable](https://docs.factuarea.com/ca/errors/series_immutable): Les sèries no són editables ni eliminables via API: la continuïtat legal de la numeració exigeix que el seu prefix, el seu any i el seu comptador es quedin com estan. - [series_initial_number_creates_gap](https://docs.factuarea.com/ca/errors/series_initial_number_creates_gap): El número inicial salta més enllà del següent correlatiu natural havent-hi documents de l'any en curs, i aquest buit a la seqüència no és admissible per a l'AEAT. - [series_locked_by_verifactu](https://docs.factuarea.com/ca/errors/series_locked_by_verifactu): Com a mínim una factura de la sèrie té un registre de facturació acceptat per l'AEAT, cosa que congela el prefix, l'any i la base de numeració de la sèrie. - [series_not_found](https://docs.factuarea.com/ca/errors/series_not_found): L'identificador no resol a cap sèrie de numeració de l'empresa autenticada. - [series_type_invalid](https://docs.factuarea.com/ca/errors/series_type_invalid): El tipus de document de la sèrie queda fora del catàleg `invoice`, `quote`, `delivery_note`, `proforma`, `purchase_invoice`, `recurring_invoice`. - [series_year_locked](https://docs.factuarea.com/ca/errors/series_year_locked): La sèrie ja va emetre documents en el seu any vigent. Moure l'any deixaria aquests documents apuntant a un exercici buit mentre la seva base imposable és en un altre. - [service_unavailable](https://docs.factuarea.com/ca/errors/service_unavailable): El servei, o una dependència que necessita, no pot respondre temporalment. - [signature_payload_too_large](https://docs.factuarea.com/ca/errors/signature_payload_too_large): La imatge de la signatura supera la mida admesa per al camp. - [sii_excluded](https://docs.factuarea.com/ca/errors/sii_excluded): L'empresa està registrada al SII, i els obligats al SII queden exclosos del reglament VeriFactu. - [simplified_invoice_cannot_be_substituted](https://docs.factuarea.com/ca/errors/simplified_invoice_cannot_be_substituted): Una de les factures de la llista de substitució no es pot substituir: no és simplificada, està cancel·lada o anul·lada, pertany a una altra empresa, o ja té substitutiva. - [simplified_invoice_not_allowed](https://docs.factuarea.com/ca/errors/simplified_invoice_not_allowed): L'operació no és elegible per a factura simplificada: supera els 3.000 €, o és un lliurament intracomunitari, una exportació, una operació amb inversió del subjecte passiu, o el client necessita factura completa per deduir l'IVA. - [simplified_limit_exceeded](https://docs.factuarea.com/ca/errors/simplified_limit_exceeded): Les línies portarien la factura simplificada (F2) per sobre del límit legal absolut de 3.000 € IVA inclòs. - [sku_already_exists](https://docs.factuarea.com/ca/errors/sku_already_exists): Un altre producte de l'empresa ja fa servir aquest SKU, i el SKU identifica l'article sense ambigüitat dins del catàleg. - [stripe_payout_already_reconciled](https://docs.factuarea.com/ca/errors/stripe_payout_already_reconciled): La liquidació ja estava conciliada, i la conciliació és terminal: repetir-la comptabilitzaria dues vegades l'apunt bancari. - [stripe_payout_not_found](https://docs.factuarea.com/ca/errors/stripe_payout_not_found): L'identificador no resol a cap liquidació de l'empresa autenticada. - [suplido_line_cannot_carry_taxes](https://docs.factuarea.com/ca/errors/suplido_line_cannot_carry_taxes): La línia de suplert porta càrrega pròpia: tipus d'IVA, retenció, recàrrec d'equivalència, descompte, clau de règim, causa d'exempció o producte/paquet. Un suplert no és una operació de l'emissor, així que repercutir-hi un impost seria tributar per un lliurament que no has fet, i lligar-lo a un producte mouria un estoc que mai no has venut. - [suplido_not_allowed_in_simplified_invoice](https://docs.factuarea.com/ca/errors/suplido_not_allowed_in_simplified_invoice): La factura és simplificada (F2) i una simplificada no identifica el destinatari. Sense destinatari identificat no hi ha a qui acreditar el pagament per compte d'altri, així que l'import no admet el tractament de suplert en aquest tipus de factura. - [suplido_requires_source_invoice_reference](https://docs.factuarea.com/ca/errors/suplido_requires_source_invoice_reference): La línia de suplert no informa `source_invoice_reference`, el número del justificant que el tercer va expedir a nom del client. Sense aquest justificant el pagament no s'acredita com a fet per compte d'altri i Hisenda el tractaria com a base imposable pròpia de l'emissor, amb el seu IVA repercutit. - [supplier_has_documents](https://docs.factuarea.com/ca/errors/supplier_has_documents): El proveïdor està referenciat per factures de compra registrades, i esborrar-lo deixaria aquestes despeses sense la part que les va emetre. - [supplier_not_found](https://docs.factuarea.com/ca/errors/supplier_not_found): L'identificador no resol a cap proveïdor de l'empresa autenticada. - [system_tax_default_modification_forbidden](https://docs.factuarea.com/ca/errors/system_tax_default_modification_forbidden): Els defaults dels impostos del catàleg compartit no es fixen sobre l'impost: el catàleg és global i la preferència és de la teva empresa. - [system_tax_immutable](https://docs.factuarea.com/ca/errors/system_tax_immutable): L'impost pertany al catàleg canònic AEAT que porta el producte. El seu tipus, el seu codi i el seu nom són fixos perquè totes les empreses comparteixin la mateixa referència fiscal. - [system_tax_immutable_field](https://docs.factuarea.com/ca/errors/system_tax_immutable_field): L'actualització toca un camp congelat en un impost del sistema; `error.param` diu quin. - [system_tax_undeletable](https://docs.factuarea.com/ca/errors/system_tax_undeletable): Els impostos del sistema formen part del catàleg fiscal compartit i no s'eliminen: esborrar-los trencaria els documents que els referencien. - [tax_applies_to_invalid](https://docs.factuarea.com/ca/errors/tax_applies_to_invalid): L'àmbit de l'impost queda fora del catàleg `sale`, `purchase`, `both`. - [tax_code_already_exists](https://docs.factuarea.com/ca/errors/tax_code_already_exists): Un altre impost del catàleg ja fa servir aquest codi, i el codi identifica l'impost sense ambigüitat. - [tax_id_already_exists](https://docs.factuarea.com/ca/errors/tax_id_already_exists): Un altre client de l'empresa ja té aquest NIF, i el NIF identifica la part sense ambigüitat dins d'una empresa. - [tax_id_required](https://docs.factuarea.com/ca/errors/tax_id_required): L'operació necessita el número d'identificació fiscal (NIF, CIF o NIE) de la part implicada i el registre no en té. - [tax_in_use](https://docs.factuarea.com/ca/errors/tax_in_use): L'impost està referenciat per documents, productes o proveïdors. Eliminar-lo deixaria documents històrics sense la seva referència fiscal. - [tax_inactive_cannot_be_default](https://docs.factuarea.com/ca/errors/tax_inactive_cannot_be_default): Un impost desactivat no pot quedar com a default, ni global ni per tipus de document: seria un default ocult que cap formulari pot triar. - [tax_not_found](https://docs.factuarea.com/ca/errors/tax_not_found): L'identificador no correspon a cap impost del catàleg accessible per a aquesta empresa. - [tax_report_not_found](https://docs.factuarea.com/ca/errors/tax_report_not_found): L'identificador no resol a cap declaració de l'empresa autenticada. - [tax_report_type_invalid](https://docs.factuarea.com/ca/errors/tax_report_type_invalid): El tipus de declaració queda fora del catàleg `modelo_303`, `modelo_347`, `modelo_130`. - [tax_type_invalid](https://docs.factuarea.com/ca/errors/tax_type_invalid): El tipus d'impost queda fora del catàleg `vat`, `retention`, `surcharge`, `other`. - [timeout_seconds_out_of_range](https://docs.factuarea.com/ca/errors/timeout_seconds_out_of_range): `timeout_seconds` queda fora del rang d'1 a 30 segons. - [too_many_auth_failures](https://docs.factuarea.com/ca/errors/too_many_auth_failures): Van arribar massa intents fallits d'autenticació des de la mateixa adreça, així que queda bloquejada temporalment per frenar els intents d'endevinar credencials. - [too_many_custom_headers](https://docs.factuarea.com/ca/errors/too_many_custom_headers): L'endpoint declara més de 20 capçaleres personalitzades. - [unknown_filter](https://docs.factuarea.com/ca/errors/unknown_filter): Un llistat va rebre un filtre que no coneix. Els parsers canònics de v1 reporten això com a `parameter_unknown`; aquest codi sobreviu per als endpoints encara sense migrar. - [unsupported_api_version](https://docs.factuarea.com/ca/errors/unsupported_api_version): La capçalera `Factuarea-Version` està ben formada però anomena una versió fora del conjunt suportat. - [unsupported_format](https://docs.factuarea.com/ca/errors/unsupported_format): El format demanat no està disponible per a aquest model: no tota declaració produeix totes les sortides. - [unsupported_media_type](https://docs.factuarea.com/ca/errors/unsupported_media_type): Una petició amb body va declarar un `Content-Type` diferent de `application/json`. - [verifactu_already_submitted](https://docs.factuarea.com/ca/errors/verifactu_already_submitted): La factura ja té el seu registre d'alta. Existeix exactament una alta per factura, així que una segona trencaria la idempotència de la cadena. - [verifactu_mode_invalid](https://docs.factuarea.com/ca/errors/verifactu_mode_invalid): El mode queda fora del catàleg `verifactu` / `no_verifactu`. - [verifactu_not_eligible](https://docs.factuarea.com/ca/errors/verifactu_not_eligible): La factura no es pot registrar ara mateix a l'AEAT: l'empresa no està en mode VeriFactu, no té certificat actiu, o el certificat està revocat o emès per a un altre NIF. - [verifactu_record_not_found](https://docs.factuarea.com/ca/errors/verifactu_record_not_found): L'identificador no correspon a cap registre de facturació de l'empresa autenticada. - [verifactu_transmission_failed](https://docs.factuarea.com/ca/errors/verifactu_transmission_failed): L'enviament del registre a l'AEAT no es va completar: l'endpoint era inaccessible o va respondre amb una incidència. - [webhook_delivery_not_found](https://docs.factuarea.com/ca/errors/webhook_delivery_not_found): L'identificador no correspon a cap intent de lliurament, o el lliurament queda fora de la finestra de retenció de l'històric. - [webhook_endpoint_degraded](https://docs.factuarea.com/ca/errors/webhook_endpoint_degraded): L'endpoint està degradat després de fallades repetides de lliurament, així que els pings de prova es rebutgen mentre segueixi en aquest estat. - [webhook_endpoint_not_found](https://docs.factuarea.com/ca/errors/webhook_endpoint_not_found): L'identificador no resol a cap endpoint de webhook de l'empresa autenticada. - [webhook_secret_recently_rotated](https://docs.factuarea.com/ca/errors/webhook_secret_recently_rotated): El secret de signatura es va rotar fa menys de cinc minuts. La finestra de gràcia permet que el teu receptor accepti tots dos secrets durant el canvi; rotar un altre cop dins d'ella invalidaria signatures encara en vol. - [Resum dels SDKs](https://docs.factuarea.com/ca/sdks): SDKs oficials de TypeScript i PHP per a l'API de Factuarea — instal·la @factuarea/sdk o factuarea/factuarea-php i obtén reintents, idempotència, paginació per cursor, errors tipats i verificació de webhooks de sèrie. - [PHP](https://docs.factuarea.com/ca/sdks/php): Instal·la factuarea/factuarea-php amb Composer, autentica't i crea la teva primera factura. PSR-4, basat en Guzzle, PHP 8.2+. - [TypeScript](https://docs.factuarea.com/ca/sdks/typescript): Instal·la @factuarea/sdk per a Node.js, autentica't i crea la teva primera factura. ESM + CommonJS dual, declaracions de tipus completes, Node 20+. - [Llistar tots els saldos d'absències](https://docs.factuarea.com/ca/api-reference/absence-balances/public-api.v1.absence-balances.list): Llista els saldos d'absències de la teva empresa amb paginació per cursor. Cada saldo són els dies meritats, arrossegats i consumits d'un empleat per a un tipus d'absència en un any donat, amb els `available_days` resultants. Admet filtrar per `employee_id` (UUID v7), `absence_type_id` (UUID v7) i `year`. Els imports de dies són cadenes decimals exactes. - [Obtenir un saldo d'absències](https://docs.factuarea.com/ca/api-reference/absence-balances/public-api.v1.absence-balances.show): Obtén un únic saldo d'absències pel seu `id` (UUID v7), inclosos els seus dies meritats, arrossegats, consumits i disponibles per a l'empleat, tipus d'absència i any. Un saldo pertanyent a una altra empresa retorna 404 `absence_balance_not_found` (anti-enumeració). - [Obtenir el calendari d'absències de l'equip](https://docs.factuarea.com/ca/api-reference/absence-calendar/public-api.v1.absence-calendar.show): Retorna el calendari mensual d'absències del teu equip per a un `year` i `month` donats: cada empleat actiu amb les seves absències aprovades d'aquell mes (cadascuna acolorida pel seu tipus d'absència) i els festius que apliquen, mantinguts separats de les absències. Opcionalment acotat a un únic `employee_id` (UUID v7). Un recurs computat: exposa `employee_id` per membre, mai un `id`. - [Arxivar una política d'absències](https://docs.factuarea.com/ca/api-reference/absence-policies/public-api.v1.absence-policies.archive): Arxiva una política d'absències (transició `active` → `archived`), retirant-la de l'ús però conservant-la. Sense cos de la petició. Retorna 422 si ja està arxivada. Reversible mitjançant desarxivar. - [Assignar una política a empleats](https://docs.factuarea.com/ca/api-reference/absence-policies/public-api.v1.absence-policies.assign): Assigna la política d'absències a un o més empleats. `employee_ids` (una llista no buida d'UUID v7, cadascun pertanyent a la teva empresa) és obligatori; un empleat desconegut retorna 422. Retorna la política amb el seu recompte d'empleats assignats actualitzat. - [Llistar els empleats assignats a una política](https://docs.factuarea.com/ca/api-reference/absence-policies/public-api.v1.absence-policies.assignments): Llista els empleats assignats a aquesta política d'absències (el seu `employee_id` UUID v7 i el seu nom), com una llista plana sota `{ "data": [ … ] }`. - [Configurar l'arrossegament de fi d'any d'una política](https://docs.factuarea.com/ca/api-reference/absence-policies/public-api.v1.absence-policies.carryover): Configura quant de saldo sense usar s'arrossega a fi d'any per a aquesta política d'absències. `carryover_type` (`none`/`capped`/`unlimited`) és obligatori; `carryover_max_days` és obligatori i positiu només quan `carryover_type` és `capped`. Els opcionals `carryover_expiry_month` (1..12) i `carryover_expiry_day` fixen quan caduca el saldo arrossegat. Una política pertanyent a una altra empresa retorna 404 `absence_policy_not_found` (anti-enumeració). Retorna la política actualitzada. - [Crear una política d'absències](https://docs.factuarea.com/ca/api-reference/absence-policies/public-api.v1.absence-policies.create): Crea una política d'absències per a l'empresa autenticada (resolta des de l'API key, mai des del payload). `name`, `allowance_type` (`limited`/`unlimited`) i `accrual_method` (`annual`/`monthly`) són obligatoris; `allowance_days` és obligatori i positiu només quan `allowance_type` és `limited`. `absence_type_ids` és la llista d'UUID (v7) de tipus d'absència que la política cobreix (pot estar buida); un tipus pertanyent a una altra empresa retorna 422. Retorna la política creada amb el seu `id` generat (UUID v7). - [Llistar totes les polítiques d'absències](https://docs.factuarea.com/ca/api-reference/absence-policies/public-api.v1.absence-policies.list): Llista les polítiques d'absències de la teva empresa amb paginació per cursor. Admet filtrar per `status` (`active`/`archived`) i `accrual_method` (`annual`/`monthly`), més una `search` de text lliure sobre el nom de la política. - [Obtenir una política d'absències](https://docs.factuarea.com/ca/api-reference/absence-policies/public-api.v1.absence-policies.show): Obtén una única política d'absències pel seu `id` (UUID v7), inclosos els UUID dels seus tipus d'absència associats i el recompte d'empleats assignats. Una política pertanyent a una altra empresa retorna 404 `absence_policy_not_found` (anti-enumeració). - [Desarxivar una política d'absències](https://docs.factuarea.com/ca/api-reference/absence-policies/public-api.v1.absence-policies.unarchive): Desarxiva una política d'absències (transició `archived` → `active`), tornant-la a l'ús. Sense cos de la petició. Retorna 422 si ja està activa. - [Desassignar una política d'empleats](https://docs.factuarea.com/ca/api-reference/absence-policies/public-api.v1.absence-policies.unassign): Retira l'assignació de la política d'absències d'un o més empleats. `employee_ids` (una llista no buida d'UUID v7) és obligatori; retirar una assignació que no existeix és un no-op. Retorna la política amb el seu recompte d'empleats assignats actualitzat. - [Actualitzar una política d'absències](https://docs.factuarea.com/ca/api-reference/absence-policies/public-api.v1.absence-policies.update): Actualitza parcialment una política d'absències: només es canvien els camps presents en el payload; els omesos conserven el seu valor actual. Quan es proporciona `absence_type_ids` reemplaça per complet els tipus associats. Retorna la política actualitzada. - [Aprovar una sol·licitud d'absència](https://docs.factuarea.com/ca/api-reference/absence-requests/public-api.v1.absence-requests.approve): Aprova una sol·licitud d'absència pendent (transició `pending` → `approved`), consumint el saldo de l'empleat. Sense cos de la petició (s'admet una `note` opcional). Un revisor no pot aprovar la sol·licitud que ell mateix va crear (422). Retorna la sol·licitud actualitzada. - [Cancel·lar una sol·licitud d'absència](https://docs.factuarea.com/ca/api-reference/absence-requests/public-api.v1.absence-requests.cancel): Cancel·la una sol·licitud d'absència. Si estava aprovada, el saldo consumit es retorna. Sense cos de la petició. Una sol·licitud pertanyent a una altra empresa retorna 404 `absence_request_not_found` (anti-enumeració). Retorna la sol·licitud actualitzada. - [Crear una sol·licitud d'absència](https://docs.factuarea.com/ca/api-reference/absence-requests/public-api.v1.absence-requests.create): Crea una sol·licitud d'absència per a l'empresa autenticada (resolta des de l'API key, mai des del payload). `employee_id` (UUID v7) és obligatori — una API key actua com un sistema, així que s'ha d'indicar l'empleat destí. `absence_type_id` (UUID v7) i el rang `start_date`/`end_date` (`YYYY-MM-DD`, fi igual o posterior a l'inici) són obligatoris; `note` és opcional. La quantitat sol·licitada es computa en dies laborables menys els festius aplicables. Si el tipus d'absència no requereix aprovació, s'autoaprova i consumeix el saldo. Retorna la sol·licitud creada amb el seu `id` generat (UUID v7). - [Llistar totes les sol·licituds d'absència](https://docs.factuarea.com/ca/api-reference/absence-requests/public-api.v1.absence-requests.list): Llista les sol·licituds d'absència de la teva empresa amb paginació per cursor. Admet filtrar per `employee_id` (UUID v7), `absence_type_id` (UUID v7), `status` (`pending`/`approved`/`rejected`/`cancelled`) i per rang de dates (`from`/`to`, `YYYY-MM-DD`). - [Rebutjar una sol·licitud d'absència](https://docs.factuarea.com/ca/api-reference/absence-requests/public-api.v1.absence-requests.reject): Rebutja una sol·licitud d'absència pendent (transició `pending` → `rejected`). Es requereix un `reason` (422 sense ell); rebutjar ni consumeix ni allibera saldo. Retorna la sol·licitud actualitzada. - [Obtenir una sol·licitud d'absència](https://docs.factuarea.com/ca/api-reference/absence-requests/public-api.v1.absence-requests.show): Obtén una única sol·licitud d'absència pel seu `id` (UUID v7), inclosos el seu tipus, rang de dates, quantitat sol·licitada, estat del cicle de vida i camps de revisió. Una sol·licitud pertanyent a una altra empresa retorna 404 `absence_request_not_found` (anti-enumeració). - [Arxivar un tipus d'absència](https://docs.factuarea.com/ca/api-reference/absence-types/public-api.v1.absence-types.archive): Arxiva un tipus d'absència (transició `active` → `archived`), retirant-lo de l'ús però conservant-lo. Sense cos de la petició. Retorna 422 si ja està arxivat. Reversible mitjançant desarxivar. - [Crear un tipus d'absència](https://docs.factuarea.com/ca/api-reference/absence-types/public-api.v1.absence-types.create): Crea un tipus d'absència per a l'empresa autenticada (resolta des de l'API key, mai des del payload). `name`, `is_paid`, `requires_approval`, `measurement_unit` (`days`/`hours`), `color` (hex `#RRGGBB`) i `visibility` (`everyone`/`managers_only`) són tots obligatoris. Retorna el tipus creat amb el seu `id` generat (UUID v7). - [Llistar tots els tipus d'absència](https://docs.factuarea.com/ca/api-reference/absence-types/public-api.v1.absence-types.list): Llista els tipus d'absència de la teva empresa amb paginació per cursor. Admet filtrar per `status` (`active`/`archived`) i `measurement_unit` (`days`/`hours`), més una `search` de text lliure sobre el nom del tipus. - [Obtenir un tipus d'absència](https://docs.factuarea.com/ca/api-reference/absence-types/public-api.v1.absence-types.show): Obtén un únic tipus d'absència pel seu `id` (UUID v7). Un tipus pertanyent a una altra empresa retorna 404 `absence_type_not_found` (anti-enumeració). - [Desarxivar un tipus d'absència](https://docs.factuarea.com/ca/api-reference/absence-types/public-api.v1.absence-types.unarchive): Desarxiva un tipus d'absència (transició `archived` → `active`), tornant-lo a l'ús. Sense cos de la petició. Retorna 422 si ja està actiu. - [Actualitzar un tipus d'absència](https://docs.factuarea.com/ca/api-reference/absence-types/public-api.v1.absence-types.update): Actualitza parcialment un tipus d'absència: només es canvien els camps presents en el payload; els omesos conserven el seu valor actual. Retorna el tipus actualitzat. - [Crear una API key](https://docs.factuarea.com/ca/api-reference/account/public-api.v1.account.api_keys.create): Crea una API key nova i retorna el seu `secret` en clar exactament una vegada —desa'l ara, no es podrà recuperar després. Sol·licitar un scope per sobre del pla del titular o fora del catàleg retorna 422. Passa `environment: test` per encunyar una clau de sandbox (`fact_test_`) sense efectes al món real; omet-lo per a una clau live (`fact_live_`). - [Llistar les teves API keys](https://docs.factuarea.com/ca/api-reference/account/public-api.v1.account.api_keys.list): Llista les API keys de l'empresa autenticada amb paginació per cursor. Cada clau exposa el seu `prefix`, `scopes`, `tier`, `environment` (`live`/`test`) i timestamps de cicle de vida. El secret en clar no es retorna mai: es mostra una vegada, a la creació o la rotació. - [Revocar una API key](https://docs.factuarea.com/ca/api-reference/account/public-api.v1.account.api_keys.revoke): Revoca una API key immediatament i irreversiblement. Les peticions posteriors autenticades amb aquella clau fallen amb 401. Pots revocar la clau en ús actualment —fer-ho talla el teu propi accés. Revocar una clau d'una altra empresa retorna 404 `api_key_not_found`. - [Rotar el secret d'una API key](https://docs.factuarea.com/ca/api-reference/account/public-api.v1.account.api_keys.rotate_secret): Invalida el secret actual d'una API key immediatament, genera un `prefix` + `secret` nous, i retorna el nou secret en clar exactament una vegada. Qualsevol petició feta amb el secret anterior deixa d'autenticar a l'instant. Irreversible. - [Recuperar una API key](https://docs.factuarea.com/ca/api-reference/account/public-api.v1.account.api_keys.show): Recupera una sola API key de l'empresa autenticada pel seu `id` (UUID v7). El secret en clar no s'inclou mai. Una clau que pertany a una altra empresa retorna 404 `api_key_not_found` (anti-enumeració). - [Obtenir els detalls de facturació del compte](https://docs.factuarea.com/ca/api-reference/account/public-api.v1.account.billing): Retorna el resum de facturació per subscripció de l'empresa autenticada: subscripció del pla base (estat, prova, fi del període actual, canvi de pla pendent), subscripció de places de gestoria (quantitat, empreses gestionades actives, cost per plaça amb IVA, total recurrent, propera factura) i mètode de pagament per defecte. Les empreses gestionades (pla `gestionada`) reben `managed: true` sense les dades de facturació del mestre. Els imports van en cèntims sencers; els imports no resolts són `null`, mai un 0 enganyós. - [Llista les plantilles de personalització disponibles](https://docs.factuarea.com/ca/api-reference/account/public-api.v1.account.personalization.templates): Llista les plantilles PDF disponibles per al pla del compte (segons el pla) més el format acceptat per a l'`accent_color`. Fes-ho servir per descobrir quins slugs de `pdf_template` i colors es poden fixar via `PATCH /v1/account/personalization`. - [Actualitza la personalització del compte](https://docs.factuarea.com/ca/api-reference/account/public-api.v1.account.personalization.update): Fixa en una sola actualització parcial l'idioma d'emissió de factures, la plantilla PDF i el color d'accent de l'empresa; els camps omesos mantenen el seu valor. `language` és un de `es`, `en`, `ca`; `pdf_template` és un slug del catàleg `PdfTemplate`; `accent_color` és un color hex `#RRGGBB`. Retorna el recurs `Account` actualitzat. - [Obtenir els detalls del compte](https://docs.factuarea.com/ca/api-reference/account/public-api.v1.account.show): Endpoint de compte estil Stripe: retorna l'empresa autenticada juntament amb el seu pla, els seus add-ons i les metadades de l'API key en ús (environment, scopes). Fes-lo servir per introspeccionar què pot fer la clau actual. - [Verificar el compte contra el cens de l'AEAT](https://docs.factuarea.com/ca/api-reference/account/public-api.v1.account.verify_census): Comprova el parell nom + NIF persistit de l'empresa contra el cens de l'AEAT (VNifV2) per anticipar rebutjos VeriFactu 4104. Sense cos de petició: l'endpoint verifica sempre les dades fiscals persistides del compte. Fail-open — si l'AEAT no està disponible, la crida retorna 200 amb `status: unavailable`. Les claus de prova (`fact_test_`) retornen estats deterministes segons el NIF màgic sense contactar amb l'AEAT. - [Llistar la línia temporal d'activitat del client](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.activities): Retorna la línia de temps d'auditoria d'un client combinant els seus propis esdeveniments de domini més els esdeveniments de factura, pressupost, albarà, proforma i factura de compra que el referencien. Paginada amb els query params page i per_page (50 per defecte). - [Crear clients en bloc](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.bulk_create): Crea fins a 500 clients en una crida, cada entrada un payload de client complet. Amb `dry_run=true` valida cada fila sense persistir i retorna una classificació per fila (`results[]`, incloent-hi `external_id`/`tax_id` duplicat i un avís no bloquejant de cens AEAT); amb `dry_run=false` crea només les files vàlides i reporta la resta a `failures[]`. Retorna la forma `BulkCreateResult`. - [Elimina diversos clients de forma massiva](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.bulk_delete): Elimina fins a 200 clients en una sola petició. Retorna un `BulkPartialSuccessResult` amb els comptadors `total`, `successful` i `failed` més una llista `failures` (`id` + `error_code` + `error_message` en castellà); els clients amb documents associats es reporten a `failures`. - [Crear un client](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.create): Crea un nou client per a la teva empresa. L'objecte retornat inclou el `uuid` generat que hauries de desar per a operacions posteriors. - [Elimina un client](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.delete): Elimina un client. Retorna 422 si el client està referenciat per algun document (factura, pressupost, etc.). - [Cercar un client per external ID](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.find_by_external_id): Cerca un client pel seu `external_id` (enviat al body JSON), la clau d'integració que el mapeja a un registre en un sistema de tercers (ERP/CRM/e-commerce). Diferent del `tax_id` fiscal. Retorna el client coincident o 404 si cap client fa servir aquest external_id dins de la teva empresa. - [Cercar un client per tax ID](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.find_by_tax_id): Cerca un client pel seu identificador fiscal espanyol (NIF/CIF/NIE). Retorna el client coincident o 404 si cap client fa servir aquest tax_id dins de la teva empresa. - [Importar clients des d'un fitxer](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.import): Importa clients en massa des d'un arxiu CSV/XLSX com a `multipart/form-data`; el processament és síncron i la resposta porta el resultat per fila. Puja primer amb `dry_run=true` per validar sense persistir, corregeix els `failures[]` reportats, i torna a pujar amb `dry_run=false` per crear només les files vàlides. `mapping` mapeja les capçaleres de les teves columnes als camps destí (`name` i `tax_id` són obligatoris). Descarrega la plantilla de capçaleres des de `GET /v1/clients/import-template`. ```json { "dry_run": true, "mapping": { "Nombre": "name", "CIF": "tax_id", "Email": "email" } } ``` Límits: arxiu ≤10 MB i menys de 200 files; un arxiu més gran retorna 422 `client_import_too_large`. - [Descarregar la plantilla d'importació de clients](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.import_template): Descarrega la plantilla CSV (capçaleres en castellà + dues files d'exemple) per omplir-la abans de pujar-la a `POST /v1/clients/import`. El contingut és estàtic i no accedeix a dades de l'empresa. Retorna un stream `text/csv` com a adjunt. - [Llistar tots els clients](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.list): Llista els teus clients amb paginació per cursor. Admet filtratge per `is_active`, `created_at[gte|lte]` i `name[in]`. - [Cerca clients](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.search): Cerca clients per consulta de text lliure contra `name`, `tax_id`, `vat_id`, `email` i `phone`. Retorna un array pla (sense paginació) limitat a 50 resultats. - [Obtenir un client](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.show): Obté un client pel seu `uuid`. Retorna 404 si el client no existeix o pertany a una altra empresa. - [Obtenir estadístiques del client](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.stats): KPIs agregats de l'empresa autenticada: nombre total de clients, nombre d'actius, nombre amb factures de venda, nombre amb pressupostos i totals per tipus de document. Retornat com a `{ "data": ClientStats }`. - [Actualitzar un client](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.update): Actualitza un client. Només es modifiquen els camps inclosos al payload; els camps omesos conserven els seus valors previs. - [Verificar un client contra el cens de l'AEAT](https://docs.factuarea.com/ca/api-reference/clients/public-api.v1.clients.verify_census): Comprova el parell nom + NIF d'un tercer (el destinatari d'una factura) contra el cens de l'AEAT (VNifV2) per anticipar rebutjos VeriFactu 1239 abans de facturar. Sense estat i informatiu: no es persisteix res al client. Fail-open — si l'AEAT no està disponible, la crida retorna 200 amb `status: unavailable`. Les claus de prova (`fact_test_`) retornen estats deterministes segons el NIF màgic sense contactar amb l'AEAT. - [Activar una empresa gestionada](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.activate): Reactiva una empresa gestionada prèviament desactivada (`inactive`). L'activació està condicionada per un càrrec atòmic per seat: en mode live el seat prorratejat es cobra de manera síncrona i l'empresa només passa a `active` si el càrrec té èxit. Sense mètode de pagament registrat retorna 402, i un pla sense el mòdul de gestoria retorna 403. Les claus de trial, enterprise i test se salten el càrrec. - [Activar diverses empreses gestionades](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.activate_batch): Reactiva diverses empreses gestionades desactivades (`inactive`) en una operació, cobrant els seats prorratejats combinats en una única factura. Passa `company_ids`. El gate és atòmic: cada empresa es valida (propietat i estat `inactive`) abans de qualsevol càrrec, així que si una és no vàlida es rebutja tot el lot sense cobrar ni activar-ne cap. - [Crear una API key filla](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.api_keys.create): Crea una API key amb scope en una de les teves empreses gestionades i retorna el seu `secret` en clar exactament una vegada —desa'l ara, no es podrà recuperar després. Els scopes sol·licitats han de ser un subconjunt dels scopes de la clau que crida; sol·licitar un scope que la clau pare no té retorna 422 (sense estrenyiment silenciós). - [Llistar les API keys filles](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.api_keys.list): Llista les API keys d'una de les teves empreses gestionades amb paginació per cursor, incloent-hi les claus revocades per a auditoria. El secret en clar no es retorna mai. Una empresa no gestionada pel teu tenant mestre retorna 404. - [Revocar una API key filla](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.api_keys.revoke): Revoca una API key filla immediatament i irreversiblement, deixant-la inutilitzable. Les peticions posteriors autenticades amb aquella clau fallen amb 401. Una empresa no gestionada pel teu tenant mestre retorna 404. - [Rotar el secret d'una API key filla](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.api_keys.rotate_secret): Invalida el secret actual d'una API key filla immediatament, genera un `prefix` + `secret` nous, i retorna el nou secret en clar exactament una vegada. Qualsevol petició feta amb el secret anterior deixa d'autenticar a l'instant. Irreversible. Una empresa no gestionada pel teu tenant mestre retorna 404. - [Recuperar una API key filla](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.api_keys.show): Recupera una sola API key d'una de les teves empreses gestionades pel seu `id` (UUID v7). El secret en clar no s'inclou mai. Una clau que no pertany a una empresa que gestiones retorna 404 `api_key_not_found` (anti-enumeració). - [Crear una empresa gestionada](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.create): Registra una nova empresa gestionada (un subcompte fill) sota el teu tenant mestre —el model de gestoria. `name` i `tax_id` són obligatoris, i `tax_id` ha de ser únic entre les empreses que gestiones (un duplicat retorna 409). En mode live el càrrec prorratejat per seat condiciona la creació: sense mètode de pagament registrat o amb un càrrec fallit la crida retorna 402 i no es crea res. Fes servir `GET /v1/companies/seat-charge-preview` per anticipar el cost; les claus de test se salten el càrrec. - [Consultar l'estat de creació d'una empresa gestionada](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.creation_status): Consulta el cicle de vida d'aprovisionament d'una empresa gestionada. Retorna `provisioning_status` (`pending`, `awaiting_payment`, `provisioning`, `active`, `failed`). `payment_setup_url` està present només mentre `awaiting_payment` i apunta a l'onboarding de mètode de pagament del tenant mestre; `failed_reason` està present només quan l'aprovisionament ha `failed`. Les claus de test mouen la filla a `active` directament. - [Desactivar una empresa gestionada](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.deactivate): Desactiva una empresa gestionada, movent-la de `active` a `inactive`: passa a ser no operativa però les seves dades es conserven i el canvi és reversible (reactiva-la més tard pagant el seu seat). No s'aplica cap càrrec; en lloc d'això s'emet un crèdit prorratejat del seat best-effort pel temps no usat. - [Arxivar una empresa gestionada](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.delete): Arxiva una empresa gestionada, movent-la a l'estat `archived` perquè ja no accepti operacions. La fila de l'empresa i el seu històric es conserven. L'arxivat pot quedar bloquejat per regles de negoci (retorna 422 `business_rule_violation`). Una empresa no gestionada pel teu tenant mestre retorna 404. - [Llistar les teves empreses gestionades](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.list): Llista les empreses gestionades pel teu tenant mestre amb paginació per cursor. Per defecte només es retornen les empreses `active` i `inactive`; passa `status` (`active`, `inactive`, `archived`) per filtrar —`status=archived` és la manera opt-in de mostrar les empreses arxivades. Només es retornen les teves pròpies filles. - [Previsualitza el càrrec per plaça d'afegir una empresa](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.seat_charge_preview): Previsualitza l'import prorratejat per seat d'afegir o activar empreses gestionades, calculat a partir de la propera factura de Stripe del tenant mestre, sense cobrar. Fes servir `count` (≥1) per previsualitzar un lot, o `company_ids` per a una previsualització conscient de la cobertura: les empreses encara cobertes per al període actual costen `0` (`already_covered: true`). `amount` està en les unitats menors de la moneda; `requires_payment_method` és `true` quan no hi ha cap mètode de pagament registrat. - [Recuperar una empresa gestionada](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.show): Recupera una sola empresa gestionada pel seu `id` (UUID v7). Una empresa no gestionada pel teu tenant mestre retorna 404 `company_not_found` (anti-enumeració). - [Actualitzar una empresa gestionada](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.update): Actualitza el perfil d'una empresa gestionada (`name`, `business_name`, camps d'adreça, `email`, `phone`). El `tax_id` és immutable després de la creació (enviar-lo retorna 422) i `country_aeat_zone` es deriva de l'adreça. Actualització parcial: els camps omesos mantenen el seu valor; envia `""` per buidar un camp. - [Verificar la creació d'una empresa gestionada](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.companies.verify_creation): Concilia i avança l'aprovisionament d'una empresa gestionada contra la subscripció del tenant mestre. Sense cos de petició; idempotent. Mentre `awaiting_payment`, un cop el mestre tingui un mètode de pagament registrat, la filla es cobra el seat prorratejat i passa a `active`; en cas contrari es queda a `awaiting_payment` sense error. Retorna el recurs d'estat de creació. - [Obtenir el resum consolidat de compliment de plantilla](https://docs.factuarea.com/ca/api-reference/companies/public-api.v1.gestoria.workforce_summary): Retorna el panell consolidat de compliment del control horari de tota la teva cartera gestionada: una fila per empresa gestionada `active`, cadascuna projectada des del darrer tancament mensual d'aquesta empresa sense recomputar — si el període actual (el darrer tancable) està tancat, el seu estat (`closed`/`reopened`), el darrer període tancat (`last_closed_year`/`last_closed_month`), i els agregats `total_balance_minutes`, `total_overtime_minutes` i `employee_count`. D'àmbit master: la cartera es resol des de la teva API key, mai des del payload, i només apareixen les teves pròpies empreses filles. A diferència dels endpoints per empresa amb `X-Active-Profile`, aquest agrega entre empreses filles en una sola crida. Es retorna com a `{ "data": [ConsolidatedWorkforce, ...] }`. - [Eliminació massiva d'albarans](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.bulk_delete): Elimina diversos albarans en una sola petició. El cos pren un array `ids` de `uuid`s. Retorna un `BulkPartialSuccessResult` amb els comptadors `total`, `successful`, `failed` i una llista `failures` (`id` + `error_code` + `error_message` en castellà) per als que no s'han pogut eliminar (p. ex. signats o facturats). Admet `Idempotency-Key` per a reintents segurs. - [Descarregar en bloc els PDF d'albarans](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.bulk_pdf): Empaqueta els PDF de fins a 50 albarans (per id) en un únic ZIP. Els ids no trobats o sense PDF generable no aborten la petició: el ZIP porta només els vàlids i els comptadors per recurs viatgen a les capçaleres de resposta `X-Bulk-*`. - [Enviar albarans en bloc](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.bulk_send): Envia fins a 200 albarans per email (encuat) en una sola crida, reutilitzant la ruta d'enviament individual per id. Retorna un `BulkPartialSuccessResult` amb els comptadors `total`, `successful` i `failed` més una llista `failures` (`id` + `error_code` + `error_message` en castellà) per cada albarà que no s'ha pogut enviar (no trobat, estat no enviable o sense destinatari resoluble). - [Canviar en bloc l'estat d'albarans](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.bulk_status): Transiciona fins a 50 albarans (per id) a un estat del conjunt tancat `[delivered, cancelled]`, cadascun a través del guard d'estat del document. Retorna un `BulkPartialSuccessResult`; els albarans la transició dels quals es rebutja (no trobats o no transicionables) tornen a `failures[]`. - [Anul·lar un albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.cancel): Transiciona un albarà a l'estat `cancelled`. Reemplaçament REST canònic de l'obsolet `POST /change_status`. Retorna 409 `invalid_status_transition` si l'albarà no es pot cancel·lar (p. ex. ja facturat). Admet `Idempotency-Key` per a reintents segurs. - [Convertir albarà en factura](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.convert): Converteix un albarà en una factura de venda. L'albarà passa a `invoiced` amb `converted_to_id` emplenat i la nova factura es retorna a `data`. Només s'admet `target=invoice`. - [Crear un albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.create): Crea un nou albarà en estat `draft`. Els albarans registren les mercaderies enviades a un client i després es poden convertir en factures. - [Elimina un albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.delete): Elimina un albarà. Només es poden eliminar els albarans `draft` sense número assignat; qualsevol altre estat retorna 409 `invalid_status_transition`. - [Duplicar un albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.duplicate): Crea un nou albarà en esborrany copiant línies, client i metadades. - [Cercar un albarà per external ID](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.find_by_external_id): Cerca un únic albarà pel seu `external_id` (enviat al body JSON), la clau d'integració que el mapeja a un registre en un sistema de tercers (ERP/CRM/e-commerce). Retorna l'albarà coincident o 404 `delivery_note_not_found` si cap albarà fa servir aquest external_id dins de la teva empresa. - [Llistar tots els albarans](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.list): Llista els teus albarans amb paginació per cursor. - [Marca l'albarà com a lliurat](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.mark_delivered): Transiciona un albarà a l'estat `delivered` (públic `sent`). Reemplaçament REST canònic de l'obsolet `POST /change_status`. Retorna 409 `invalid_status_transition` si l'albarà no pot transicionar. Admet `Idempotency-Key` per a reintents segurs. - [Descarregar el PDF de l'albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.pdf): Descarrega la representació en PDF d'un albarà. Retorna el flux binari del PDF (`application/pdf`). Passa `?download=1` per a `Content-Disposition: attachment` (descàrrega del fitxer); en cas contrari es serveix `inline`. La resposta porta un `ETag`; reenvia'l mitjançant `If-None-Match` per rebre `304 Not Modified` quan el document no hagi canviat. - [Obtenir l'enllaç públic d'un albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.public_link.get): Retorna l'estat de l'enllaç públic per compartir d'un albarà: `url` (absoluta, llesta per enviar al client), `enabled`, `expires_at` (`null` = sense límit) i `max_days` (màxim imposat pel pla en estendre l'enllaç). - [Actualitzar l'enllaç públic d'un albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.public_link.update): Activa/desactiva l'enllaç públic compartit d'un albarà o canvia'n la caducitat. Retorna 422 `expiry_exceeds_max_days` si la caducitat sol·licitada supera el `max_days` imposat pel pla. Admet `Idempotency-Key` per a reintents segurs. - [Envia un albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.send): Envia un albarà al client per email. Utilitza l'email registrat tret que se sobreescrigui al payload. - [Obtenir un albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.show): Obté un albarà pel seu `uuid`. - [Signar un albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.sign): Registra una signatura manuscrita en un albarà, típicament capturada del destinatari en el lliurament. La signatura ha de ser un PNG codificat en base64 (≤2 MB); altres formats retornen 422. Signar fixa `signed_at`/`signed_by` però no canvia l'estat. El log d'auditoria de signatures reté PII del destinatari hashejada durant 5 anys (LSSI-CE espanyola); fes servir l'endpoint `signature-audits/{auditId}/forget` per atendre una sol·licitud de supressió RGPD. - [Oblidar la PII de la signatura de l'albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.signature_audits.forget): RGPD Art. 17 (dret de supressió) — elimina les dades personals (nom/DNI del destinatari) d'una entrada del log d'auditoria de signatures conservant la traça d'auditoria no-PII exigida per al compliment LSSI-CE. El `{auditId}` és la clau primària numèrica del registre d'auditoria de signatura. - [Recupera les estadístiques d'albarans](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.stats): Retorna KPIs agregats dels teus albarans: total de documents, import acumulat, desglossament per estat, nombre pendent de signatura i nombre convertit a factura aquest mes. - [Llistar estats d'albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.statuses): Llista el catàleg tancat d'estats d'albarà (`draft`, `delivered`, `invoiced`, `cancelled`) amb les seves etiquetes públiques i colors. Fes-lo servir per omplir filtres o selectors d'estat en lloc de codificar valors a mà. El camp `data` de la resposta és un array d'elements `{ value, label, color }`. - [Actualitzar un albarà](https://docs.factuarea.com/ca/api-reference/delivery-notes/public-api.v1.delivery_notes.update): Actualitza un albarà en esborrany. Un cop signat o facturat, l'albarà esdevé immutable. - [Llista el registre de peticions de la teva API](https://docs.factuarea.com/ca/api-reference/developers/public-api.v1.developers.request_logs.list): Inspecciona les peticions que la teva pròpia integració ha fet contra aquesta API, de més recent a més antiga, per depurar-la sense obrir un tiquet de suport: què has cridat, què t'ha retornat, quant ha trigat i, quan una crida ha fallat, l'error que ha retornat. Acotat a l'empresa autenticada. Les files es purguen als 30 dies, així que això és una finestra de depuració, no un rastre d'auditoria. - [Consulta un registre de petició de l'API](https://docs.factuarea.com/ca/api-reference/developers/public-api.v1.developers.request_logs.show): Consulta una única petició de la teva pròpia integració pel `request_id` que l'API ha retornat al header `X-Request-Id` d'aquella resposta — l'identificador que ja tens a mà quan una crida s'ha portat malament, i el que cal citar en una petició de suport. És una cadena opaca `req_…`, no un UUID v7. El cos porta els mateixos camps que el llistat. - [Resumeix el lliurament d'email per document](https://docs.factuarea.com/ca/api-reference/emails/public-api.v1.emails.indicators): Respon a «ha sortit l'email d'aquests documents?» per a un lot sencer de cop, en lloc de paginar els enviaments de cadascun: per document, quants emails s'han enviat, l'últim estat, l'últim lliurament al servidor SMTP i quants han fallat. Ideal per pintar una columna «enviat / no enviat» sobre una pàgina de factures en una sola crida. IMPORTANT — `last_status` i `last_sent_at` descriuen el lliurament al SERVIDOR SMTP DE SORTIDA, no el lliurament real: un email `sent` pot rebotar després sense que la plataforma se n'assabenti. - [Llista els emails enviats](https://docs.factuarea.com/ca/api-reference/emails/public-api.v1.emails.list): Consulta els emails que la teva empresa ha enviat per la plataforma — factures, pressupostos, factures proforma, albarans, recordatoris de cobrament —, de més recent a més antic, per poder respondre a «ha sortit de debò l'email d'aquesta factura?» sense preguntar-ho al teu client. Acotat a l'empresa autenticada. IMPORTANT — `status` descriu el lliurament al SERVIDOR SMTP DE SORTIDA, no el lliurament real: `sent` significa que el servidor de correu de sortida ha acceptat el missatge, no que el destinatari l'hagi rebut. - [Consulta un email enviat](https://docs.factuarea.com/ca/api-reference/emails/public-api.v1.emails.show): Consulta un email pel seu id, típicament després de trobar-lo al llistat, per investigar què li ha passat: destinatari, assumpte, estat, intents, el missatge d'error quan ha fallat i el document per al qual s'ha enviat. Acotat a l'empresa autenticada. IMPORTANT — `status` descriu el lliurament al SERVIDOR SMTP DE SORTIDA, no el lliurament real: `sent` significa que el servidor de correu de sortida ha acceptat el missatge, no que el destinatari l'hagi rebut. - [Cancel·lar una invitació d'empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employee-invitations.cancel): Cancel·la una invitació d'empleat pendent identificada pel seu `id` (UUID v7); passa a `canceled` i ja no es pot acceptar. Retorna 204 si té èxit, 422 si la invitació ja s'havia acceptat i 404 si no existeix a la teva empresa. - [Llistar les invitacions d'empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employee-invitations.list): Llista les invitacions d'empleat de la teva empresa. Només es retornen les invitacions amb rol `employee`; s'exclouen les invitacions d'usuari/admin de la superfície de gestió d'usuaris. Cada element exposa el seu `id` opac (UUID v7), `email`, `status` (`pending`/`accepted`/`canceled`/`expired`) i caducitat. - [Reenviar una invitació d'empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employee-invitations.resend): Reenvia una invitació d'empleat pendent identificada pel seu `id` (UUID v7), regenerant el seu token i caducitat i reenviant l'email d'invitació. Retorna 422 si la invitació ja s'havia acceptat o cancel·lat, i 404 si no existeix a la teva empresa. - [Enviar una invitació d'empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employee-invitations.send): Convida una persona a unir-se a la teva empresa com a empleat (portal de Control Horari). Només `email` és obligatori — el rol `employee` el fixa el servidor, mai es pren del payload. La persona convidada rep un email amb un enllaç d'acceptació. Convidar un email que ja pertany a un usuari de l'empresa, o que ja té una invitació pendent, retorna 422. Les invitacions d'empleat no consumeixen el límit de places `users` del pla. - [Cancel·lar l'add-on de places d'empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employee-seats.cancel): Cancel·la l'add-on de facturació per empleat: la subscripció `employee-seats` es cancel·la al final del període (el mes actual ja està pagat) i la cobertura per empleat es purga. La subscripció del pla mai es toca. Retorna l'estat de facturació resultant, on `subscribed` continua sent `true` fins que acaba el període. - [Sincronitzar la quantitat de places d'empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employee-seats.change-quantity): Reconcilia la quantitat de places de l'add-on amb el nombre real d'empleats actius (SET amb `proration_behavior: none`, sense factura). Idempotent: quan la quantitat ja coincideix és un no-op. Retorna l'estat de facturació resultant. - [Previsualitzar el càrrec de la plaça d'empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employee-seats.preview): Previsualitza l'import prorratejat per plaça per activar o contractar empleats, computat des de la propera factura de Stripe de la subscripció `employee-seats`, sense cobrar. Usa `count` (≥1, fins a 1000) per a una vista prèvia en bloc, o `employee_ids` (UUID v7) per a una vista prèvia conscient de cobertura: els empleats encara coberts en el període actual costen 0 (`already_covered: true`). `amount` és la base imposable en cèntims; `requires_payment_method` és `true` quan no hi ha mètode de pagament registrat. Mai llança — degrada a una vista prèvia neutra. - [Obtenir l'estat de facturació de places d'empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employee-seats.status): Retorna l'estat de facturació de l'add-on per empleat de la teva empresa: si la subscripció `employee-seats` està activa, quantes places es facturen (`quantity`), quants empleats estan actius, i el cost recurrent per plaça amb IVA. Els imports estan en unitats menors de la moneda (cèntims) i són `null` quan el cost no és resoluble (sense subscripció, sense pla actiu, enterprise fora de Stripe, sandbox) — mai un 0 enganyós. `seats_billable` indica si el teu pla HA D'ESTAR pagant per plaça, amb independència de `subscribed`: `subscribed: false` amb `seats_billable: true` i empleats actius és una anomalia de facturació, mentre que `seats_billable: false` és un estat legítim sense càrrec (enterprise per contracte, trial o sandbox). Els empleats mai compten per al límit de places `users` del pla. - [Subscriure's a l'add-on de places d'empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employee-seats.subscribe): Subscriu-te a l'add-on de facturació per empleat: crea la subscripció mensual dedicada `employee-seats` amb `quantity` fixat al nombre d'empleats actius, cobrant el primer període amb el mètode de pagament registrat. El cobrament és atòmic — sense mètode de pagament retorna 402 `employee_seat_payment_method_required` (l'embolcall porta `error.details.payment_setup_url`), i un cobrament rebutjat retorna 402 `employee_seat_charge_failed`; en ambdós casos no se subscriu res. Retorna l'estat de facturació resultant. - [Crear un empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employees.create): Registra un nou empleat per a l'empresa autenticada (resolta des de l'API key, mai des del payload). `first_name`, `last_name`, `email`, `employment_type` (`full_time`/`part_time`), `contract_hours`, `hire_date` i `ccaa` són obligatoris; `tax_id` i `job_title` són opcionals. Retorna l'empleat creat amb el seu `id` generat (UUID v7). Els empleats actius compten per a la facturació per places del mòdul de plantilla. - [Desactivar un empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employees.deactivate): Desactiva un empleat (transició `active` → `inactive`), retirant-lo suaument de la plantilla activa però conservant el seu registre. `termination_date` (`Y-m-d`) és opcional — omet-la per usar la data d'avui. Retorna 422 si l'empleat ja està inactiu o la data de baixa és anterior a la data d'alta. Reversible mitjançant reactivar. - [Cercar un empleat per external ID](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employees.find_by_external_id): Cerca un empleat pel seu `external_id` (enviat al body JSON), la clau d'integració que el mapeja a un registre en un sistema de tercers (ERP/CRM/HR). Diferent del `tax_id` fiscal. Retorna l'empleat coincident o 404 si cap empleat fa servir aquest external_id dins de la teva empresa. - [Llistar tots els empleats](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employees.list): Llista els empleats de la teva empresa amb paginació per cursor. Admet filtrar per `status` (`active`/`inactive`), `employment_type` (`full_time`/`part_time`) i `ccaa`, més una `search` de text lliure sobre nom i email. - [Reactivar un empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employees.reactivate): Reactiva un empleat (transició `inactive` → `active`), netejant el seu `termination_date` i tornant-lo a la plantilla activa. Sense cos de la petició. Retorna 422 si l'empleat ja està actiu. - [Obtenir un empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employees.show): Obtén un únic empleat pel seu `id` (UUID v7). Un empleat pertanyent a una altra empresa retorna 404 `employee_not_found` (anti-enumeració). - [Obtenir les estadístiques d'empleats](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employees.stats): KPIs agregats de la teva plantilla: nombre total d'empleats, nombre d'actius i inactius i un desglossament per tipus de jornada (`full_time`/`part_time`). Els empleats desactivats compten a `total`/`inactive` però no com a places actives. Es retorna com a `{ "data": EmployeeStats }`. - [Actualitzar un empleat](https://docs.factuarea.com/ca/api-reference/employees/public-api.v1.employees.update): Actualitza un empleat. Actualització parcial: només es modifiquen els camps presents en el payload; els omesos conserven el seu valor. `hire_date` és immutable. Retorna l'empleat actualitzat. - [Llistar tipus d'esdeveniment](https://docs.factuarea.com/ca/api-reference/events/public-api.v1.event_catalog.list): Llista el catàleg tancat de tipus d'esdeveniment que Factuarea pot emetre als webhooks. Cada entrada exposa el seu `name`, `category`, una descripció i un `status`: els tipus `available` s'emeten avui i són subscribibles via `enabled_events`; els tipus `coming_soon` estan reservats per a una versió futura i encara no són subscribibles (passar-ne un a `enabled_events` retorna 422). - [Llistar tots els esdeveniments](https://docs.factuarea.com/ca/api-reference/events/public-api.v1.events.list): Llista els esdeveniments del teu registre d'esdeveniments amb paginació per cursor. Cada esdeveniment registra alguna cosa que va passar al teu compte (es va pagar una factura, es va acceptar un pressupost, …) i és el mateix objecte que es lliura als teus webhook endpoints. Admet filtratge per `type[in]` i `created[gte|lte]`. - [Obtenir un esdeveniment](https://docs.factuarea.com/ca/api-reference/events/public-api.v1.events.show): Obté un únic esdeveniment pel seu `id` (format `evt_`, un identificador opac). Útil per auditar i reenviar payloads de webhook. Retorna `404 not_found` si l'esdeveniment no existeix o pertany a una altra empresa. - [Sol·licitar l'anul·lació d'un enviament a FACe](https://docs.factuarea.com/ca/api-reference/facturae/public-api.v1.face_submissions.cancel): Sol·licita l'anul·lació (4200) d'un enviament a FACe amb un `reason` obligatori. Només es permet mentre l'enviament està en un estat anul·lable (`submitted`, `registered_rcf`, `accounted`); en cas contrari retorna 422 `face_submission_not_cancellable`. L'enviament passa a `cancellation_requested` fins que FACe confirma. - [Obtenir un enviament a FACe](https://docs.factuarea.com/ca/api-reference/facturae/public-api.v1.face_submissions.show): Obté un enviament a FACe pel seu `id` (UUID). El camp `status` reflecteix l'últim estat de tramitació conegut a FACe (`submitted`, `registered_rcf`, `accounted`, `paid`, `rejected`, `cancellation_requested`, `cancelled`, `error`) — el sistema consulta FACe periòdicament, així que un GET normal és la manera de seguir el progrés (no hi ha endpoint de refresc a v1). - [Llistar els enviaments a FACe de la factura](https://docs.factuarea.com/ca/api-reference/facturae/public-api.v1.invoices.face_submissions.list): Llista l'històric d'enviaments a FACe d'una factura (array pla, inclou el més recent). Retorna `data: []` quan la factura mai no s'ha enviat. - [Enviar la factura a FACe](https://docs.factuarea.com/ca/api-reference/facturae/public-api.v1.invoices.face_submissions.submit): Presenta una factura emesa a FACe (el punt d'entrada B2G espanyol). Requereix els tres codis DIR3 del client i un certificat de signatura actiu; el XML FacturaE 3.2.2 es signa XAdES-EPES i es presenta a FACe, retornant el número de registre. Sense cos de petició —els codis DIR3 es llegeixen del client. Les claus de test simulen la presentació sense contactar amb FACe. - [Descarregar l'XML de FacturaE](https://docs.factuarea.com/ca/api-reference/facturae/public-api.v1.invoices.facturae): Retorna en streaming el XML FacturaE 3.2.2 de la factura (compliment B2G), conforme a XSD amb el desglossament d'impostos complet. Amb un certificat de signatura actiu el cos es signa XAdES-EPES i es serveix com a `.xsig`; sense ell es retorna sense signar com a `.xml`. La capçalera `X-Facturae-Signed` distingeix tots dos. Les factures en esborrany retornen 422. - [Llistar tots els festius](https://docs.factuarea.com/ca/api-reference/holidays/public-api.v1.holidays.list): Llista els festius visibles per a la teva empresa amb paginació per cursor: festius de referència globals (nacionals i per comunitat autònoma, precarregats i de només lectura) més els teus festius locals personalitzats. Admet filtrar per `year`, `ccaa` (comunitat autònoma ISO 3166-2:ES), `scope` (`national`/`autonomic`/`local`) i `source` (`reference` per a files precarregades, `custom` per a les pròpies). - [Resoldre els festius aplicables](https://docs.factuarea.com/ca/api-reference/holidays/public-api.v1.holidays.resolve): Resol els festius que apliquen a una comunitat autònoma donada en un any donat: els festius nacionals, els festius autonòmics d'aquesta `ccaa` i els teus festius locals personalitzats, fusionats en una única llista plana sota `{ "data": [Holiday, …] }`. Tant `ccaa` (ISO 3166-2:ES) com `year` són obligatoris; un codi de comunitat no vàlid o un any fora de rang retorna 422. - [Obtenir un festiu](https://docs.factuarea.com/ca/api-reference/holidays/public-api.v1.holidays.show): Obtén un únic festiu pel seu `id` (UUID v7). Un festiu personalitzat pertanyent a una altra empresa retorna 404 `holiday_not_found` (anti-enumeració). - [Llista els esdeveniments d'integració](https://docs.factuarea.com/ca/api-reference/integration-events/public-api.v1.integrations.events.list): Consulta tot el que les passarel·les de pagament han enviat a Factuarea. Aquesta és la safata que cal obrir quan un cobrament no ha generat la seva factura: cada esdeveniment descartat porta un `discard_reason` tipat i si es pot reprocessar. De més recent a més antic, i acotat a l'empresa autenticada. El contingut cru de l'esdeveniment no es retorna mai. - [Reprocessa un esdeveniment d'integració aparcat](https://docs.factuarea.com/ca/api-reference/integration-events/public-api.v1.integrations.events.replay): Reprocessa un esdeveniment de passarel·la que s'ha aparcat, un cop desapareguda la causa que li va impedir produir el seu efecte. **Abans de cridar-lo** - L'esdeveniment ha d'estar publicat amb `is_replayable` a `true`; qualsevol altre retorna 422. - Resol abans la causa: torna a activar la facturació automàtica, torna a vincular el compte connectat, espera el tipus de canvi. - Exigeix l'scope d'escriptura `integration_events:write`, mai l'scope de lectura de la safata. **Què pot provocar** > **Aquesta acció pot tenir conseqüències fiscals reals.** Si la causa ja està resolta, el reprocés POT EMETRE UNA FACTURA REAL, amb el seu número de sèrie i el seu registre a VeriFactu. Confirma-ho amb el titular del compte abans de cridar-lo. **Què retorna** - Un `202` significa acceptat i encuat, **no** completat. - El cos retorna l'esdeveniment tal com està ara, no el resultat del reintent. - El resultat apareix com un esdeveniment NOU a la safata: consulta `GET /v1/integrations/events` per veure com ha acabat. - No duplica mai factures: el reprocés passa per la mateixa comprovació d'idempotència que l'intent original. - [Consulta un esdeveniment d'integració](https://docs.factuarea.com/ca/api-reference/integration-events/public-api.v1.integrations.events.show): Consulta un esdeveniment d'integració pel seu id, típicament després de trobar-lo al llistat, per saber exactament per què un cobrament no ha produït la seva factura i què cal fer a continuació. A més dels camps del llistat, el detall afegeix `recommended_action`, una frase imperativa amb el pas següent, i `is_replayable`, que et diu si l'operació de reprocés acceptaria l'esdeveniment. - [Llistar l'activitat de la factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.activities): Retorna la línia de temps d'activitat paginada per cursor (log d'auditoria) d'una sola factura: transicions d'estat, emails, recordatoris i canvis de metadades. - [Anul·lar una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.annul): Retira una factura emesa **amb un motiu documentat**. Aquí `reason` és obligatori (3–500 caràcters); aquesta és l'única diferència amb `POST /v1/invoices/{id}/void`, que fa exactament la mateixa operació i persisteix un text de farciment quan l'omets. Prefereix aquest endpoint sempre que el motiu hagi de ser traçable: el text que envies es conserva al rastre d'auditoria de la factura i, quan l'empresa està acollida a VeriFactu, passa a ser el `motivo` del registre d'anul·lació davant l'AEAT. La factura passa a `annulled` i `voided_at` comença a informar de quan va passar. L'estat és terminal i l'operació és **irreversible**: no hi ha tornada a `sent` ni a `draft`, i el número correlatiu de la sèrie ni s'allibera ni es reutilitza. **Efecte a l'AEAT.** Amb VeriFactu actiu, anul·lar encua un registre d'*anul·lació* a l'AEAT de manera **asíncrona**: un `200` significa que la factura està anul·lada a Factuarea, no que l'AEAT ja ho hagi processat — consulta la factura per veure'n l'estat VeriFactu. El registre d'*alta* original no s'esborra ni es reescriu; l'AEAT conserva els dos apunts, l'emissió i la seva anul·lació. Amb VeriFactu inactiu l'anul·lació és purament interna i no es transmet res. **Anul·lar o rectificar?** L'anul·lació retira el document sencer i només funciona abans del cobrament; no produeix cap document rectificatiu, així que mai no reexpressa cap import. Una factura rectificativa (`POST /v1/invoices/{id}/corrective`) crea una **nova** factura que corregeix l'original i és l'únic camí per a una factura que ja està `paid` o que només està malament en part. Límits: només es pot anul·lar una factura en `sent` o `overdue`. Un `draft` no s'anul·la, s'esborra; `paid`, `cancelled` i `annulled` retornen 422. Una factura que **és** rectificativa no es pot anul·lar mai — emet en el seu lloc una nova rectificativa de l'original. Fes servir `GET /v1/invoices/{id}/can-annul` per comprovar l'elegibilitat, i si es crearà un registre d'anul·lació VeriFactu, abans de cridar aquí. - [Assignar un número de factura real](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.assign_real_number): Promou un esborrany a factura definitiva assignant-li el seu número de sèrie real. En empreses amb VeriFactu habilitat això passa automàticament en enviar. - [Crear factures en bloc](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.bulk_create): Crea fins a 100 factures en una crida, cada entrada un payload de factura complet. Amb `dry_run=true` valida cada fila sense persistir i retorna una classificació per fila (`results[]`, incloent-hi `external_id` duplicat i un avís no bloquejant de cens AEAT); amb `dry_run=false` crea només les files vàlides i reporta la resta a `failures[]`. Retorna la forma `BulkCreateResult`. - [Eliminació massiva de factures](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.bulk_delete): Elimina diverses factures en una crida amb èxit parcial: cada id s'avalua de manera independent i una fallada mai avorta el lot. Només s'eliminen factures en esborrany; una factura emesa torna com a fallada `resource_not_deletable` (fes servir `void` en lloc d'això). Retorna un `BulkPartialSuccessResult` amb `total`, `successful`, `failed` i una llista `failures` per id. ```json { "ids": ["0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f60", "0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f61"] } ``` Límits: `ids` accepta d'1 a 100 entrades UUID v7 per crida. - [Descarregar en bloc els PDF de factures](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.bulk_pdf): Empaqueta els PDF de fins a 50 factures (per id) en un únic ZIP. Els ids no trobats o sense PDF generable no aborten la petició: el ZIP porta només els vàlids i els comptadors per recurs viatgen a les capçaleres de resposta `X-Bulk-*`. - [Enviar factures en bloc](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.bulk_send): Envia fins a 200 factures per email (encuat) en una sola crida, reutilitzant la ruta d'enviament individual per id. Retorna un `BulkPartialSuccessResult` amb els comptadors `total`, `successful` i `failed` més una llista `failures` (`id` + `error_code` + `error_message` en castellà) per cada factura que no s'ha pogut enviar (no trobada, estat terminal o sense destinatari resoluble). - [Canviar en bloc l'estat de factures](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.bulk_status): Transiciona diverses factures a un nou estat en una crida, cadascuna a través del mateix guard de l'Aggregate, amb èxit parcial (un id rebutjat mai avorta el lot). `new_status` és `sent` o `paid`; quan és `paid`, `payment_date` és obligatori i es propaga com la data de pagament real de cada factura (mai `now()`). Retorna un `BulkPartialSuccessResult` amb `total`, `successful`, `failed` i una llista `failures` per id (`resource_not_found` o `invalid_status_transition`). ```json { "ids": ["0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f60"], "new_status": "paid", "payment_date": "2026-06-30" } ``` Límits: `ids` accepta d'1 a 50 entrades; `payment_date` és obligatori quan `new_status` és `paid` i no pot estar en el futur. - [Comprovar elegibilitat per a anul·lació](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.can_annul): Valida si la factura es pot anul·lar i si es crearà un registre d'anul·lació de VeriFactu. Crida'l abans de fer POST a /annul. - [Generar factura rectificativa](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.corrective): Emet una factura rectificativa (RD 1619/2012 art. 15) que corregeix una factura ja emesa. Retorna `201` amb la **nova** factura: `is_corrective: true`, `corrective` apuntant a l'original i un número derivat del d'aquesta a la mateixa sèrie (`F-2026-0042-REC1`, `-REC2`… per a rectificatives successives). Flux: l'original ha d'estar ja emesa (`sent` o `paid`) → la rectificativa neix **ja emesa**, mai com a esborrany → quan VeriFactu està actiu la seva *alta* es transmet a l'AEAT de manera **asíncrona**, així que un `201` no significa que l'AEAT ja l'hagi acceptada. L'original no es modifica mai: conserva el seu número, el seu estat i el seu propi registre VeriFactu. Una rectificativa és un document addicional, no una edició. **Total o parcial.** `correction_type: full` és una substitució (naturalesa VeriFactu `S`): les `lines` que envies són els *imports finals correctes*, i ometre `lines` del tot la converteix en una anul·lació total, on cada línia original es copia negada i amb el prefix `[ANULACION]`. `correction_type: partial` és una rectificació per diferències (naturalesa `I`): `lines` és obligatori i cadascuna és un delta — típicament negatiu — amb el prefix `[AJUSTE]`. En una rectificació parcial una línia només mou stock si declara el seu propi `product_id`; en una substitució el producte s'hereta de la línia original del mateix índex. **Codi R de l'AEAT.** Per defecte es deriva de `correction_reason`: `error_fundado` → R1, `concurso` → R2, `incobrable` → R3, la resta → R4; una rectificativa d'una factura simplificada (F2) neix sempre R5 sigui quin sigui el motiu. `correction_code` sobreescriu aquesta derivació, però es valida contra la matriu legal — original F2 → només `R5`; original F1/F3 → només `R1`–`R4`. Qualsevol altra combinació retorna 422 amb els `allowed_values` legals. Límits: les originals en `draft`, `overdue`, `cancelled` i `annulled` retornen 422 (una factura `overdue` s'ha de cobrar o anul·lar abans); una rectificativa no es pot rectificar al seu torn — emet en el seu lloc una nova rectificativa de l'original. Llista totes les rectificatives d'una factura amb `GET /v1/invoices/{id}/correctives`. - [Llistar factures rectificatives](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.correctives): Retorna totes les factures rectificatives associades a la factura original. S'utilitza per reconstruir l'arbre original → rectificativa. - [Crea una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.create): Crea una factura de venda. Es crea en `draft` per defecte; passa `options.issue_directly: true` per emetre-la immediatament (assignant el número correlatiu i congelant el document segons AEAT), o emet-la més tard. L'*alta* VeriFactu es transmet a AEAT de manera asíncrona: un `201` no significa que AEAT hagi acceptat encara la factura, així que consulta-la per a l'estat AEAT. ```json { "client_id": "0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f60", "lines": [{ "description": "Consulting", "quantity": 1, "unit_price": 1000, "tax_rate": 21 }], "options": { "issue_directly": true } } ``` Límits: es requereix almenys una línia; envia una `Idempotency-Key` (≤255 caràcters, recordada 24 h) per a reintents segurs; un `external_id` duplicat fa upsert de la factura existent en lloc de crear-ne una de nova. - [Crear una factura recurrent a partir d'una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.create_recurring): Crea una plantilla de factura recurrent que reutilitza les línies, el client i la sèrie d'una factura existent, aplicant la cadència (freqüència, data d'inici, data de fi opcional i límits) aportada al cos. Retorna la nova factura recurrent. - [Elimina una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.delete): Elimina una factura en esborrany. Les factures emeses no es poden eliminar (usa `void` al seu lloc). - [Duplicar una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.duplicate): Crea una nova factura en esborrany copiant les línies, el client i les metadades d'una factura existent. La nova factura obté un `uuid` i un número nous. - [Exportar factures a un full de càlcul](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.export_excel): Exporta una selecció de factures a un full de càlcul (`xlsx` o `csv`) i la retorna com a adjunt en streaming. Acota-la amb els filtres (`invoice_ids[]`, `client_id`, `series_id`, `status`, `date_from`, `date_to`, `search`) o omet-los per exportar-ho tot. `format` tria la disposició: `SUMMARY` (una fila per factura) o `ITEMS` (una fila per línia). ```http GET /v1/invoices/export?format=SUMMARY&status=paid&date_from=2026-01-01&date_to=2026-03-31 ``` Límits: la selecció està limitada a 5.000 factures; una de més àmplia retorna 422 `export_limit_exceeded`. - [Cercar una factura per external ID](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.find_by_external_id): Cerca una única factura pel seu `external_id` (enviat al body JSON), la clau d'integració que la mapeja a un registre en un sistema de tercers (ERP/CRM/e-commerce). Diferent del número fiscal i del `uuid`. Retorna la factura coincident o 404 `invoice_not_found` si cap factura fa servir aquest external_id dins de la teva empresa. - [Cercar una factura per número](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.find_by_number): Cerca una única factura pel seu número, amb un `year` opcional per desambiguar entre exercicis fiscals. Retorna 404 si no es troba i 422 si el número és ambigu i no es proporciona `year`. - [Llistar totes les factures](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.list): Llista les teves factures de venda amb paginació per cursor. Admet filtratge per `status[in]`, `client_id`, `series_id`, `issued_on[gte|lte]` i `total[gte|lte]`. - [Marca la factura com a pagada](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.mark_paid): Marca una factura com a totalment pagada. Idempotent: si ja està pagada, retorna la factura sense canvis. Retorna 422 si la factura està en un estat que no pot transicionar a `paid`. - [Marca una factura com a enviada](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.mark_sent): Transiciona una factura en esborrany a `sent` sense enviar email. Útil quan el document s'ha lliurat per un canal extern. - [Descarregar el PDF del rebut de pagament](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.payment_receipt): Transmet el PDF del justificant d'una factura pagada. Retorna 422 si la factura no està en estat `paid`. - [Registrar un pagament](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.payments_create): Registra un pagament parcial (o total) contra una factura. La factura transiciona a `partially_paid` mentre l'import pagat acumulat està per sota del total, i a `paid` un cop l'assoleix. Retorna 422 si la factura està en un estat que no admet pagaments. - [Llistar pagaments de factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.payments_list): Llista els pagaments registrats contra una factura, ordenats per data de pagament. Retorna un array buit quan encara no s'ha registrat cap pagament. - [Descarregar el PDF de la factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.pdf): Descarrega la representació en PDF d'una factura. Retorna el flux binari del PDF (`application/pdf`). - [Generar enllaç temporal a PDF](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.pdf_link): Retorna una URL temporal al PDF de la factura en lloc de transmetre els bytes. Còmode per incrustar en emails o apps de missatgeria. Contracte dual: 200 amb la URL quan el PDF ja està materialitzat; 202 amb `status: pendiente` quan la generació s'ha encuat (el PDF es renderitza a la cua `pdf`) — reintenta fins a obtenir el 200. - [Previsualitzar el PDF d'un esborrany de factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.pdf_preview): Retorna en streaming un PDF esborrany no fiscal (`application/pdf`) d'una factura marcada com a BORRADOR, amb un número de marcador de posició i sense QR de VeriFactu. No es persisteix res: el comptador de la sèrie i l'empremta romanen intactes. Retorna 422 per a una factura ja emesa — fes servir l'endpoint `pdf` estàndard en el seu lloc. - [Recupera l'enllaç públic de la factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.public_link_get): Retorna la URL pública per compartir de la factura (/d/{uuid}) juntament amb el seu estat, expiració i els dies màxims d'extensió permesos pel pla. - [Actualitzar l'enllaç públic d'una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.public_link_update): Aplica una acció a l'enllaç públic: `revoke`, `activate`, `extend` (amb `extend_days`) o `reset` al valor per defecte del pla. - [Llista els trimestres amb factures](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.quarterly.available): Retorna els trimestres que tenen almenys una factura, amb desglossament per tipus de factura (F1/F2/F3/R5). Útil per poblar selectors de "trimestre a exportar". - [Generar arxiu ZIP trimestral](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.quarterly.download_zip): Construeix un ZIP amb tots els PDF de factures del trimestre indicat. Retorna metadades del ZIP (ruta, recomptes processats, errors). - [Enviar per email el ZIP trimestral a l'assessor](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.quarterly.send_email): Genera el ZIP trimestral i l'envia per email al destinatari, normalment l'assessor fiscal. - [Vista prèvia d'un email de recordatori de pagament](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.reminder_preview): Renderitza l'HTML, l'assumpte i els destinataris resolts de l'email de recordatori sense enviar-lo. Mateixos camps d'override que send-reminder. - [Reprogramar una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.reschedule): Mou la data d'emissió d'una factura ja programada. La factura **continua a `scheduled` tota l'estona** — a diferència d'`unschedule` seguit de `schedule`, no torna mai a `draft`, així que en cap moment intermedi és editable ni esborrable, i no hi ha finestra en què l'escombrat la pogués trobar sense programar. **Què pots canviar:** `scheduled_for`, i només això. `scheduled_action` es conserva — una programació creada com a `issue_and_send` continua enviant l'email al client a la data nova, i una creada com a `draft` continua sense fer-ho. Per canviar l'acció has de fer `unschedule` i tornar a programar. Aquesta crida no toca el contingut de la factura (línies, client, sèrie, totals): per a això fes servir `PATCH /v1/invoices/{id}` mentre continuï sent un esborrany. Límits: només es pot reprogramar una factura en `scheduled` — un `draft` (mai programat) o una factura ja emesa retornen 422 — i el nou `scheduled_for` ha d'estar estrictament al futur (422 si no). Tot el que es documenta a `schedule` sobre què passa quan arriba la data (número assignat en aquell moment, snapshots congelats, *alta* asíncrona a VeriFactu, email només amb `issue_and_send`, reintent per factura si falla) s'aplica igual a la data nova. - [Programar una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.schedule): Reserva l'emissió d'una factura esborrany per a un instant futur. La factura passa a `scheduled` i **encara no passa res fiscal**: conserva el seu número de farciment `BORRADOR`, no consumeix cap comptador de sèrie i no es registra res a VeriFactu. Programar no crema numeració mai. **Què passa a `scheduled_for`.** Un escombrat s'executa cada minut i, a la primera passada a partir d'aquell instant: (1) assigna el número correlatiu definitiu de la sèrie **en aquell moment**, no quan vas programar — així que un document programat avui i emès el mes que ve pren el número que correspon al mes que ve; (2) congela els snapshots de destinatari i emissor en aquell instant, que és el que mostraran el PDF i l'XML fiscal; (3) passa la factura a `sent`; (4) encua l'*alta* a VeriFactu davant l'AEAT de manera **asíncrona** quan l'empresa hi està acollida; i (5) envia l'email al client **només** quan `scheduled_action` és `issue_and_send` i el client té email registrat — amb `scheduled_action: draft` la factura s'emet però no es lliura mai, i `issue_and_send` sense email de destinatari l'emet igualment, ometent el lliurament en silenci. **Zona horària.** `scheduled_for` és una data-hora ISO 8601. Si porta un desfasament explícit (`2027-01-15T09:00:00Z`, `…+01:00`) es respecta aquell desfasament; sense ell s'interpreta a la zona horària de servidor del compte, `Europe/Madrid`. La resolució és de minut: espera l'emissió dins del minut següent a l'instant que has demanat, mai abans. **Si l'emissió programada falla**, cada factura s'aïlla a la seva pròpia transacció: la que falla es queda a `scheduled` amb la seva data al passat, l'error es registra, la resta del lot no es veu afectada i l'escombrat següent la reintenta. Una emissió correcta no es repeteix mai, perquè `scheduled → sent` només pot passar una vegada. Límits: només es pot programar un `draft` (qualsevol altre estat retorna 422) i `scheduled_for` ha d'estar estrictament al futur (422 si no). Mentre continuï a `scheduled` pots cridar `unschedule` per tornar-la a `draft`, o `reschedule` per moure només la data. - [Envia la factura per email](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.send): Envia una factura al client per email. Utilitza l'email registrat tret que se sobreescrigui al payload. - [Envia un recordatori de pagament](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.send_reminder): Envia per email un recordatori de pagament al client per a aquesta factura. Accepta valors opcionals `email`, `subject`, `message`, `cc`, `bcc` per sobreescriure. - [Recupera una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.show): Obté una factura de venda pel seu `uuid`. - [Comprovar elegibilitat de factura simplificada](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.simplified_eligibility): Determina si una factura es pot emetre com a simplificada (F2) segons el Real Decreto 1619/2012 art. 4 en funció de l'import i les dades de la contrapart. - [Obtenir estadístiques de factures](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.stats): Retorna KPIs agregats de l'empresa: recomptes per estat, ingressos, totals pendents i vençuts, dies mitjans fins al pagament i recomptes de rectificatives. Filtrable per període (per defecte l'any actual). - [Llistar estats de factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.statuses): Llista el catàleg tancat d'estats de factura amb el seu `value` públic, la seva `label` localitzada i el seu `color` d'UI. Fes-lo servir per omplir filtres o selectors d'estat en lloc de codificar valors a mà. - [Substituir factures simplificades per factura completa](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.substitute_simplified): Agrupa N factures simplificades (F2) sota una única factura completa substitutiva (F3) amb les dades completes del receptor. Marca les originals com a substituïdes. - [Desprogramar una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.unschedule): Cancel·la una emissió programada. La factura torna a `draft`, `scheduled_for` i `scheduled_action` es tornen a posar a `null`, i torna a ser editable i esborrable com qualsevol altre esborrany. Desprogramar no deixa **cap rastre fiscal**, perquè encara no havia passat res fiscal: no es va consumir cap número correlatiu de la sèrie (la factura conserva el seu número de farciment `BORRADOR`), no es va registrar res a VeriFactu i no es va enviar cap email. Això no és una anul·lació i no apareix a cap registre de l'AEAT. **Finestra d'ús.** Només s'aplica mentre la factura està a `scheduled`. Un `draft` que no s'ha programat mai retorna 422, i una factura que l'escombrat ja ha emès, també: des d'aquell instant està a `sent`, té número definitiu i — on apliqui VeriFactu — un registre davant l'AEAT, així que la tornada enrere ja no és `unschedule` sinó `void`/`annul` per retirar-la (només mentre estigui sense cobrar) o `corrective` per rectificar-la. A la pràctica la cursa és real: una factura el `scheduled_for` de la qual acaba de passar pot haver-se emès ja quan arribi la teva crida. Si només vols moure la data, fes servir `PATCH /v1/invoices/{id}/reschedule` — evita el viatge d'anada i tornada per `draft` i la finestra en què el document és editable. - [Anul·lar l'enviament d'una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.unsend): Neteja la marca d'enviament (`sent_at`) d'una factura `sent` mantenint el seu estat `sent`. El número correlatiu i el registre VeriFactu queden intactes: la factura no es reverteix a esborrany i continua sent immutable segons AEAT. Fes-ho servir per desfer un marcatge-com-a-enviada accidental. Idempotent: no fa res quan `sent_at` ja és null. - [Actualitzar una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.update): Actualitza una factura en esborrany. Un cop emesa una factura (estat `issued`), la majoria dels camps esdevenen immutables per compliment de l'AEAT. - [Anul·lar una factura](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.invoices.void): Retira una factura emesa. La factura passa a `annulled`, `voided_at` comença a informar de quan va passar i l'estat és terminal: anul·lar és **irreversible** i no hi ha tornada a `sent` ni a `draft`. **Anul·lar o rectificar?** Anul·la quan el document sencer no hauria d'haver existit mai i no s'ha cobrat — la factura es retira en bloc i no es produeix cap document rectificatiu. Emet una rectificativa (`POST /v1/invoices/{id}/corrective`) quan la factura ja estava cobrada, o quan només està malament en part (import, destinatari, devolució parcial): una factura `paid` no es pot anul·lar mai, i anul·lar no corregeix mai cap xifra. El que anul·lar **no** fa: el número correlatiu de la sèrie ni s'allibera ni es reutilitza (el comptador de la sèrie només avança), la factura original no s'esborra i el seu registre d'*alta* a VeriFactu no es retira. Quan l'empresa està acollida a VeriFactu, s'encua un registre d'anul·lació davant l'AEAT de manera **asíncrona** amb el teu `reason` com a `motivo` — un `200` significa que la factura està anul·lada al nostre costat, no que l'AEAT ja hagi processat l'anul·lació. Amb VeriFactu inactiu l'anul·lació és purament interna. Límits: només es pot anul·lar una factura en `sent` o `overdue`. Un `draft` no és anul·lable (esborra'l en lloc d'això), i `paid`, `cancelled` i `annulled` retornen 422. Una factura que **és** rectificativa no es pot anul·lar mai — per desfer una rectificativa equivocada, emet una nova rectificativa de l'original. Fixa't que l'invers sí que s'admet: tenir rectificatives no impedeix anul·lar l'original. Crida abans `GET /v1/invoices/{id}/can-annul` si necessites comprovar l'elegibilitat sense intentar el canvi. Aquí `reason` és opcional i es persisteix un text de farciment quan l'omets. `POST /v1/invoices/{id}/annul` és exactament la mateixa operació amb `reason` obligatori — prefereix-la sempre que el motiu hagi de quedar documentat. - [Llistar mètodes de pagament](https://docs.factuarea.com/ca/api-reference/invoices/public-api.v1.payment_methods.list): Llista el catàleg tancat de mètodes de pagament amb el seu `value` públic i el seu `label` localitzat. Fes-lo servir per poblar el camp `payment_method` en registrar un pagament en lloc de hardcodejar valors. - [Tancar un registre de jornada mensual](https://docs.factuarea.com/ca/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.create): Congela el tancament mensual inalterable del registre de jornada per a un `(year, month)` finalitzat: pren una instantània dels totals del saldo de cada empleat actiu i del seu desglossament/saldos d'absències (reutilitzant el contracte de saldo, sense recomputar mai) i bloqueja el període davant d'entrades retroactives i correccions. `year` i `month` (1-12) són obligatoris. Un mes que encara no ha acabat retorna 422 en castellà; un període ja tancat retorna 409. Reobrir un període prèviament reobert el torna a tancar, mantenint el seu `id` original. Retorna 201 amb el tancament creat i una capçalera `Location`. - [Descarregar el registre tancat (RD-llei 8/2019)](https://docs.factuarea.com/ca/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.export): Descarrega el registre de jornada diari d'un període tancat com a full de càlcul en el format `rdley_8_2019`, llegit del registre bloquejat i a prova de manipulacions (entrades de només addició + cadena de hashes) del període. `format` és opcional i pren per defecte `rdley_8_2019`; un format fora del catàleg retorna 422. Un període sense tancament retorna 404. La resposta és una descàrrega d'arxiu binari. - [Llistar tots els tancaments mensuals de registre de jornada](https://docs.factuarea.com/ca/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.list): Llista els tancaments mensuals del registre de jornada de la teva empresa amb paginació per cursor, ordenats per període descendent. Admet filtrar per `year`. Cada element exposa el seu estat (`closed`/`reopened`), els límits del període i el nombre d'empleats. - [Reobrir un tancament de registre de jornada mensual](https://docs.factuarea.com/ca/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.reopen): Reobre un tancament mensual `closed` pel seu `id` (UUID v7) — una recuperació auditada d'un tancament erroni que rehabilita les escriptures del període. El tancament manté el seu `id`; el seu estat passa a `reopened`. Un tancament que no es pot reobrir retorna 422 en castellà, i un pertanyent a una altra empresa retorna 404. Retorna 200 amb el tancament reobert. - [Obtenir l'informe d'un període tancat](https://docs.factuarea.com/ca/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.report): Retorna l'informe mensual d'un període tancat pel `id` (UUID v7) del tancament, llegit de la instantània congelada sense recomputar, així que els totals mai divergeixen del full en el moment del tancament. Conté els totals agregats de l'empresa i una fila per empleat amb totals, desglossament d'absències i saldos, i el detall diari. Els totals estan en minuts. Un període sense tancament retorna 404. Un recurs computat: exposa `close_id`, mai un `id` propi. - [Segellar un registre de jornada mensual](https://docs.factuarea.com/ca/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.seal): Segella (signa digitalment) un registre de jornada mensual `closed` pel `id` (UUID v7) del tancament: congela un digest canònic SHA-256 de la instantània del tancament i una signatura RSA-SHA256 separada feta amb el certificat de l'empresa, de manera que el registre és a prova de manipulacions i verificable de manera independent. Un tancament que no està `closed` retorna 422 en castellà, un període ja segellat retorna 409 (un segell per tancament, sense re-segellat) i una empresa sense un certificat actiu utilitzable retorna 422. Un tancament pertanyent a una altra empresa retorna 404. Retorna 201 amb el segell (inclòs el seu estat de verificació en viu) i una capçalera `Location`. - [Obtenir el segell d'un registre mensual](https://docs.factuarea.com/ca/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.seal_show): Obtén el segell digital d'un registre de jornada mensual pel `id` (UUID v7) del tancament, juntament amb el seu estat de verificació recomputat en viu contra la instantània actual: `verified` és `true` quan la instantània i la signatura estan intactes; en un altre cas `verification_reason` explica el desajust (`snapshot_mismatch`, `signature_invalid` o `certificate_unreadable`). El segell exposa el seu digest, signatura i certificat de signatura perquè un tercer pugui verificar-lo. Un tancament sense segell — o pertanyent a una altra empresa — retorna 404 `monthly_register_signature_not_found` (anti-enumeració). - [Obtenir un tancament de registre de jornada mensual](https://docs.factuarea.com/ca/api-reference/monthly-register-closes/public-api.v1.monthly_time_record_closes.show): Obtén un únic tancament mensual pel seu `id` (UUID v7). Un tancament pertanyent a una altra empresa retorna 404 `monthly_time_record_close_not_found` (anti-enumeració). - [Descarregar l'exportació de nòmina d'un mes tancat](https://docs.factuarea.com/ca/api-reference/payroll-exports/public-api.v1.monthly_time_record_closes.payroll_export): Descarrega l'arxiu d'incidències de nòmina d'un mes tancat en el format d'un programari de nòmina espanyol (`a3` per a A3 Wolters Kluwer, `sage` per a Sage, `nominasol` per a NominaSOL), llegit de la instantània congelada del tancament mensual sense recomputar. Cada fila és un empleat amb la seva identitat fiscal (NIF i nom), minuts treballats vs esperats, hores extra, saldo i les absències aprovades desglossades per tipus. `format` és opcional i pren per defecte `a3`; un format fora del catàleg retorna 422. Un període sense tancament retorna 404. La resposta és una descàrrega de full de càlcul binari. - [Llistar els formats d'exportació de nòmina suportats](https://docs.factuarea.com/ca/api-reference/payroll-exports/public-api.v1.payroll_export_formats.list): Llista els formats de programari de nòmina suportats per l'exportació de nòmina (`a3`, `sage`, `nominasol`), cadascun amb la seva etiqueta comercial, perquè una integració pugui oferir un selector de programari sense fer hardcode dels valors. Un catàleg pla de només lectura sense paginació. - [Llistar les declaracions de presencialitat oficina/remot](https://docs.factuarea.com/ca/api-reference/presence/public-api.v1.presence.daily): Llista les declaracions de presencialitat oficina/remot de la teva empresa amb paginació per cursor. Admet filtrar per `employee_id` (UUID v7), per dia exacte (`date`) o per rang de dates (`from`/`to`, `YYYY-MM-DD`). Cada registre és la ubicació de treball declarada per un empleat per a un dia. De només lectura a l'API pública — les declaracions es fan des de l'app (només SPA). - [Obtenir la presència de l'equip en viu](https://docs.factuarea.com/ca/api-reference/presence/public-api.v1.presence.live): Retorna el panell de presència en viu del teu equip per al mòdul de Control Horari: un element `employee_presence` per empleat actiu, amb l'estat de la jornada derivat del registre inalterable de jornada (`working`/`paused`/`finished`/`away`), el flag d'arribada tard (primer fitxatge vs inici previst) i la ubicació oficina/remot declarada avui. Un recurs computat de només lectura: cada element exposa l'UUID v7 de l'empleat com el seu `id`, mai un id de registre de presència. Sense filtres ni paginació. - [Obtenir la presència en viu d'un empleat](https://docs.factuarea.com/ca/api-reference/presence/public-api.v1.presence.show): Obtén la presència en viu d'un únic empleat pel seu `id` (UUID v7): l'estat de la jornada derivat del registre, el flag d'arribada tard i la ubicació oficina/remot declarada avui. Un empleat que no existeix o pertany a una altra empresa retorna 404 `employee_presence_not_found` (anti-enumeració). Un recurs computat: exposa l'UUID v7 de l'empleat com el seu `id`. - [Llistar la línia temporal d'activitat del producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.activities): Retorna la línia de temps d'auditoria d'un producte combinant els seus propis esdeveniments de domini més els esdeveniments de document les línies dels quals el referencien. Paginada amb els query params page i per_page (50 per defecte). - [Elimina diversos productes de forma massiva](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.bulk_delete): Elimina fins a 200 productes en una sola petició. Retorna un `BulkPartialSuccessResult` amb els comptadors `total`, `successful` i `failed` més una llista `failures` (`id` + `error_code` + `error_message` en castellà); els productes inclosos en packs es reporten a `failures`. Decrementa el comptador d'ús del pla en conseqüència. - [Canviar en bloc l'estat actiu de productes](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.bulk_status): Mou fins a 50 productes (per id) al `new_status` destí (`active` o `inactive`). Idempotent respecte al destí: un producte ja en l'estat sol·licitat compta com a `successful` sense canviar. Retorna un `BulkPartialSuccessResult`; els productes no trobats tornen a `failures[]`. - [Actualitzar l'stock de diversos productes](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.bulk_update_stock): Aplica una operació d'stock a diversos productes en una sola petició (fins a 500). Els UUID que no pertanyen a la teva empresa s'ignoren silenciosament. - [Crear un producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.create): Crea un nou producte al teu catàleg. - [Elimina un producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.delete): Elimina un producte. Retorna 422 si el producte està referenciat per alguna línia de document. - [Cercar un producte per external ID](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.find_by_external_id): Cerca un únic producte pel seu `external_id` (enviat al body JSON), la clau d'integració que el mapeja a un registre en un sistema de tercers (ERP/CRM/e-commerce). Ortogonal al `sku` del catàleg. Retorna el producte coincident o 404 si cap producte fa servir aquest external_id dins de la teva empresa. - [Cercar un producte per SKU](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.find_by_sku): Cerca un únic producte pel seu `sku` (enviat al cos JSON). Retorna el producte coincident o 404 si cap producte fa servir aquest SKU dins de la teva empresa. - [Elimina una imatge de la galeria d'un producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.gallery.delete): Elimina una imatge de la galeria pel seu índex de base 0. Les imatges restants desplacen les seves posicions per omplir el buit. - [Descarregar el binari d'una imatge de la galeria d'un producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.gallery.download): Transmet el binari en brut d'una imatge de la galeria del producte pel seu índex basat en 0. Retorna 404 si l'índex no existeix o el fitxer no és al disc. - [Puja una imatge de galeria a un producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.gallery.upload): Adjunta una imatge (jpeg, png, jpg, gif o webp; fins a 3 MB) a la galeria del producte. Retorna el producte actualitzat. Falla amb 422 si se supera el límit de la galeria. - [Llistar tots els productes](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.list): Llista els productes del teu catàleg amb paginació per cursor. - [Llista els productes per sota del llindar d'stock](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.low_stock_report): Retorna els productes el stock actual dels quals està per sota del seu llindar de stock baix configurat. Útil per a alertes d'inventari. - [Obtenir analítiques de vendes de productes](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.sales_analytics): Retorna unitats venudes, ingressos, nombre de factures, variació mes a mes, tendència mensual dels últims 6 mesos, últim comprador i feed d'activitat recent d'un sol producte. - [Cerca productes](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.search): Cerca productes per consulta de text lliure contra `name` i `sku`. Limitat a 50 resultats. - [Obtenir un producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.show): Obté un producte pel seu `uuid`. - [Obtenir estadístiques de productes](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.stats): KPIs agregats del teu catàleg de productes: nombre total de productes, nombre d'actius, nombre per sota del llindar d'stock baix, valor d'stock acumulat i totals per categoria. Retornat com a `{ "data": ProductStats }`. - [Alternar l'estat actiu del producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.toggle_active): Canvia un producte entre actiu i inactiu. Els productes inactius s'amaguen dels selectors de línies en documents nous. - [Actualitzar un producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.update): Actualitza un producte del teu catàleg. - [Actualitzar l'stock d'un producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.update_stock): Reemplaça, incrementa o redueix la quantitat de stock d'un producte. Per defecte és set (reemplaçar); add i subtract són àlies acceptats d'increase i decrease. Falla amb 422 si el stock resultant fos negatiu. - [Elimina el vídeo del producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.video.delete): Elimina el vídeo associat al producte i allibera l'emmagatzematge. Idempotent: retorna 204 fins i tot quan no hi havia cap vídeo adjunt. - [Descarregar el binari del vídeo d'un producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.video.download): Transmet el binari en brut del vídeo del producte. Retorna 404 si el producte no té vídeo o el fitxer no és al disc. - [Puja un vídeo a un producte](https://docs.factuarea.com/ca/api-reference/products/public-api.v1.products.video.upload): Adjunta un fitxer de vídeo (mp4, mov, avi o webm; fins a 50 MB) al producte. Reemplaça qualsevol vídeo existent. - [Acceptar una proforma](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.accept): Marca una proforma com a acceptada pel client. Retorna 422 si la proforma està en un estat que no pot transicionar a `accepted`. - [Eliminació massiva de proformes](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.bulk_delete): Elimina fins a 100 proformes en una sola crida. Retorna un `BulkPartialSuccessResult` amb els comptadors `total`, `successful` i `failed` més una llista `failures` (`id` + `error_code` + `error_message` en castellà) per cada entrada que no s'ha pogut eliminar. - [Descarregar en bloc els PDF de proformes](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.bulk_pdf): Empaqueta els PDF de fins a 50 proformes (per id) en un únic ZIP. Els ids no trobats o sense PDF generable no aborten la petició: el ZIP porta només els vàlids i els comptadors per recurs viatgen a les capçaleres de resposta `X-Bulk-*`. - [Enviar proformes en bloc](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.bulk_send): Envia fins a 200 proformes per email (encuat) en una sola crida, reutilitzant la ruta d'enviament individual per id. Retorna un `BulkPartialSuccessResult` amb els comptadors `total`, `successful` i `failed` més una llista `failures` (`id` + `error_code` + `error_message` en castellà) per cada proforma que no s'ha pogut enviar (no trobada, estat no enviable o sense destinatari resoluble). - [Canviar en bloc l'estat de proformes](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.bulk_status): Transiciona fins a 50 factures proforma (per id) a un estat del conjunt tancat `[accepted, rejected]`, cadascuna a través del guard d'estat del document. Retorna un `BulkPartialSuccessResult`; les proformes la transició de les quals es rebutja (no trobades o no transicionables) tornen a `failures[]`. - [Convertir proforma en factura](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.convert): Converteix una proforma en una factura de venda final. La nova factura referencia la proforma d'origen; la proforma passa a l'estat `converted`. - [Crea una proforma](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.create): Crea una nova factura proforma en estat `draft`. Les proformes es poden convertir després en factures finals. - [Elimina una proforma](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.delete): Elimina una proforma. Retorna 422 si la proforma s'ha convertit en factura. - [Duplicar una proforma](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.duplicate): Crea una nova proforma en esborrany copiant línies, client i metadades d'una proforma existent. - [Cercar una proforma per external ID](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.find_by_external_id): Cerca una única proforma pel seu `external_id` (enviat al body JSON), la clau d'integració que la mapeja a un registre en un sistema de tercers (ERP/CRM/e-commerce). Retorna la proforma coincident o 404 `proforma_not_found` si cap proforma fa servir aquest external_id dins de la teva empresa. - [Llistar totes les proformes](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.list): Llista les teves factures proforma amb paginació per cursor. - [Descarregar el PDF de la proforma](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.pdf): Descarrega la representació en PDF d'una proforma. - [Recupera l'enllaç públic de la proforma](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.public_link_get): Retorna la URL pública per compartir de la proforma (/d/{uuid}) juntament amb el seu estat, expiració i els dies màxims d'extensió permesos pel pla. - [Actualitzar l'enllaç públic d'una proforma](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.public_link_update): Aplica una acció a l'enllaç públic: `revoke`, `activate`, `extend` (amb `extend_days`) o `reset` al valor per defecte del pla. - [Rebutjar una proforma](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.reject): Marca una proforma com a rebutjada pel client. Retorna 422 si la proforma està en un estat que no pot transicionar a `rejected`. - [Envia la proforma per email](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.send): Envia una proforma al client per email. - [Obtenir una proforma](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.show): Obté una factura proforma pel seu `uuid`. - [Obtenir estadístiques de proformes](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.stats): KPIs agregats de l'empresa autenticada: nombre i import total de proformes, nombre per estat, nombre d'expirades i nombre convertides a factura. Retornat com a `{ "data": ProformaStats }`. - [Llista els estats de proforma](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.statuses): Retorna el catàleg tancat d'estats de proforma amb el seu `value` públic, `label` localitzada i `color` d'UI. Fes-lo servir per poblar filtres o selectors d'estat en lloc de codificar valors a mà. - [Actualitzar una proforma](https://docs.factuarea.com/ca/api-reference/proformas/public-api.v1.proformas.update): Actualitza una proforma en esborrany. Un cop convertida, la proforma esdevé immutable. - [Adjuntar un fitxer a una factura de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.attach_file): Puja el document PDF original d'una factura de compra com a `multipart/form-data`. Substitueix qualsevol fitxer adjuntat prèviament. Retorna la factura de compra actualitzada. - [Eliminació massiva de factures de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.bulk_delete): Elimina fins a 100 factures de compra per UUID en una sola petició. Retorna un `BulkPartialSuccessResult` amb els comptadors `total`, `successful` i `failed` més una llista `failures` (`id` + `error_code` + `error_message` en castellà) per cada entrada que no s'ha pogut eliminar. - [Canviar en bloc l'estat de factures de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.bulk_status): Transiciona fins a 50 factures de compra (per id) a `paid` en una crida, cadascuna a través del guard d'estat del document. La `payment_date` requerida es propaga tal qual a cada factura (mai `now()`). Retorna un `BulkPartialSuccessResult`; les factures que no van poder transicionar (no trobades o ja pagades) tornen a `failures[]`. - [Crea una factura de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.create): Registra una factura rebuda d'un proveïdor. - [Elimina una factura de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.delete): Elimina una factura de compra. - [Elimina un fitxer d'una factura de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.delete_file): Elimina el fitxer original adjunt a una factura de compra i allibera el seu emmagatzematge. Idempotent: té èxit fins i tot quan no hi havia cap fitxer adjunt. - [Descarregar el fitxer original de la factura de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.file): Transmet el PDF original adjunt a la factura de compra quan es va pujar. Retorna 404 si no hi ha cap adjunt. - [Cercar una factura de compra per external ID](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.find_by_external_id): Cerca una única factura de compra pel seu `external_id` (enviat al body JSON), la clau d'integració que la mapeja a un registre en un sistema de tercers (ERP/CRM/e-commerce). Ortogonal a l'`external_invoice_number` proporcionat pel proveïdor (el número fiscal del proveïdor). Retorna la factura de compra coincident o 404 `purchase_invoice_not_found` si cap fa servir aquest external_id dins de la teva empresa. - [Llistar totes les factures de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.list): Llista les factures de compra rebudes de proveïdors amb paginació per cursor. - [Llistar pagaments de factura de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.list_payments): Retorna el llibre de pagaments complet d'una factura de compra com a `{ "data": [...] }`, ordenat per data de pagament descendent. El llibre d'una sola factura està acotat, així que es retorna el conjunt complet sense paginació per cursor. Una factura sense pagaments retorna un array buit, mai un `404`; un `404` aquí significa que la factura no existeix o pertany a una altra empresa. - [Marca la factura de compra com a pagada](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.mark_paid): Registra el pagament d'una factura de compra. Estableix `paid_at` amb la marca de temps actual. - [Llistar factures de compra vençudes](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.overdue): Retorna les factures de compra la data de venciment de les quals ha passat i continuen impagades. - [Descarregar el rebut de pagament d'una factura de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.payment_receipt): Transmet el PDF del justificant de pagament d'una factura de compra pagada. Retorna 409 si la factura encara no s'ha pagat. - [Llistar factures de compra pendents](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.pending): Retorna les factures de compra en estat de pagament pendent, paginades. - [Registrar un pagament de factura de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.register_payment): Registra un pagament parcial (o total) contra una factura de compra i l'afegeix al seu llibre de pagaments. Cos: `amount`, `paid_on`, `payment_method`, més els opcionals `bank_account_id`, `reference` i `notes`. Es comproven tres invariants que retornen `422`: l'import ha de ser més gran que zero i no superior al saldo pendent, `paid_on` ha de caure entre la data d'emissió de la factura i avui, i una factura cancel·lada no admet pagaments. Tan bon punt els pagaments acumulats cobreixen el total, la factura se salda sola — no cal que cridis també `mark_paid`. Retorna `201` amb el pagament acabat de crear i un header `Location` que apunta al llibre de pagaments. - [Obtenir una factura de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.show): Obté una factura de compra pel seu `uuid`. - [Obtenir estadístiques de factures de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.stats): KPIs agregats de les teves factures de compra: nombre i import total, recomptes per estat, totals pendents i vençuts, i imports per proveïdor. Retornat com a `{ "data": PurchaseInvoiceStats }`. - [Actualitzar una factura de compra](https://docs.factuarea.com/ca/api-reference/purchase-invoices/public-api.v1.purchase_invoices.update): Actualitza una factura de compra. - [Acceptar un pressupost](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.accept): Marca un pressupost com a acceptat pel client. Estableix `accepted_at` al timestamp actual. - [Eliminació massiva de pressupostos](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.bulk_delete): Elimina fins a 100 pressupostos en una sola crida. Retorna un `BulkPartialSuccessResult` amb els comptadors `total`, `successful` i `failed` més una llista `failures` (`id` + `error_code` + `error_message` en castellà) per cada entrada que no s'ha pogut eliminar. - [Descarregar en bloc els PDF de pressupostos](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.bulk_pdf): Empaqueta els PDF de fins a 50 pressupostos (per id) en un únic ZIP. Els ids no trobats o sense PDF generable no aborten la petició: el ZIP porta només els vàlids i els comptadors per recurs viatgen a les capçaleres de resposta `X-Bulk-*`. - [Enviar pressupostos en bloc](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.bulk_send): Envia fins a 200 pressupostos per email (encuat) en una sola crida, reutilitzant la ruta d'enviament individual per id. Retorna un `BulkPartialSuccessResult` amb els comptadors `total`, `successful` i `failed` més una llista `failures` (`id` + `error_code` + `error_message` en castellà) per cada pressupost que no s'ha pogut enviar (no trobat, estat terminal o sense destinatari resoluble). - [Canviar en bloc l'estat de pressupostos](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.bulk_status): Transiciona fins a 50 pressupostos (per id) a un estat del conjunt tancat `[approved, rejected]`, cadascun a través del guard d'estat del document. Retorna un `BulkPartialSuccessResult`; els pressupostos la transició dels quals es rebutja (no trobats o no transicionables) tornen a `failures[]`. - [Convertir pressupost en factura](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.convert): Converteix un pressupost acceptat en una factura de venda. La nova factura referencia el pressupost d'origen mitjançant metadades; el pressupost passa a l'estat `converted`. - [Crea un pressupost](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.create): Crea un nou pressupost de venda en estat `draft`. Els pressupostos es poden convertir després en factures mitjançant `POST /quotes/{quote}/convert`. - [Elimina un pressupost](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.delete): Elimina un pressupost. Retorna 422 si el pressupost s'ha convertit en factura. - [Duplicar un pressupost](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.duplicate): Crea un nou pressupost en esborrany copiant les línies, el client i les metadades d'un pressupost existent. - [Cercar un pressupost per external ID](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.find_by_external_id): Cerca un únic pressupost pel seu `external_id` (enviat al body JSON), la clau d'integració que el mapeja a un registre en un sistema de tercers (ERP/CRM/e-commerce). Retorna el pressupost coincident o 404 `quote_not_found` si cap pressupost fa servir aquest external_id dins de la teva empresa. - [Llistar tots els pressupostos](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.list): Llista els teus pressupostos de venda amb paginació per cursor. Admet filtratge per `status[in]`, `client_id`, `issued_on[gte|lte]`. - [Descarregar el PDF del pressupost](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.pdf): Descarrega la representació en PDF d'un pressupost. - [Recupera l'enllaç públic del pressupost](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.public_link_get): Retorna la URL pública per compartir del pressupost (/d/{uuid}) juntament amb el seu estat, expiració i els dies màxims d'extensió permesos pel pla. - [Actualitzar l'enllaç públic d'un pressupost](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.public_link_update): Aplica una acció a l'enllaç públic: `revoke`, `activate`, `extend` (amb `extend_days`) o `reset` al valor per defecte del pla. - [Rebutjar un pressupost](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.reject): Marca un pressupost com a rebutjat pel client. Estableix `rejected_at` al timestamp actual. - [Envia el pressupost per email](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.send): Envia un pressupost al client per email. - [Obtenir un pressupost](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.show): Obté un pressupost de venda pel seu `uuid`. - [Obtenir estadístiques de pressupostos](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.stats): KPIs agregats de l'empresa autenticada: nombre i import total de pressupostos, nombre per estat, nombre d'expirats i nombre de convertits. Retornat com a `{ "data": QuoteStats }`. - [Llista els estats de pressupost](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.statuses): Retorna la llista canònica d'estats de pressupost disponibles a l'API juntament amb la seva etiqueta llegible i el seu color d'UI. Útil per construir desplegables i filtres. - [Actualitzar un pressupost](https://docs.factuarea.com/ca/api-reference/quotes/public-api.v1.quotes.update): Actualitza un pressupost en esborrany. Un cop acceptat/rebutjat/convertit, el pressupost esdevé immutable. - [Activar factura recurrent](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.activate): Activa una factura recurrent pausada. La següent factura es generarà segons la programació. És un àlies semàntic de `POST /recurring_invoices/{recurring_invoice}/resume` — tots dos apunten al mateix handler i es comporten igual; cap dels dos està obsolet. - [Llista l'activitat de factures recurrents](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.activities): Retorna la línia de temps d'activitat paginada per cursor (esdeveniments de domini: activació, pausa, represa, generació, error, cancel·lació, etc.) d'una factura recurrent. Les metadades es sanegen per no exposar mai identificadors interns. - [Eliminació massiva de factures recurrents](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.bulk-delete): Elimina diverses factures recurrents en una sola petició (POST amb un body d'`ids`). Retorna el recompte de recursos eliminats i una llista de fallades amb el seu motiu. Les factures recurrents que ja han generat factures no es poden eliminar. - [Anul·lar factura recurrent](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.cancel): Anul·la una factura recurrent. A diferència de `pause`, aquest és un estat terminal i irreversible: una factura recurrent anul·lada no es pot reprendre ni reactivar mai. Les factures generades prèviament no es veuen afectades. - [Crea una factura recurrent](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.create): Crea una plantilla de factura recurrent que genera factures automàticament amb una cadència fixa (setmanal, mensual, trimestral, anual). - [Elimina una factura recurrent](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.delete): Elimina una plantilla de factura recurrent. Les factures futures deixen de generar-se; les factures existents es conserven. - [Cercar una factura recurrent per external ID](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.find_by_external_id): Cerca una única plantilla de factura recurrent pel seu `external_id` (enviat al body JSON), la clau d'integració que la mapeja a un registre en un sistema de tercers (ERP/CRM/e-commerce). Retorna la factura recurrent coincident o 404 `recurring_invoice_not_found` si cap fa servir aquest external_id dins de la teva empresa. - [Genera una factura a partir d'una plantilla recurrent](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.generate): Dispara la generació immediata de factura a partir de la configuració recurrent, fora del cicle programat. - [Llistar totes les factures recurrents](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.list): Llista les teves plantilles de factures recurrents amb paginació per cursor. - [Llista els logs d'execució de factures recurrents](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.logs): Retorna l'historial paginat de generacions, errors i altres esdeveniments d'aquesta plantilla recurrent. - [Pausar factura recurrent](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.pause): Pausa una factura recurrent. No es generaran noves factures fins que es reprengui. Reversible — fes servir `resume`/`activate` per reactivar-la. Per a una aturada permanent i irreversible fes servir `cancel`. - [Vista prèvia de les properes dates de la factura recurrent](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.preview): Retorna les pròximes dates d'execució programades amb les seves dates de venciment i imports estimats. Per defecte 5 ocurrències. - [Reprendre factura recurrent](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.resume): Reprèn una factura recurrent pausada. És un àlies semàntic de `POST /recurring_invoices/{recurring_invoice}/activate` — tots dos apunten al mateix handler i es comporten de manera idèntica; cap dels dos està deprecat. - [Obtenir una factura recurrent](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.show): Obté una plantilla de factura recurrent pel seu `uuid`. - [Ometre la pròxima generació de la factura recurrent](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.skip): Avança la factura recurrent a la seva següent execució programada sense generar una factura per al cicle actual. L'ocurrència omesa no compta contra cap límit d'ocurrències. Les factures recurrents cancel·lades o completades retornen 422. - [Recupera les estadístiques de factures recurrents](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.stats): KPIs agregats de les teves factures recurrents: recomptes per estat, vencen avui / aquesta setmana, generades i fallides aquest mes, desglossament per freqüència, properes execucions programades i ingressos estimats aquest mes. - [Actualitzar una factura recurrent](https://docs.factuarea.com/ca/api-reference/recurring-invoices/public-api.v1.recurring_invoices.update): Actualitza una plantilla de factura recurrent. La cadència i les línies s'apliquen a les factures generades després de l'actualització; les factures generades prèviament no es veuen afectades. - [Llistar sèries actives per tipus de document](https://docs.factuarea.com/ca/api-reference/series/public-api.v1.series.active): Retorna totes les sèries no arxivades del tipus de document indicat dins la teva empresa. - [Llista la línia temporal d'activitat de la sèrie](https://docs.factuarea.com/ca/api-reference/series/public-api.v1.series.activities): Retorna la línia de temps d'auditoria d'una sèrie combinant els seus propis esdeveniments de domini (creació, arxivament/desarxivament, canvis de predeterminat, consum de numeració). Paginada amb un cursor de número de pàgina (`starting_after` és el número de la pàgina següent). - [Arxivar una sèrie](https://docs.factuarea.com/ca/api-reference/series/public-api.v1.series.archive): Arxiva una sèrie perquè deixi d'aparèixer com a disponible per a nous documents. Falla amb 409 si la sèrie és la predeterminada i l'única sèrie activa del seu tipus. Retorna 204 en cas d'èxit. - [Crea les sèries per defecte d'una empresa](https://docs.factuarea.com/ca/api-reference/series/public-api.v1.series.bootstrap): Deixa una empresa en condicions d'emetre documents en una sola crida: per a cada tipus de document de la superfície pública (`invoice`, `quote`, `delivery_note`, `proforma`) que no tingui sèrie activa, crea la seva sèrie per defecte amb el codi i el nom canònics. Sense cos de petició. **Què retorna** - Una entrada per tipus de document, amb un `status` de `created`, `existing` o `no_default`. - `no_default` significa que el tipus té sèries actives però cap marcada per defecte — arxivar la sèrie per defecte la degrada sense promoure'n cap substituta — i l'empresa continua sense poder emetre aquell document. - Tracta `no_default` com a feina pendent, no com a èxit: les sèries actives arriben a `candidates` i ho resols amb `POST /v1/series/{id}/default`. **Per què no tria per tu** Triar quina sèrie numera els documents d'una empresa té conseqüències registrals que només tu pots decidir, així que el bootstrap no en promou mai cap en el teu lloc. **Si el crides dues vegades** - Idempotent per regla de negoci: una segona crida no crea res, no falla i torna a informar de l'estat. - INDEPENDENT del header `Idempotency-Key`: amb el header, una clau repetida repeteix el cos original — entrades `created` incloses — en lloc d'informar de l'estat actual. - [Crea una sèrie](https://docs.factuarea.com/ca/api-reference/series/public-api.v1.series.create): Crea una sèrie de numeració de documents. L'opcional `number_format` fixa la màscara de numeració (p. ex. `{code}-{YYYY}-{00000}`) i `initial_number` (≥1) arrenca el comptador per continuar una numeració existent. El mateix codi es pot reutilitzar entre tipus de document (multi-series). Una sèrie és immutable un cop creada segons AEAT (`PUT` retorna 405), així que això només es pot fixar aquí. - [Obtenir la sèrie per defecte per a un tipus de document](https://docs.factuarea.com/ca/api-reference/series/public-api.v1.series.default): Retorna la sèrie de numeració predeterminada per al tipus de document indicat (invoice, quote, proforma, delivery_note). Retorna 404 quan no hi ha predeterminat configurat. - [Cercar una sèrie per codi](https://docs.factuarea.com/ca/api-reference/series/public-api.v1.series.find_by_code): Cerca una sèrie pel seu `code` (cos JSON, sense distingir majúscules). Un `code` no és únic entre tipus de document (multi-series), així que passa `document_type` per resoldre la sèrie `(code, document_type)` exacta. Si l'omets, el codi es cerca a tots els tipus: es retorna una única coincidència, però un codi ambigu retorna 422 `document_type_required_for_ambiguous_code` en lloc de triar-ne un en silenci. Retorna 404 si no n'existeix cap. - [Llistar totes les sèries](https://docs.factuarea.com/ca/api-reference/series/public-api.v1.series.list): Llista les teves sèries de numeració de documents amb paginació per cursor. - [Marca una sèrie com a predeterminada per al seu tipus](https://docs.factuarea.com/ca/api-reference/series/public-api.v1.series.set_default): Promou una sèrie a predeterminada per al seu tipus de document. Si una altra sèrie era la predeterminada per al mateix tipus, es degrada de manera atòmica. Retorna 204 en cas d'èxit. - [Obtenir una sèrie](https://docs.factuarea.com/ca/api-reference/series/public-api.v1.series.show): Obté una sèrie pel seu `uuid`. Les sèries són **immutables** per compliment fiscal (AEAT VeriFactu — continuïtat legal de la numeració): `PUT`, `PATCH` i `DELETE` sobre `/v1/series/{uuid}` retornen `405 Method Not Allowed` amb `error.code = "series_immutable"` i la capçalera `Allow: GET, POST`. Per "eliminar" una sèrie fes servir `POST /v1/series/{uuid}/archive`; per canviar la numeració, crea una nova sèrie i marca-la com a predeterminada. - [Obtenir estadístiques de sèries](https://docs.factuarea.com/ca/api-reference/series/public-api.v1.series.stats): KPIs agregats de les teves sèries de numeració de documents: nombre total de sèries, nombre d'actives i arxivades, i desglossament per tipus de document. Retornat com a `{ "data": SeriesStats }`. - [Desarxivar una sèrie](https://docs.factuarea.com/ca/api-reference/series/public-api.v1.series.unarchive): Retorna una sèrie arxivada al conjunt actiu. No canvia el predeterminat actual del seu tipus. Retorna 204 si té èxit. - [Llistar payouts de Stripe](https://docs.factuarea.com/ca/api-reference/stripe/public-api.v1.payouts.list): Llista els payouts de Stripe ingerits per a la teva empresa, amb paginació per cursor. Cadascun exposa els imports net/comissions/brut, la moneda, la data d'arribada, l'`status` de conciliació (`ingested`/`reconciled`) i una `composition` informativa. Filtra per `status` i per finestra de data d'arribada. Els payouts són de només lectura; la conciliació bancària passa al dashboard. - [Obtenir un payout de Stripe](https://docs.factuarea.com/ca/api-reference/stripe/public-api.v1.payouts.show): Obtén un payout de Stripe pel seu `id` (UUID v7). Retorna els imports, la divisa, la data d'arribada, l'estat de conciliació (`bank_transaction_ref` un cop conciliat) i la `composition` informativa dels cobraments components. Retorna 404 si el payout no existeix o pertany a una altra empresa. - [Desconnectar un compte Stripe connectat](https://docs.factuarea.com/ca/api-reference/stripe/public-api.v1.stripe_autoinvoicing.accounts.disconnect): Desconnecta un compte de Stripe connectat sense tocar els altres. El compte es marca `disconnected` (les seves factures ja emeses i el seu històric es conserven; els webhooks posteriors es registren sense processar). Respon 204 sense cos. Un compte inexistent o d'una altra empresa retorna 404. - [Llistar comptes Stripe connectats](https://docs.factuarea.com/ca/api-reference/stripe/public-api.v1.stripe_autoinvoicing.accounts.list): Llista els comptes de Stripe connectats (Stripe Connect, multi-botiga) de la teva empresa. Cadascun exposa el seu `id`, `name`, `external_account_id` (`acct_xxx`), la `series_id` assignada, la seva configuració per compte (`autoinvoicing_enabled`, `simplified_threshold_cents`, `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`), `status` i `connected_at`. Els càrrecs s'autofacturen amb la sèrie i la configuració d'aquell compte. - [Obtenir un compte Stripe connectat](https://docs.factuarea.com/ca/api-reference/stripe/public-api.v1.stripe_autoinvoicing.accounts.show): Obté un compte Stripe connectat pel seu `id` (UUID v7). Retorna el seu nom, id de compte extern, sèrie assignada (`series_id`), la configuració efectiva d'autofacturació per compte i el seu estat. Retorna 404 si el compte no existeix o pertany a una altra empresa. - [Actualitzar un compte Stripe connectat](https://docs.factuarea.com/ca/api-reference/stripe/public-api.v1.stripe_autoinvoicing.accounts.update): Actualitza un compte de Stripe connectat: el seu `name`, la `series_id` d'autofacturació (`null` la esborra, tornant a la sèrie per defecte de l'empresa) i la política fiscal per compte (`autoinvoicing_enabled`, `simplified_threshold_cents`, `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`). Tots els camps són opcionals; els omesos mantenen el seu valor. - [Obtenir la configuració d'auto-facturació de Stripe](https://docs.factuarea.com/ca/api-reference/stripe/public-api.v1.stripe_autoinvoicing.config.show): Retorna l'estat de la integració de Stripe Connect i la configuració d'autofacturació: si Stripe està connectat i activat, la sèrie usada, el gating per pla, i la política fiscal (`simplified_threshold_cents`, `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`). Amb diversos comptes connectats retorna 422 `per_account_config_required` —llegeix cadascun via `GET /v1/connected-accounts`. - [Actualitzar la configuració d'auto-facturació de Stripe](https://docs.factuarea.com/ca/api-reference/stripe/public-api.v1.stripe_autoinvoicing.config.update): Activa o desactiva l'autofacturació dels càrrecs de Stripe Connect i tria la sèrie usada. Opcionalment ajusta la política fiscal (`simplified_threshold_cents` en cèntims [0, 300000], `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`); els camps omesos mantenen el seu valor. Amb diversos comptes connectats retorna 422 `per_account_config_required` —configura cada compte individualment. - [Llistar les rectificatives auto-facturades de Stripe](https://docs.factuarea.com/ca/api-reference/stripe/public-api.v1.stripe_autoinvoicing.correctives.list): Llista les factures rectificatives generades automàticament a partir de devolucions de Stripe (`charge.refunded`), amb paginació per cursor. L'`id` públic és la factura rectificativa (UUID v7); `original_invoice_id` enllaça amb la factura original, i `refund_id` és la devolució d'origen de la passarel·la. - [Llistar cobraments auto-facturats de Stripe](https://docs.factuarea.com/ca/api-reference/stripe/public-api.v1.stripe_autoinvoicing.payments.list): Llista els càrrecs de Stripe que van generar una factura (fluxos A i B més cicles de subscripció), amb paginació per cursor. La factura i el client generats es retornen com a `invoice_id`/`client_id`. Els càrrecs de cicle de subscripció també exposen `subscription_id` (extern `sub_xxx`), `stripe_invoice_id` i el període facturat. Filtra per `origin` (`subscription`/`oneshot`). - [Llista la línia temporal d'activitat del proveïdor](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.activities): Retorna la línia de temps d'auditoria d'un proveïdor combinant els seus propis esdeveniments de domini més els esdeveniments de factura de compra i contracte que el referencien. Paginada amb els query params page i per_page (50 per defecte). - [Elimina diversos proveïdors de forma massiva](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.bulk_delete): Elimina fins a 200 proveïdors en una sola petició. Retorna un `BulkPartialSuccessResult` amb els comptadors `total`, `successful` i `failed` més una llista `failures` (`id` + `error_code` + `error_message` en castellà); els proveïdors amb contractes associats es reporten a `failures`. Els UUIDs d'altres tenants s'ignoren. - [Canviar en bloc l'estat actiu de proveïdors](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.bulk_status): Mou fins a 50 proveïdors (per id) al `new_status` destí (`active` o `inactive`). Idempotent respecte al destí: un proveïdor ja en l'estat sol·licitat compta com a `successful` sense canviar. Retorna un `BulkPartialSuccessResult`; els proveïdors no trobats tornen a `failures[]`. - [Crea un proveïdor](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.create): Crea un nou proveïdor per a la teva empresa. L'objecte retornat inclou el `uuid` generat. - [Elimina un proveïdor](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.delete): Elimina un proveïdor. Retorna 422 si el proveïdor està referenciat per alguna factura de compra. - [Cercar un proveïdor per external ID](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.find_by_external_id): Cerca un proveïdor pel seu `external_id` (enviat al body JSON), la clau d'integració persistent que el mapeja a un registre en un sistema de tercers (ERP/CRM). Diferent del `tax_id` fiscal i de l'`Idempotency-Key` a nivell de petició. Retorna el proveïdor coincident o 404 si cap proveïdor fa servir aquest external_id dins de la teva empresa. - [Cercar un proveïdor per tax ID](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.find_by_tax_id): Cerca un proveïdor pel seu identificador fiscal espanyol (NIF/CIF/NIE/VAT). Retorna el proveïdor coincident o 404 si cap proveïdor fa servir aquest tax_id dins de la teva empresa. - [Llistar tots els proveïdors](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.list): Llista els teus proveïdors amb paginació per cursor. Admet filtratge per `is_active`, `created_at[gte|lte]`. - [Cerca proveïdors](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.search): Cerca proveïdors per consulta de text lliure contra `name`, `tax_id`, `vat_id`, `email` i `phone`. Limitat a 50 resultats. - [Obtenir un proveïdor](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.show): Obté un proveïdor pel seu `uuid`. - [Obtenir estadístiques de proveïdors](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.stats): KPIs agregats de l'empresa autenticada: nombre total de proveïdors, nombre d'actius, nombre amb contractes i imports totals per estat. Retornat com a `{ "data": SupplierStats }`. - [Alternar l'estat actiu del proveïdor](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.toggle_active): Canvia un proveïdor entre actiu i inactiu. Els proveïdors inactius s'amaguen dels selectors de línies en factures de compra noves. - [Actualitzar un proveïdor](https://docs.factuarea.com/ca/api-reference/suppliers/public-api.v1.suppliers.update): Actualitza un proveïdor. Només es modifiquen els camps presents al payload. - [Llista les activitats d'informes d'impostos](https://docs.factuarea.com/ca/api-reference/tax-reports/public-api.v1.tax_reports.activities): Retorna la línia de temps d'activitat paginada per cursor (generació, descàrrega, etc.) d'una única generació d'informe fiscal. - [Descarregar el fitxer de l'informe d'impostos](https://docs.factuarea.com/ca/api-reference/tax-reports/public-api.v1.tax_reports.download): Descarrega el fitxer generat d'un informe fiscal. Afegeix el header `X-Tax-Report-Hash` per a la verificació d'integritat. - [Cercar un informe d'impostos per període](https://docs.factuarea.com/ca/api-reference/tax-reports/public-api.v1.tax_reports.find_by_period): Cerca l'informe fiscal generat més recent per a un tipus i període donats. Retorna l'informe o 404 `tax_report_not_found` quan no n'existeix cap per al període. - [Generar Model 130](https://docs.factuarea.com/ca/api-reference/tax-reports/public-api.v1.tax_reports.generate_130): Genera el Model 130 espanyol (pagament fraccionat trimestral de l'IRPF, estimació directa) per a l'any i trimestre donats en el format sol·licitat (txt_aeat, pdf, excel; per defecte pdf). El càlcul és acumulatiu des de l'inici de l'any (de l'1 de gener al tancament del trimestre). - [Generar Modelo 303](https://docs.factuarea.com/ca/api-reference/tax-reports/public-api.v1.tax_reports.generate_303): Genera el Modelo 303 espanyol (IVA trimestral) per a l'any i trimestre indicats en el format sol·licitat (txt_aeat, pdf, excel). - [Generar Modelo 347](https://docs.factuarea.com/ca/api-reference/tax-reports/public-api.v1.tax_reports.generate_347): Genera el Modelo 347 espanyol (operacions anuals amb tercers > 3,005.06 EUR) per a l'any indicat. - [Llista l'historial d'informes d'impostos](https://docs.factuarea.com/ca/api-reference/tax-reports/public-api.v1.tax_reports.history): Retorna l'històric paginat d'informes fiscals generats de l'empresa. Filtres opcionals: type, year. - [Vista prèvia d'un informe d'impostos](https://docs.factuarea.com/ca/api-reference/tax-reports/public-api.v1.tax_reports.preview): Calcula el desglossament d'un informe fiscal sense persistir una generació ni escriure fitxers. Ideal per a UIs interactives que confirmen els totals abans de consolidar. - [Recupera les estadístiques de l'informe d'impostos](https://docs.factuarea.com/ca/api-reference/tax-reports/public-api.v1.tax_reports.stats): Retorna KPIs agregats de l'històric d'informes fiscals generats: totals per tipus i format, mida de fitxer acumulada, i el trimestre/any fiscal actual. - [Obtenir el saldo horari d'un empleat per a un període](https://docs.factuarea.com/ca/api-reference/time-balances/public-api.v1.time_balances.employee): Retorna el saldo horari d'un període arbitrari d'un empleat: minuts esperats vs treballats, el saldo i les hores extra per dia, i els totals del període. L'empleat és el `{employee}` (UUID v7) de la ruta; `from` i `to` (`YYYY-MM-DD`) són obligatoris. És el mateix contracte que el tancament mensual reutilitza sobre períodes tancats. Un rang on `to` és anterior a `from` retorna 422. Els totals estan en minuts. Un recurs computat: exposa `employee_id`, mai un `id`. - [Obtenir el full horari mensual d'un empleat](https://docs.factuarea.com/ca/api-reference/time-balances/public-api.v1.time_balances.monthly_sheet): Retorna el full horari mensual en viu d'un empleat per al període obert (en curs): minuts esperats vs treballats, el saldo i les hores extra per dia, i els totals mensuals. `employee_id` (UUID v7) és obligatori; `month` (`YYYY-MM`) pren per defecte el mes actual. El full es recomputa en cada petició des del registre inalterable, així que un fitxatge acabat de registrar es reflecteix sense tancar el mes. Els minuts esperats descompten festius i absències aprovades. Els totals estan en minuts. Un recurs computat: exposa `employee_id`, mai un `id`. - [Obtenir el resum de saldo horari de l'equip](https://docs.factuarea.com/ca/api-reference/time-balances/public-api.v1.time_balances.team_summary): Retorna el resum de saldo horari de l'equip (vista de responsable) per a un mes: una fila per empleat actiu amb els seus minuts esperats, treballats, saldo i hores extra. `month` (`YYYY-MM`) pren per defecte el mes actual. Només s'inclouen els empleats actius amb un horari. Els totals estan en minuts. Un recurs computat sense `id`. - [Aprovar una correcció de fitxatge](https://docs.factuarea.com/ca/api-reference/time-corrections/public-api.v1.time_corrections.approve): Aprova una sol·licitud de correcció pendent pel seu `id` (UUID v7), afegint la `correction_entry` resolutòria enllaçada al fitxatge original. Es pot aportar una `note` opcional de l'aprovador. Una sol·licitud que no està pendent retorna 422 (ja resolta), i aprovar la teva pròpia sol·licitud retorna 422 (l'autoaprovació està prohibida). Retorna 200 amb la correcció resolta. - [Sol·licitar una correcció de fitxatge](https://docs.factuarea.com/ca/api-reference/time-corrections/public-api.v1.time_corrections.create): Sol·licita la correcció d'un fitxatge (RD-llei 8/2019). `time_entry_id` (UUID v7 de l'entrada a corregir), `kind` (`add_missing_entry`/`adjust_time`/`remove_entry`), un `reason` i els valors `proposed` són obligatoris. Una correcció és una nova entrada de només addició que referencia l'entrada original sense mutar-la (anàleg a una factura rectificativa); el flux queda `pending` fins que un responsable l'aprova o rebutja. Retorna 201 amb la sol·licitud creada i una capçalera `Location`. - [Llistar totes les correccions de fitxatge](https://docs.factuarea.com/ca/api-reference/time-corrections/public-api.v1.time_corrections.list): Llista les sol·licituds de correcció de fitxatge de la teva empresa amb paginació per cursor, ordenades per hora de sol·licitud. Admet filtrar per `status` (`pending` és la safata del responsable, `approved`/`rejected` estan resoltes), `employee_id` (UUID v7) i un rang de dates (`from`/`to`). - [Rebutjar una correcció de fitxatge](https://docs.factuarea.com/ca/api-reference/time-corrections/public-api.v1.time_corrections.reject): Rebutja una sol·licitud de correcció pendent pel seu `id` (UUID v7) amb un `reason` obligatori, resolent-la sense tocar el fitxatge original. Una sol·licitud que no està pendent retorna 422 (ja resolta). Retorna 200 amb la correcció resolta. - [Obtenir una correcció de fitxatge](https://docs.factuarea.com/ca/api-reference/time-corrections/public-api.v1.time_corrections.show): Obtén una única sol·licitud de correcció pel seu `id` (UUID v7), inclòs el seu estat derivat. Una sol·licitud pertanyent a una altra empresa retorna 404 `correction_request_not_found` (anti-enumeració). - [Validar la cadena de hashes del registre de jornada](https://docs.factuarea.com/ca/api-reference/time-entries/public-api.v1.time_entries.chain.validate): Recomputa la cadena de hashes SHA-256 (`huella`) del registre de jornada de la teva empresa i la compara amb els valors persistits sense mutar dades. Retorna si la cadena està intacta i, si no, l'`id` (UUID v7) del primer registre corrupte — les empremtes en si mai s'exposen. Limitat a 1 petició/minut i rebutjat amb 422 `dataset_too_large` per a conjunts de més de 50.000 registres. - [Fitxar l'entrada d'un empleat](https://docs.factuarea.com/ca/api-reference/time-entries/public-api.v1.time_entries.clock_in): Fitxa l'inici de la jornada d'un empleat, obrint un nou tram de treball. `employee_id` (UUID v7) i `source` (`web`/`mobile`) són obligatoris; `occurred_at` pren per defecte l'hora del servidor. Vàlid només quan l'empleat no ha fitxat ja l'entrada; una transició no vàlida retorna 422 en castellà. Retorna 201 amb l'entrada `clock_in` creada. - [Fitxar la sortida d'un empleat](https://docs.factuarea.com/ca/api-reference/time-entries/public-api.v1.time_entries.clock_out): Fitxa el final del tram de treball actual de l'empleat (des de `working` o `paused`). `employee_id` (UUID v7) i `source` són obligatoris. Vàlid només quan hi ha un tram obert; una transició no vàlida retorna 422 en castellà. Retorna 201 amb l'entrada `clock_out` creada. - [Obtenir l'estat de jornada actual d'un empleat](https://docs.factuarea.com/ca/api-reference/time-entries/public-api.v1.time_entries.current): Retorna l'estat derivat de la jornada actual d'un empleat (`not_started`/`working`/`paused`/`finished`), reconstruït des del tram de treball obert en el registre inalterable — no hi ha taula de sessió. `employee_id` (UUID v7) és obligatori com a paràmetre de query. - [Llistar tots els fitxatges](https://docs.factuarea.com/ca/api-reference/time-entries/public-api.v1.time_entries.list): Llista els fitxatges de la teva empresa amb paginació per cursor, ordenats per `occurred_at`. Admet filtrar per `employee_id` (UUID v7), un rang de dates (`from`/`to`) i `entry_type` (`clock_in`/`pause_start`/`pause_end`/`clock_out`). - [Registrar una entrada manual retroactiva](https://docs.factuarea.com/ca/api-reference/time-entries/public-api.v1.time_entries.manual): Registra un tram de treball passat d'un empleat (una entrada manual retroactiva). `employee_id` (UUID v7), `started_at`, `ended_at` i un `reason` són obligatoris; els `pauses` opcionals afegeixen intervals de pausa. Les entrades s'emmagatzemen amb `is_retroactive: true` i `source: manual`, i s'escriu una entrada de log d'auditoria. `ended_at` anterior a `started_at`, o un motiu absent, retorna 422 en castellà. Retorna 201 amb l'entrada `clock_out` del tram creat. - [Iniciar una pausa](https://docs.factuarea.com/ca/api-reference/time-entries/public-api.v1.time_entries.pause): Inicia una pausa en el tram de treball actual de l'empleat. `employee_id` (UUID v7) i `source` són obligatoris. Vàlid només quan l'empleat està `working`; una transició no vàlida retorna 422 en castellà. Retorna 201 amb l'entrada `pause_start` creada. - [Reprendre després d'una pausa](https://docs.factuarea.com/ca/api-reference/time-entries/public-api.v1.time_entries.resume): Reprèn la jornada de l'empleat després d'una pausa. `employee_id` (UUID v7) i `source` són obligatoris. Vàlid només quan l'empleat està `paused`; una transició no vàlida retorna 422 en castellà. Retorna 201 amb l'entrada `pause_end` creada. - [Obtenir un fitxatge](https://docs.factuarea.com/ca/api-reference/time-entries/public-api.v1.time_entries.show): Obtén un únic fitxatge pel seu `id` (UUID v7). Una entrada pertanyent a una altra empresa retorna 404 `time_record_entry_not_found` (anti-enumeració). - [Obtenir la configuració de control horari](https://docs.factuarea.com/ca/api-reference/time-tracking-settings/public-api.v1.time_tracking_settings.show): Retorna la configuració de control horari de la teva empresa: la base de còmput d'hores extra (`weekly`/`daily`) i els llindars, la tolerància d'arrodoniment i els ajustos del recordatori de fitxatge oblidat. Si la teva empresa encara no l'ha configurat, es retornen els valors per defecte amb `id: null` — la primera actualització materialitza la fila. - [Actualitzar la configuració de control horari](https://docs.factuarea.com/ca/api-reference/time-tracking-settings/public-api.v1.time_tracking_settings.update): Crea o actualitza la configuració de control horari de la teva empresa: `overtime_basis` (`weekly`/`daily`), els llindars opcionals d'hores extra diari/setmanal en minuts (`null` els deriva de l'horari), la tolerància d'arrodoniment `overtime_tolerance_minutes`, i l'interruptor del recordatori de fitxatge i els seus minuts de gràcia. Un llindar o tolerància negatius retornen 422 en castellà. Retorna els ajustos actualitzats amb `id` = UUID v7 de la fila. - [Forçar la creació del registre VeriFactu d'una factura](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.invoices.verifactu_create): Crea el registre d'alta VeriFactu per a una factura ja emesa i encua la transmissió a l'AEAT. Fes-lo servir quan la creació automàtica en enviar es va ometre. - [Recupera el registre VeriFactu de la factura](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.invoices.verifactu_get): Retorna el registre VeriFactu (SIF de l'AEAT) associat a la factura si existeix. Respon amb `data: null` quan la factura encara no té registre. - [Llistar registres d'accés d'AEAT](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.aeat_access.list): Retorna el llibre d'accessos AEAT dissociat (anonimitzat) amb paginació per cursor. Els identificadors fiscals de tercers (NIF) mai no s'exposen; el cursor usa l'UUID v7 del registre subjacent només per ordenar. - [Obtenir un registre d'accés a AEAT](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.aeat_access.show): Obté un únic registre d'accés AEAT dissociat pel seu `id` (UUID v7). Retorna 404 si el registre no existeix o pertany a una altra empresa. - [Activar un certificat d'empresa](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.certificates.activate): Converteix en actiu un certificat pujat prèviament. Qualsevol altre certificat actiu es desactiva de manera atòmica. Retorna 404 si el certificat no existeix a la teva empresa. - [Recupera el certificat actiu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.certificates.active): Retorna el certificat FNMT actualment actiu usat per signar les transmissions VeriFactu. Retorna 404 si encara no s'ha pujat cap certificat. - [Llistar certificats de l'empresa](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.certificates.list): Llista els certificats FNMT (PKCS#12) pujats de la teva empresa. La contrasenya del certificat mai no s'exposa en aquesta representació. - [Revoca un certificat d'empresa](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.certificates.revoke): Revoca (elimina) un certificat de l'empresa perquè ja no pugui signar transmissions VeriFactu. Retorna 404 si el certificat no existeix a la teva empresa. - [Puja un certificat d'empresa](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.certificates.upload): Puja un certificat FNMT (PKCS#12, `.p12`/`.pfx`) com a `multipart/form-data` amb `certificate_file` i `certificate_password`. El fitxer es valida per magic bytes (ASN.1 DER) i es limita a 100 KB; la contrasenya es xifra en repòs. El certificat pujat s'activa automàticament (els anteriors es desactiven). El header `Location` apunta a `/v1/verifactu/certificates/active`. - [Valida la cadena de hashes de VeriFactu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.chain.validate): Recalcula la cadena d'empremtes VeriFactu (`huella`) de la teva empresa i la compara amb els valors persistits sense mutar dades. Retorna si la cadena està íntegra i, si no, el primer registre corrupte. Limitat a 1 petició/minut i rebutjat amb 422 `dataset_too_large` per a conjunts de més de 50,000 registres. - [Recupera la configuració de VeriFactu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.config): Retorna la configuració VeriFactu de la teva empresa (mode, entorn, estat d'alta). La contrasenya del certificat mai no s'exposa. Es retorna com a `{ "data": VeriFactuConfig }`. - [Recupera la declaración responsable actual](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.declaracion.current): Retorna la versió vigent (la més recent) de la Declaración Responsable VeriFactu a nivell de productor. Només lectura: la declaració és global del productor del sistema (Factuarea), no per empresa. Retorna 404 `declaracion_not_found` si no se n'ha publicat cap. - [Llistar l'historial de declaració responsable](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.declaracion.history): Retorna totes les versions de la Declaración Responsable VeriFactu a nivell de productor (la declaració de compliment SIF emesa per Factuarea), ordenades per `version` descendent. Només lectura: la declaració és global del productor del sistema, no per empresa. - [Llista els esdeveniments de VeriFactu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.events.list): Llista els esdeveniments SIF de VeriFactu de la teva empresa (transmissions d'alta/anul·lació, reintents, respostes de l'AEAT) amb paginació per cursor. - [Reintenta un esdeveniment de VeriFactu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.events.retry): Torna a encuar la transmissió a l'AEAT d'un esdeveniment VeriFactu fallit. Retorna 404 si l'esdeveniment no existeix, 422 `business_rule_violation` / `event_already_processed` si ja va ser acceptat, i 422 `max_retries_exceeded` quan s'assoleix el límit de reintents. - [Obtenir un esdeveniment VeriFactu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.events.show): Obté un únic esdeveniment SIF de VeriFactu pel seu `id` (UUID v7). Retorna 404 si l'esdeveniment no existeix o pertany a una altra empresa. - [Obtenir el resum d'esdeveniments de VeriFactu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.events.summary): Retorna un resum agregat dels teus esdeveniments SIF de VeriFactu agrupats per tipus i resultat. Útil per a dashboards. Es retorna com a `{ "data": VeriFactuEventSummary }`. - [Llista la línia temporal d'activitat del registre VeriFactu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.records.activities): Retorna la línia de temps d'auditoria d'un únic registre VeriFactu (creació, intents de transmissió, acceptació/rebuig de l'AEAT). Paginada amb un cursor de número de pàgina. - [Cercar un registre VeriFactu per CSV de l'AEAT](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.records.find_by_csv): Cerca un registre VeriFactu per l'`aeat_csv` (Código Seguro de Verificación) retornat per l'AEAT en acceptar, enviat al cos JSON. Retorna el registre coincident o 404 `verifactu_record_not_found`. - [Cercar un registre VeriFactu per hash](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.records.find_by_huella): Cerca un registre VeriFactu per la seva `huella` (l'empremta SHA-256 encadenada, enviada al cos JSON). Retorna el registre coincident o 404 `verifactu_record_not_found` si no n'existeix cap a la teva empresa. - [Cercar un registre VeriFactu per número de factura](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.records.find_by_invoice_number): Cerca el registre VeriFactu associat a un número de factura donat (enviat al cos JSON). Retorna el registre coincident o 404 `verifactu_record_not_found` si la factura no té registre a la teva empresa. - [Llista els registres VeriFactu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.records.list): Llista els registres VeriFactu (SIF de l'AEAT) de la teva empresa amb paginació per cursor. Cada registre captura l'alta/anul·lació presentada a l'AEAT, la seva cadena d'empremtes (`huella`), l'`aeat_csv` i l'estat de transmissió. Admet filtratge per `status`, `type`, `date_from`/`date_to` i `environment`. - [Reintenta la transmissió a VeriFactu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.records.retry): Torna a encuar un registre VeriFactu fallit per a la seva transmissió a l'AEAT. Conflicte (409) si ja va ser acceptat, 422 si s'ha superat el límit de reintents. - [Obtenir un registre VeriFactu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.records.show): Obté un registre VeriFactu pel seu `id` (UUID v7). Retorna 404 `verifactu_record_not_found` si el registre no existeix o pertany a una altra empresa. - [Esmenar (subsanar) un registre VeriFactu rebutjat](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.records.subsanar): Esmena un registre VeriFactu rebutjat per AEAT: regenera el contingut esmenable a partir de la factura d'origen conservant la `huella` original, reinicia la ronda de transmissió i torna a encuar la transmissió a AEAT (202). Retorna 422 `record_not_rejected` si el registre no està rebutjat, o `requires_annulment` quan l'esmena afecta camps de l'empremta (en lloc d'això cal anul·lar + nova alta). - [Actualitzar la configuració de VeriFactu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.settings.update): Actualitza la configuració VeriFactu de la teva empresa (p. ex. mode/entorn). Retorna 422 `business_rule_violation` quan una transició està bloquejada pel compliment AEAT (per exemple, un cop activat el mode VeriFactu no es pot desactivar silenciosament). - [Obtenir estadístiques de VeriFactu](https://docs.factuarea.com/ca/api-reference/verifactu/public-api.v1.verifactu.stats): KPIs agregats dels teus registres VeriFactu: recompte total, recomptes per estat (pending, submitted, accepted, rejected, error), desglossament per tipus de registre i de factura, i data de l'última transmissió. Accepta els filtres opcionals `date_from`, `date_to` i `environment`. Es retorna com a `{ "data": VeriFactuStats }`. - [Crea un webhook endpoint](https://docs.factuarea.com/ca/api-reference/webhooks/public-api.v1.webhook_endpoints.create): Crea un webhook endpoint que rep notificacions d'esdeveniments mitjançant callbacks HTTPS. El `secret` de signatura es retorna **una sola vegada** en aquesta resposta i mai més — desa'l de forma segura. - [Elimina un webhook endpoint](https://docs.factuarea.com/ca/api-reference/webhooks/public-api.v1.webhook_endpoints.delete): Elimina un webhook endpoint. Els lliuraments en curs no es cancel·len, però no s'encuen lliuraments nous. - [Llista les entregues de webhook](https://docs.factuarea.com/ca/api-reference/webhooks/public-api.v1.webhook_endpoints.deliveries.list): Llista els intents de lliurament d'un webhook endpoint amb paginació per cursor. Cada lliurament captura l'estat de la resposta HTTP, el cos (truncat), la durada i la programació de reintents. - [Reenviar lliurament de webhook](https://docs.factuarea.com/ca/api-reference/webhooks/public-api.v1.webhook_endpoints.deliveries.replay): Reencua un lliurament de webhook. Es crea un nou intent de lliurament (amb `attempt: 1`) per al mateix parell esdeveniment/endpoint. - [Recupera el lliurament del webhook](https://docs.factuarea.com/ca/api-reference/webhooks/public-api.v1.webhook_endpoints.deliveries.show): Obté un únic intent de lliurament pel seu `uuid`, incloent-hi el payload complet de l'esdeveniment que es va lliurar. - [Llistar tots els webhook endpoints](https://docs.factuarea.com/ca/api-reference/webhooks/public-api.v1.webhook_endpoints.list): Llista els teus webhook endpoints amb paginació per cursor. - [Fer ping al webhook endpoint](https://docs.factuarea.com/ca/api-reference/webhooks/public-api.v1.webhook_endpoints.ping): Envia un esdeveniment de prova (`webhook.ping`) a l'endpoint per verificar que és accessible i que el handshake de signatura funciona. El lliurament sintètic apareix a `GET /webhook_endpoints/{webhook_endpoint}/deliveries`. - [Rota el secret del webhook](https://docs.factuarea.com/ca/api-reference/webhooks/public-api.v1.webhook_endpoints.rotate_secret): Rota el secret de signatura d'un webhook endpoint. El nou secret es retorna **una sola vegada** en aquesta resposta. El secret anterior continua sent vàlid durant un període de gràcia de 24 hores (vegeu `previous_secret_valid_until`) per permetre una rotació sense temps d'inactivitat. - [Obtenir un webhook endpoint](https://docs.factuarea.com/ca/api-reference/webhooks/public-api.v1.webhook_endpoints.show): Obté un webhook endpoint pel seu `uuid`. El secret de signatura mai s'exposa en aquesta representació. - [Enviar un esdeveniment de prova](https://docs.factuarea.com/ca/api-reference/webhooks/public-api.v1.webhook_endpoints.test_event): Llança un lliurament de prova d'un tipus d'esdeveniment real del catàleg a aquest endpoint, marcat `test: true` a l'embolcall lliurat. A diferència de `ping` (un `webhook.ping` sintètic), això registra un `Event` real (visible a `GET /events`) i encua un `WebhookDelivery` signat i amb reintents. Opcionalment passa `type` per triar quin esdeveniment subscrit simular. El lliurament arriba només a aquest endpoint. - [Actualitzar un webhook endpoint](https://docs.factuarea.com/ca/api-reference/webhooks/public-api.v1.webhook_endpoints.update): Actualitza un webhook endpoint (URL, descripció, esdeveniments habilitats, estat, llista d'accés d'IP). - [Arxivar un horari de treball](https://docs.factuarea.com/ca/api-reference/work-schedules/public-api.v1.work_schedules.archive): Arxiva un horari de treball (transició `active` → `archived`), retirant-lo de l'ús però conservant-lo. Sense cos de la petició. Retorna 422 si ja està arxivat. Reversible mitjançant desarxivar. - [Assignar un horari a un empleat](https://docs.factuarea.com/ca/api-reference/work-schedules/public-api.v1.work_schedules.assign): Assigna l'horari de treball a un empleat amb una data d'inici de vigència. `employee_id` (UUID v7, ha de pertànyer a la teva empresa) i `effective_from` (`Y-m-d`) són obligatoris. Assignar tanca l'assignació oberta anterior de l'empleat i obre la nova (un empleat té com a màxim una assignació oberta; es conserva l'històric). Un empleat desconegut retorna 422 `assigned_employee_not_found`; un horari desconegut retorna 404. Retorna l'assignació creada. - [Llistar les assignacions d'un horari](https://docs.factuarea.com/ca/api-reference/work-schedules/public-api.v1.work_schedules.assignments): Llista els empleats amb una assignació oberta (`effective_to` = null) a aquest horari de treball, com una llista plana sota `{ "data": [ … ] }`. - [Crear un horari de treball](https://docs.factuarea.com/ca/api-reference/work-schedules/public-api.v1.work_schedules.create): Crea un horari de treball setmanal per a l'empresa autenticada (resolta des de l'API key, mai des del payload). `name` i `week_pattern` són obligatoris; `mode` pren per defecte `validated`. El `week_pattern` és una llista de dies de la setmana (ISO 8601 1..7) cadascun amb les seves franges horàries `HH:MM` ordenades i sense solapar-se (un `ranges` buit significa dia de descans). Retorna l'horari creat amb el seu `id` generat (UUID v7); `weekly_hours` es deriva del patró. - [Obtenir l'horari actual d'un empleat](https://docs.factuarea.com/ca/api-reference/work-schedules/public-api.v1.work_schedules.employee_schedule): Resol l'horari de treball actualment en vigor (avui) per a un empleat pel seu `id` (UUID v7). Retorna 404 `schedule_assignment_not_found` quan l'empleat no té horari en vigor (o pertany a una altra empresa). El resultat és l'horari resolt (`id` = UUID v7 de l'horari), no l'assignació. - [Llistar tots els horaris de treball](https://docs.factuarea.com/ca/api-reference/work-schedules/public-api.v1.work_schedules.list): Llista els horaris de treball setmanals de la teva empresa amb paginació per cursor. Admet filtrar per `status` (`active`/`archived`) i `mode` (`validated`/`real_clocking`), més una `search` de text lliure sobre el nom de l'horari. - [Obtenir un horari de treball](https://docs.factuarea.com/ca/api-reference/work-schedules/public-api.v1.work_schedules.show): Obtén un únic horari de treball pel seu `id` (UUID v7). Un horari pertanyent a una altra empresa retorna 404 `work_schedule_not_found` (anti-enumeració). - [Obtenir les estadístiques d'horaris de treball](https://docs.factuarea.com/ca/api-reference/work-schedules/public-api.v1.work_schedules.stats): KPIs agregats dels teus horaris de treball: total, nombre d'actius i arxivats, un desglossament per mode (`validated`/`real_clocking`) i el nombre d'empleats amb un horari assignat. Es retorna com a `{ "data": … }`. - [Desarxivar un horari de treball](https://docs.factuarea.com/ca/api-reference/work-schedules/public-api.v1.work_schedules.unarchive): Desarxiva un horari de treball (transició `archived` → `active`), tornant-lo a l'ús. Sense cos de la petició. Retorna 422 si ja està actiu. - [Desassignar un horari d'un empleat](https://docs.factuarea.com/ca/api-reference/work-schedules/public-api.v1.work_schedules.unassign): Tanca l'assignació oberta de l'empleat a aquest horari. `employee_id` (UUID v7) és obligatori; `effective_to` (`Y-m-d`) és opcional i pren per defecte la data d'avui. Retorna 404 quan no hi ha assignació oberta. Respon 204 No Content. - [Actualitzar un horari de treball](https://docs.factuarea.com/ca/api-reference/work-schedules/public-api.v1.work_schedules.update): Reemplaça per complet un horari de treball: `name`, `mode` i el `week_pattern` complet són obligatoris (no hi ha actualització parcial del patró). `weekly_hours` es recomputa a partir del nou patró. Retorna l'horari actualitzat. - [Tots els error codes](https://docs.factuarea.com/ca/guides/errors/all): Referència completa de cada error code de l'API pública, agrupat per bounded context, amb el seu estat HTTP i type. - [Gestió d'errors](https://docs.factuarea.com/ca/guides/errors): Embolcall d'error normalitzat, catàleg de type i code amb àncores estables, i estratègia de reintents. - [Consulta el catàleg fiscal](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.tax-catalog.show): Retorna, en un sol document, el coneixement fiscal espanyol que necessites per construir un formulari de facturació conforme: règims d'imposició indirecta (IVA, IGIC, IPSI) amb els seus tipus legals i el seu codi L1 de VeriFactu, règims d'operació a escala de capçalera amb la menció legal que exigeix cadascun, causes d'exempció amb el seu codi AEAT, la seva menció legal i el seu article de la Llei de l'IVA, els tipus de retenció d'IRPF del sistema i la matriu tancada de parells legals d'IVA/recàrrec d'equivalència. Substitueix la taula hardcodeada que tota integració acaba mantenint a mà. El catàleg no porta cap dada de l'empresa autenticada: dues empreses diferents reben cossos idèntics byte a byte per al mateix idioma, i `retention_rates` mai no inclou els impostos personalitzats que una empresa crea amb `POST /v1/taxes`. Els tipus de retenció es publiquen en POSITIU, així que aplica'ls com una deducció sobre la base imposable. Aquest és el catàleg del que la plataforma admet, NO una llista normativa exhaustiva de tots els règims, exempcions o tipus de retenció que defineix la llei espanyola. Fes-lo servir per saber què pots enviar a aquesta API; no el llegeixis com a assessorament fiscal ni com a substitut de la legislació. Cada entrada porta la seva `label` (i, als dos blocs normatius, la seva `description`) en espanyol, anglès i català alhora. `Accept-Language` només tria l'idioma que s'informa a `primary_language`; mai no filtra el payload, així que amb un document desat a la memòria cau n'hi ha prou per pintar un selector multiidioma. La resposta es pot desar a la memòria cau: porta `ETag` i un `Cache-Control` públic, i retornar el validador a `If-None-Match` respon un 304 sense cos. Dos idiomes produeixen dos `ETag` diferents, perquè l'idioma negociat viatja dins del cos. - [Llistar impostos actius](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.active): Retorna els impostos actius disponibles per a la teva empresa, combinant els predeterminats del sistema més les definicions específiques de l'empresa. - [Llista els impostos filtrats per tipus](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.by_type): Retorna els impostos filtrats per categoria mitjançant el query param type (vat, retention, surcharge, other). Per defecte vat quan s'omet. - [Calcular un impost sobre un import base](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.calculate): Aplica l'impost referenciat a un import base i retorna el desglossament: base, tax_rate, tax_amount, total_amount i l'objecte d'impost complet. - [Calcular totals per a un conjunt de línies](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.calculate_totals): Calcula la base imposable, l'IVA, el recàrrec, la retenció i el total general per a un array de línies amb quantitat, preu, descompte i tipus impositius. Retorna els totals del document més el desglossament per línia. - [Crea un impost](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.create): Registra un nou impost amb nom, codi únic, tipus (vat, retention, surcharge o other), taxa i àmbit (sale, purchase o both). El codi de país ISO-2 és obligatori. - [Obtenir els impostos per defecte per a un tipus de document](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.defaults): Retorna els impostos predeterminats configurats (vat, retention, surcharge) per al tipus de document indicat, en l'àmbit de la teva empresa. Cada espai és un Tax o null quan no hi ha predeterminat configurat. - [Elimina un impost](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.delete): Elimina un impost. Falla amb 409 si l'impost està referenciat per documents existents. Els impostos de sistema (is_system=true) no es poden eliminar. - [Llista els impostos aplicables a les compres](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.for_purchases): Retorna els impostos disponibles per a documents de compra (factures de proveïdor). - [Llista els impostos aplicables a les vendes](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.for_sales): Retorna els impostos disponibles per a documents de venda (factures, pressupostos, proformes, albarans). - [Comprovar si un impost està en ús](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.is_in_use): Retorna si l'impost està referenciat per documents existents. Útil per a comprovacions d'eliminació segura abans de cridar DELETE. - [Llistar tots els impostos](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.list): Llista els tipus impositius disponibles per a la teva empresa (IVA, IRPF, recàrrec espanyols, etc.). - [Marca un impost com a predeterminat per al seu tipus](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.set_default): Promou un impost al predeterminat a nivell de sistema per a la seva categoria (vat, retention o surcharge). Si un altre impost era el predeterminat per al mateix tipus, es degrada automàticament. - [Estableix l'impost predeterminat per a un tipus de document](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.set_default_for_document): Assigna un impost com a predeterminat per a un tipus de document específic (invoice, quote, proforma, delivery_note, purchase_invoice, recurring_invoice). - [Obtenir un impost](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.show): Obté un tipus impositiu pel seu `uuid`. - [Obtenir estadístiques d'impostos](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.stats): KPIs agregats dels tipus impositius disponibles per a la teva empresa: nombre total d'impostos, nombre d'actius i desglossament per tipus (vat, retention, surcharge, other). Retornat com a `{ "data": TaxStats }`. - [Alternar l'estat actiu de l'impost](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.toggle): Canvia un impost entre actiu i inactiu. Els impostos inactius s'amaguen dels selectors però segueixen disponibles per a documents ja emesos. - [Actualitzar un impost](https://docs.factuarea.com/ca/api-reference/taxes/public-api.v1.taxes.update): Actualització parcial d'un impost: name, code, rate, applies_to, country i description. Els impostos del sistema (is_system=true) no són editables.