Crear una factura recurrent a partir d'una factura

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.

Authorization

AuthorizationBearer <token>

La teva API key com a token Bearer: fact_live_… en producció, fact_test_… en sandbox. Consulta la guia d'autenticació.

A: header

Paràmetres de ruta

company*string

Identificador públic (UUID v7) de l'empresa. Obtén-lo de GET /v1/me (data.scope[].id).

Formatuuid

invoice*string

Identificador públic (UUID v7) de la factura.

Formatuuid

Headers

Idempotency-Key?string

Clau opaca generada pel client (fins a 255 caràcters; es recomana UUID v7) que fa segurs els reintents: la primera resposta es cacheja i es reprodueix a les repeticions sense tornar a executar la mutació. Reutilitzar una clau amb un cos diferent retorna 422 idempotency_key_reused; els valors dels camps secrets (password, secret…) compten com a part del cos, així que reintentar amb un secret corregit sota la mateixa clau és una petició diferent, mai la repetició de la resposta anterior. Consulta la guia d'idempotència.

Longitud1 <= length <= 255

Factuarea-Version?string

Fixa la versió de l'API (YYYY-MM-DD, versionat per data estil Stripe) per a aquesta petició; omet-lo per usar la versió fixada de la clau, o l'última si no n'hi ha cap. Versió no suportada → 400 unsupported_api_version; mal formada → 400 parameter_invalid_format. La versió efectiva es reflecteix a la capçalera de resposta Factuarea-Version. Consulta la guia de Versioning.

Formatdate

Cos de la petició

application/json

La política de presentació i els termes de pagament relatius conserven la distinció entre omès, null i buit. Una creació nova comença a la versió de configuració 1. Crear a partir d'una factura no en copia el calendari de pagaments vençut ni la intenció visual privada. Un upsert sobre un external_id existent utilitza el CAS d'actualització. Desar la configuració mai reprèn una recurrència pausada. presentation_policy, payment_terms_template i expected_presentation_policy_version només tenen efecte quan la presentació amb revisions està activada per a l'empresa; en cas contrari s'ignoren.

Definicions de TypeScript

Usa el tipus request body a TypeScript.

presentation_policy?|||

En crear, si s'omet o és null s'hereta l'última; en actualitzar, si s'omet es conserva, null restableix l'herència i un objecte complet substitueix la política. {} i els objectes parcials no són vàlids. Aquest camp només té efecte quan la presentació amb revisions està activada per a l'empresa; en cas contrari s'ignora.

payment_terms_template?array<>|

Calendari de pagament relatiu de la recurrència; l'esquema explica la semàntica de null, [] i de la llista. Aquest camp només té efecte quan la presentació amb revisions està activada per a l'empresa; en cas contrari s'ignora.

expected_source_context_hash?string

recovery?string

frequency*string

start_on*string

Formatdate

end_on?|

Formatdate

name?|

Longitudlength <= 255

description?string|null

notes?string|null

metadata?|

Un mapa lliure de fins a 50 parells clau→valor per emmagatzemar dades estructurades arbitràries (els valors són cadenes de fins a 500 caràcters). A diferència de custom_fields —una llista ordenada de parells tipats {field, value} amb semàntica de visualització, present als sis recursos de document—, metadata és un mapa sense ordre per a dades d'integració opaques; un document pot portar tots dos. Els recursos mestres (Client, Supplier) no tenen custom_fields, així que la seva metadata fa també de magatzem de custom-fields.

Claus reservades (només lectura). Quan el sistema autoemet una factura a partir d'una correlació de pagament (Stripe/GoCardless/MONEI), escriu stripe_subscription_id, stripe_invoice_id, billing_reason, period_start i period_end a la metadata d'aquesta factura automàticament. No les estableixis ni les sobreescriguis a mà —la plataforma n'és la propietària i un valor manual es pot reemplaçar quan s'executa la correlació.

Propietatsproperties <= 50

holiday_handling?string|null

days_before_due?|

Rang0 <= value

max_occurrences?|

Rang1 <= value

generation_mode?|

