Factuarea API
Facturas recurrentes

Anular factura recurrente

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.

POST
/recurring_invoices/{recurring_invoice}/cancel

Authorization

AuthorizationBearer <token>

En: header

Parámetros de ruta

recurring_invoice*string

Parámetros de cabecera

Idempotency-Key?string

Clave única generada por el cliente para garantizar la idempotencia en los reintentos. Te permite reenviar de forma segura la misma petición: la primera respuesta se cachea y se devuelve sin volver a ejecutar la mutación. Es una cadena opaca para el servidor; cualquier valor único de hasta 64 caracteres es válido (UUID v7, UUID v4, ULID, nanoid, etc.). Se recomienda UUID v7 por coherencia con los identificadores de la API. La misma clave reutilizada con un body distinto devuelve 409 idempotency_key_reused.

Longitud1 <= length <= 64

Cuerpo de la respuesta

application/json

application/json

application/json

application/json

application/json

application/json

{
  "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",
    "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,
    "days_before_due": 30,
    "max_occurrences": 12,
    "occurrences_count": 3,
    "remaining_occurrences": 9,
    "holiday_handling": "next_business_day",
    "start_on": "2026-01-01",
    "end_on": "2026-12-31",
    "next_run_at": "2026-02-01T09:00:00Z",
    "last_run_at": "2026-01-01T09:00:00Z",
    "cancelled_at": null,
    "subtotal": 200,
    "taxes_total": 42,
    "total": 242,
    "currency": "EUR",
    "lines": [
      {
        "object": "recurring_invoice_line",
        "description": "Cuota soporte mensual",
        "quantity": 1,
        "unit_price": 200,
        "tax_rate": 21,
        "retention": 0,
        "surcharge": 0,
        "subtotal": 200,
        "taxes": 42,
        "total": 242
      }
    ],
    "metadata": {
      "erp_code": "IVA-GEN",
      "ledger_account": "477000"
    },
    "external_id": "ERP-REC-2026-0008",
    "tags": [
      "suscripcion",
      "mantenimiento"
    ],
    "custom_fields": [
      {
        "field": "contrato",
        "value": "CTR-2026-0007"
      }
    ],
    "created_at": "2025-12-20T15:00:00Z",
    "updated_at": "2026-01-01T09:05:00Z"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se ha proporcionado una API key válida en el header Authorization.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido para esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "La cabecera `Idempotency-Key` ya se usó con un body distinto. Usa una clave nueva o reenvía exactamente el mismo body.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_01HKQS5NHT9A4U7R2E3F8GZWTJ"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
  }
}

Eliminación masiva de facturas recurrentes

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.

Crea una factura recurrente

Crea una plantilla de factura recurrente que genera facturas automáticamente con una cadencia fija (semanal, mensual, trimestral, anual).