Crear una factura recurrente a partir de una factura

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.

Authorization

AuthorizationBearer <token>

Tu API key como token Bearer: fact_live_… en producción, fact_test_… en sandbox. Consulta la guía de autenticación.

En: header

Parámetros de ruta

company*string

Identificador público (UUID v7) de la empresa. Obtenlo de GET /v1/me (data.scope[].id).

Formatouuid

invoice*string

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

Formatouuid

Headers

Idempotency-Key?string

Clave opaca generada por el cliente (hasta 255 caracteres; se recomienda UUID v7) que hace seguros los reintentos: la primera respuesta se cachea y se reproduce en las repeticiones sin volver a ejecutar la mutación. Reutilizar una clave con un cuerpo distinto devuelve 422 idempotency_key_reused; los valores de los campos secretos (password, secret…) cuentan como parte del cuerpo, así que reintentar con un secreto corregido bajo la misma clave es una petición distinta, nunca la repetición de la respuesta anterior. Consulta la guía de idempotencia.

Longitud1 <= length <= 255

Factuarea-Version?string

Fija la versión de la API (YYYY-MM-DD, versionado por fecha estilo Stripe) para esta petición; omítelo para usar la versión fijada de la clave, o la última si no hay ninguna. Versión no soportada → 400 unsupported_api_version; malformada → 400 parameter_invalid_format. La versión efectiva se refleja en la cabecera de respuesta Factuarea-Version. Consulta la guía de Versioning.

Formatodate

Cuerpo de la petición

application/json

La política de presentación y las condiciones de pago relativas conservan la distinción entre omitido, null y vacío. Una creación nueva empieza en la versión de configuración 1. Crear a partir de una factura no copia su calendario de pagos vencido ni su intención visual privada. Un upsert sobre un external_id existente usa el CAS de actualización. Guardar la configuración nunca reanuda una recurrencia pausada. presentation_policy, payment_terms_template y expected_presentation_policy_version solo surten efecto cuando la presentación con revisiones está activada para la empresa; en caso contrario se ignoran.

Definiciones de TypeScript

Usa el tipo request body en TypeScript.

presentation_policy?|||

En la creación, omitir o null significa la última heredada. En la actualización, omitir conserva; null restablece la herencia; un objeto completo sustituye a la política. {} y los objetos parciales no son válidos. Este campo solo surte efecto cuando la presentación con revisiones está activada para la empresa; en caso contrario se ignora.

payment_terms_template?array<>|

Calendario de pagos relativo de la recurrencia; el esquema explica la semántica de null, [] y de la lista. Este campo solo surte efecto cuando la presentación con revisiones está activada para la empresa; en caso contrario se ignora.

expected_source_context_hash?string

recovery?string

frequency*string

start_on*string

Formatodate

end_on?|

Formatodate

name?|

Longitudlength <= 255

description?string|null

notes?string|null

metadata?|

Un mapa libre de hasta 50 pares clave→valor para almacenar datos estructurados arbitrarios (los valores son cadenas de hasta 500 caracteres). A diferencia de custom_fields —una lista ordenada de pares tipados {field, value} con semántica de visualización, presente en los seis recursos de documento—, metadata es un mapa sin orden para datos de integración opacos; un documento puede llevar ambos. Los recursos maestros (Client, Supplier) no tienen custom_fields, así que su metadata hace también de almacén de custom-fields.

Claves reservadas (solo lectura). Cuando el sistema autoemite una factura a partir de una correlación de pago (Stripe/GoCardless/MONEI), escribe stripe_subscription_id, stripe_invoice_id, billing_reason, period_start y period_end en la metadata de esa factura automáticamente. No las establezcas ni las sobrescribas a mano —la plataforma es su dueña y un valor manual puede reemplazarse cuando se ejecuta la correlación.

Propiedadesproperties <= 50

holiday_handling?string|null

days_before_due?|

Rango0 <= value

max_occurrences?|

Rango1 <= value

generation_mode?|

Qué hace cada ejecución de la recurrencia con la factura que genera: draft la deja en borrador; issue la emite (número definitivo, registro VeriFactu, movimientos de stock) sin enviarla por email; issue_and_send la emite y la envía por email a los destinatarios de auto_delivery. Cualquier otro valor se rechaza con 422. Opcional y admite null: si se omite (o es null), el modo se deriva de send_automatically (true → issue_and_send, false o ausente → draft). Si se envía, prevalece y send_automatically pasa a ser un campo derivado (true solo con issue_and_send); enviar un send_automatically (en la raíz o dentro de auto_delivery) que lo contradiga se rechaza con 422. Los destinatarios solo son obligatorios con issue_and_send: si se configura un objeto auto_delivery, auto_delivery.recipients debe contener entonces al menos una dirección (si no, 422 auto_delivery_recipients_required); draft e issue no envían ningún email y no los necesitan. Disponible en todas las versiones de la API.

Valor en"draft" | "issue" | "issue_and_send" | null

auto_delivery?

Cuerpo de la respuesta

`application/json`

Ejemplo de petición

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());

Ejemplo de respuesta

{
  "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
  }
}

Se envió la cabecera 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"
  }
}

Cabecera 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 admitida

{
  "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 encontrada o fuera del alcance de la 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ón del documento ha cambiado

{
  "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 contexto de presentación revisado ha cambiado

{
  "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 concurrente de identificadores (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 reutilizada con un payload distinto

{
  "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"
  }
}

Formato de Idempotency-Key no válido

{
  "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 recurrente a partir de una factura

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

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`