Què fa cada execució de la recurrència amb la factura que genera: draft la deixa en esborrany; issue l'emet (número definitiu, registre VeriFactu, moviments d'stock) sense enviar-la per email; issue_and_send l'emet i l'envia per email als destinataris d'auto_delivery. Qualsevol altre valor es rebutja amb 422. Opcional i admet null: si s'omet (o és null), el mode es deriva de send_automatically (true → issue_and_send, false o absent → draft). Si s'envia, preval i send_automatically passa a ser un camp derivat (true només amb issue_and_send); enviar un send_automatically (a l'arrel o dins d'auto_delivery) que el contradigui es rebutja amb 422. Els destinataris només són obligatoris amb issue_and_send: si es configura un objecte auto_delivery, auto_delivery.recipients ha de contenir llavors almenys una adreça (si no, 422 auto_delivery_recipients_required); draft i issue no envien cap email i no en necessiten. Disponible a totes les versions de l'API.

Valor a"draft" | "issue" | "issue_and_send" | null

auto_delivery?

Cos de la resposta

`application/json`

Exemple de petició

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/companies/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/create-recurring", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-invoices-create_recurring"} },  body: JSON.stringify({  "frequency": "daily",  "start_on": "2026-03-15"}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Exemple de resposta

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08",
    "object": "recurring_invoice",
    "client": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "name": "Acme Corporation"
    },
    "series": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e",
      "code": "F-2026"
    },
    "status": "active",
    "price_list_id": null,
    "price_list_name": null,
    "frequency": "monthly",
    "name": "Cuota mantenimiento mensual Acme",
    "description": "Contrato de soporte y mantenimiento Plan Pro",
    "notes": "Renovación automática. Facturar el día 1 de cada mes.",
    "email_to": "facturacion@acme.example",
    "send_automatically": true,
    "generation_mode": "issue_and_send",
    "days_before_due": 30,
    "max_occurrences": 12,
    "occurrences_count": 0,
    "remaining_occurrences": 12,
    "holiday_handling": "next_business_day",
    "start_on": "2026-01-01",
    "end_on": "2026-12-31",
    "next_run_at": "2026-01-01T09:00:00Z",
    "last_run_at": null,
    "cancelled_at": null,
    "subtotal": "200.00",
    "taxes_total": "42.00",
    "total_vat": "42.00",
    "total_retention": "0.00",
    "total_surcharge": "0.00",
    "total": "242.00",
    "currency": "EUR",
    "lines": [
      {
        "object": "recurring_invoice_line",
        "description": "Cuota soporte mensual",
        "additional_description": null,
        "quantity": 1,
        "unit_price": "200.0000",
        "tax_rate": 21,
        "retention": 0,
        "surcharge": 0,
        "discount_percent": 0,
        "subtotal": "200.00",
        "taxes": "42.00",
        "total": "242.00",
        "exemption_reason": null,
        "regime_key": null,
        "retention_rate_id": null,
        "surcharge_rate_id": null,
        "indirect_tax_regime": null,
        "product_id": null,
        "product_name": null,
        "item_kind": "service",
        "variant_id": null,
        "variant_name": null,
        "presentation_id": null,
        "presentation_name": null,
        "presentation_mode": null,
        "commercial_unit_code": "C62",
        "base_unit_code": "C62",
        "conversion_factor": "1.000000",
        "base_quantity": "1.0000",
        "counted_quantity": null,
        "counted_unit": null,
        "price_list_id": null,
        "price_list_name": null,
        "price_source": "manual",
        "price_unit_code": "C62",
        "configuration": null,
        "options": [],
        "price_semantics": "per_commercial_unit",
        "price_adjustment_total": "0.0000",
        "option_adjustments_absorbed": false,
        "pack_group": null
      }
    ],
    "metadata": {
      "contract": "CTR-2026-0007"
    },
    "external_id": "ERP-REC-2026-0008",
    "tags": [
      "suscripcion",
      "mantenimiento"
    ],
    "custom_fields": [
      {
        "field": "contrato",
        "value": "CTR-2026-0007"
      }
    ],
    "auto_delivery": {
      "send_automatically": true,
      "recipients": [
        "facturacion@acme.example"
      ],
      "cc": [
        "administracion@acme.example"
      ],
      "subject": "Tu factura mensual de Acme",
      "body": "Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."
    },
    "created_at": "2025-12-20T15:00:00Z",
    "updated_at": "2025-12-20T15:00:00Z",
    "presentation_policy": {
      "mode": "latest",
      "template_id": null,
      "revision_id": null,
      "commercial_identity_id": null,
      "commercial_identity_revision_id": null
    },
    "payment_terms_template": null,
    "presentation_policy_version": 1,
    "presentation_pause_reason": null
  }
}

