Factuarea API
Factures recurrents

Activar factura recurrent

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.

POST
/recurring_invoices/{recurring_invoice}/activate

Authorization

AuthorizationBearer <token>

A: header

Paràmetres de ruta

recurring_invoice*string

Paràmetres de capçalera

Idempotency-Key?string

Clau única generada pel client per garantir la idempotència en els reintents. Et permet reenviar de manera segura la mateixa petició: la primera resposta es cacheja i es retorna sense tornar a executar la mutació. És una cadena opaca per al servidor; qualsevol valor únic de fins a 64 caràcters és vàlid (UUID v7, UUID v4, ULID, nanoid, etc.). Es recomana UUID v7 per coherència amb els identificadors de l'API. La mateixa clau reutilitzada amb un body diferent retorna 409 idempotency_key_reused.

Longitud1 <= length <= 64

Cos de la resposta

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

Actualitzar una factura de compra

Actualitza una factura de compra.

Llista l'activitat de factures recurrents

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.