El recurso recurring/invoices te permite crear automatizaciones que generan facturas de forma periódica. Es útil para servicios de suscripción, cuotas mensuales, mantenimientos anuales y cualquier facturación recurrente.

Una factura recurrente es una automatización que contiene una plantilla de factura y un trigger (disparador) que define cuándo se ejecuta.

💡 Recomendación: Antes de empezar a desarrollar, te recomendamos crear un entorno de pruebas (sandbox) para hacer tus primeras llamadas sin afectar tus datos reales.

Endpoints disponibles

Método	Endpoint	Descripción
GET	/{companyId}/recurring/invoices	Lista de facturas recurrentes
POST	/{companyId}/recurring/invoices	Crear factura recurrente
GET	/{companyId}/recurring/invoices/{id}	Obtener una factura recurrente por ID
PUT	/{companyId}/recurring/invoices/{id}	Actualizar factura recurrente
DELETE	/{companyId}/recurring/invoices/{id}	Eliminar factura recurrente
PUT	/{companyId}/recurring/invoices/{id}/pdf	Generar PDF de muestra
PUT	/{companyId}/recurring/invoices/{id}/tags	Actualizar etiquetas

Ejemplos de código

Factura recurrente anual

Una automatización que genera una factura cada año el día 10 de enero.

curl -X POST \
  -H "facturadirecta-api-key: TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "type": "automation",
      "main": {
        "title": "Cuota anual mantenimiento",
        "enabled": true,
        "trigger": {
          "type": "recurring",
          "rrule": {
            "interval": 1,
            "freq": "yearly",
            "bymonthday": 10,
            "bymonth": 1,
            "dtstart": "2026-01-01T06:00:00.000Z",
            "until": "2030-01-02T06:00:00.000Z"
          }
        },
        "action": {
          "type": "createDocument",
          "template": {
            "type": "invoice",
            "main": {
              "docNumber": {
                "series": "FP"
              },
              "contact": "con_10000000-0000-4000-8000-000000000000",
              "currency": "EUR",
              "lines": [
                {
                  "quantity": 1,
                  "unitPrice": 1200,
                  "tax": ["S_IVA_21"],
                  "text": "Cuota anual de mantenimiento 2026"
                }
              ]
            }
          }
        }
      }
    }
  }' \
  https://app.facturadirecta.com/api/TU_COMPANY_ID/recurring/invoices

Factura recurrente mensual

Una automatización que genera una factura el primer día de cada mes.

{
  "content": {
    "type": "automation",
    "main": {
      "title": "Suscripción mensual",
      "enabled": true,
      "trigger": {
        "type": "recurring",
        "rrule": {
          "interval": 1,
          "freq": "monthly",
          "bymonthday": 1,
          "dtstart": "2026-02-01T06:00:00.000Z"
        }
      },
      "action": {
        "type": "createDocument",
        "template": {
          "type": "invoice",
          "main": {
            "docNumber": {
              "series": "F"
            },
            "contact": "con_10000000-0000-4000-8000-000000000000",
            "currency": "EUR",
            "lines": [
              {
                "quantity": 1,
                "unitPrice": 99,
                "tax": ["S_IVA_21"],
                "text": "Suscripción mensual - Plan Pro"
              }
            ]
          }
        }
      }
    }
  }
}

Factura recurrente trimestral

Una automatización que genera facturas cada 3 meses.

{
  "content": {
    "type": "automation",
    "main": {
      "title": "Mantenimiento trimestral",
      "enabled": true,
      "trigger": {
        "type": "recurring",
        "rrule": {
          "interval": 3,
          "freq": "monthly",
          "bymonthday": 15,
          "dtstart": "2026-01-15T06:00:00.000Z"
        }
      },
      "action": {
        "type": "createDocument",
        "template": {
          "type": "invoice",
          "main": {
            "docNumber": {
              "series": "F"
            },
            "contact": "con_10000000-0000-4000-8000-000000000000",
            "currency": "EUR",
            "lines": [
              {
                "quantity": 1,
                "unitPrice": 300,
                "tax": ["S_IVA_21"],
                "text": "Servicio de mantenimiento trimestral"
              }
            ]
          }
        }
      }
    }
  }
}

Estructura de una factura recurrente

Una factura recurrente tiene tres partes principales:

Configuración general: título, estado activo/inactivo
Trigger (disparador): cuándo se ejecuta la automatización
Action (acción): qué factura se crea

Campos importantes

Campos generales

Campo	Tipo	Descripción
title	string	Nombre descriptivo de la automatización
enabled	boolean	Si está activa (true) o pausada (false)

Campos del trigger (rrule)

El trigger usa el formato iCalendar RRULE para definir la recurrencia:

Campo	Tipo	Descripción
freq	string	Frecuencia: yearly, monthly, weekly, daily
interval	number	Intervalo entre ejecuciones (1 = cada periodo, 2 = cada 2 periodos...)
bymonthday	number	Día del mes (1-31)
bymonth	number	Mes del año (1-12, solo para freq: yearly)
dtstart	string	Fecha de inicio (formato ISO 8601)
until	string	Fecha de fin (formato ISO 8601, opcional)

Campos de la acción

Campo	Tipo	Descripción
action.type	string	Tipo de acción (siempre "createDocument")
action.template	object	Plantilla de la factura a crear (misma estructura que invoices)

Ejemplos de frecuencias

Frecuencia	Configuración
Mensual (día 1)	`freq: "monthly", interval: 1, bymonthday: 1`
Bimensual (día 15)	`freq: "monthly", interval: 2, bymonthday: 15`
Trimestral (día 1)	`freq: "monthly", interval: 3, bymonthday: 1`
Semestral (día 10)	`freq: "monthly", interval: 6, bymonthday: 10`
Anual (10 enero)	`freq: "yearly", interval: 1, bymonthday: 10, bymonth: 1`
Semanal (lunes)	`freq: "weekly", interval: 1, byday: "MO"`

Pausar y reanudar

Para pausar una factura recurrente, actualízala con enabled: false:

curl -X PUT \
  -H "facturadirecta-api-key: TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "type": "automation",
      "main": {
        "enabled": false
      }
    }
  }' \
  https://app.facturadirecta.com/api/TU_COMPANY_ID/recurring/invoices/rec_xxxxx

Para reanudarla, usa enabled: true.

Errores comunes

Error: "Invalid rrule configuration"

La configuración del trigger no es válida. Verifica que:

freq sea uno de: yearly, monthly, weekly, daily
bymonthday esté entre 1 y 31
bymonth esté entre 1 y 12 (si aplica)
dtstart sea una fecha válida en formato ISO 8601

Error: "Invalid template"

La plantilla de factura no es válida. Verifica que tenga los campos obligatorios: contact, currency, lines, docNumber.

Error: "contact not found"

El cliente indicado en la plantilla no existe. Verifica el ID del contacto.

API: Facturas recurrentes (recurring)