S'ha enviat la capçalera X-Active-Profile retirada

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "subcode": "retired_active_profile_header",
    "message": "La cabecera 'X-Active-Profile' fue retirada de la API v1: la empresa efectiva se indica en el segmento de empresa de la ruta.",
    "param": "X-Active-Profile",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_unknown",
    "request_id": "req_01J8Y3M2Q40000000000000001"
  }
}

Capçalera Factuarea-Version malformada

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid_format",
    "message": "El header 'Factuarea-Version' debe tener formato YYYY-MM-DD.",
    "param": "Factuarea-Version",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid_format",
    "request_id": "req_01J8Y3M2Q40000000000000002"
  }
}

Factuarea-Version no admesa

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_api_version",
    "message": "La versión de API '2020-01-01' no está soportada.",
    "param": "Factuarea-Version",
    "doc_url": "https://docs.factuarea.com/guides/errors#unsupported_api_version",
    "request_id": "req_01J8Y3M2Q40000000000000003"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Falta header Authorization o X-API-Key.",
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_b673bd6011ec3e3ad8660973a4"
  }
}

POST /v1/companies/{company}/invoices/{invoice}/create-recurring · 403 insufficient_scope

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'recurring_invoices:write'. Tu API key solo tiene los scopes: ninguno.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_7c7a3f5b0fa28171739e75f308"
  }
}

Empresa desactivada

{
  "error": {
    "type": "authorization_error",
    "code": "company_inactive",
    "message": "Esta empresa está desactivada. Actívala para operar.",
    "param": "company",
    "doc_url": "https://docs.factuarea.com/guides/errors#company_inactive",
    "request_id": "req_01J8Y3M2Q40000000000000005"
  }
}

POST /v1/companies/{company}/invoices/{invoice}/create-recurring · 404 invoice_not_found

{
  "error": {
    "type": "not_found_error",
    "code": "invoice_not_found",
    "message": "Factura no encontrada.",
    "param": "invoice_uuid",
    "subcode": "invoice_not_found",
    "doc_url": "https://docs.factuarea.com/guides/errors#invoice_not_found",
    "request_id": "req_2de46fbdfb9b81e97eb8962d38"
  }
}

Empresa no trobada o fora de l'abast de l'API key

{
  "error": {
    "type": "not_found_error",
    "code": "profile_not_found",
    "message": "La empresa indicada no existe o no está en el ámbito de tu credencial.",
    "param": "company",
    "doc_url": "https://docs.factuarea.com/guides/errors#profile_not_found",
    "request_id": "req_01J8Y3M2Q40000000000000004"
  }
}

La presentació del document ha canviat

{
  "error": {
    "type": "conflict_error",
    "code": "pdf_presentation_conflict",
    "message": "La presentación documental ha cambiado. Actualiza los datos antes de volver a guardar.",
    "param": "expected_version",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_presentation_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000PPC1"
  }
}

El context de presentació revisat ha canviat

{
  "error": {
    "type": "conflict_error",
    "code": "pdf_presentation_context_changed",
    "message": "El contexto de presentación ha cambiado. Actualiza la vista previa antes de continuar.",
    "param": "expected_preview_context_fingerprint",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_presentation_context_changed",
    "request_id": "req_01J8Y3M2Q4CF0000000000PCC1"
  }
}

Reserva concurrent d'identificadors (reintentable)

{
  "error": {
    "type": "conflict_error",
    "code": "resource_conflict",
    "message": "Hay otra operación reservando identificadores sobre 'recurring_invoices' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.",
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000IDR1"
  }
}

POST /v1/companies/{company}/invoices/{invoice}/create-recurring · 422 invalid_param_value

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "El campo frequency es obligatorio.",
    "param": "frequency",
    "errors": [
      {
        "param": "frequency",
        "code": "parameter_missing",
        "message": "El campo frequency es obligatorio."
      }
    ],
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_f31b979ac544540ca7216433e2"
  }
}

Idempotency key reutilitzada amb un payload diferent

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_01J8Y3M2Q40000000000000007"
  }
}

Format d'Idempotency-Key no vàlid

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_format",
    "message": "La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_format",
    "request_id": "req_01J8Y3M2Q40000000000000008"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el límite de requests permitido. Reintenta más tarde.",
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_9cfc07bf537c5943eaea7c74e2"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.",
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_67fe4fdfcee758f64acf1ca73f"
  }
}

Crear una factura recurrent a partir d'una factura

Authorization

Paràmetres de ruta

Headers

Cos de la petició

Cos de la resposta

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`