Pausar y reanudar facturas recurrentes en bloque

Pausar un grupo de facturas recurrentes significaba una llamada por plantilla: POST /v1/recurring_invoices/{recurring_invoice}/pause por cada id, con tus propios reintentos y tu propio recuento de errores encima. El borrado en bloque ya tenía POST /v1/recurring_invoices/bulk-delete; el cambio de estado, no.

POST /v1/recurring_invoices/bulk-status cierra ese hueco con el mismo contrato de éxito parcial que usan las demás operaciones de estado en bloque.

La operación


Ruta	`POST /v1/recurring_invoices/bulk-status`
Scope	`recurring_invoices:transition`
Cuerpo	`ids` (de 1 a 50 `uuid` sin repetir) y `new_status` (`active` o `paused`)
Respuesta	`200` con un `BulkPartialSuccessResult`

curl -X POST https://api.factuarea.com/v1/recurring_invoices/bulk-status \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b" \
  -d '{
    "ids": [
      "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
      "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff"
    ],
    "new_status": "paused"
  }'

{
  "data": {
    "total": 3,
    "successful": 2,
    "failed": 1,
    "failures": [
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff",
        "error_code": "recurring_invoice_already_paused",
        "error_message": "Esta factura recurrente ya está pausada."
      }
    ]
  }
}

Nada aborta el lote

paused pausa las recurrencias activas y active reanuda las pausadas. Cada id pasa por la misma transición unitaria —y por tanto por los mismos guards— que POST /v1/recurring_invoices/{recurring_invoice}/pause y /resume, así que un lote nunca aplica un cambio que la ruta de una en una habría rechazado.

Los ids que no son elegibles vuelven en failures[] con su error_code mientras el resto del lote se aplica:

`error_code`	Cuándo
`recurring_invoice_not_found`	Id desconocido, o factura recurrente de otra empresa.
`recurring_invoice_already_paused`	Ya está pausada y `new_status` es `paused`.
`recurring_invoice_already_active`	Ya está activa y `new_status` es `active`.
`recurring_invoice_cancelled_cannot_resume`	Recurrencia cancelada: no se reanuda nunca.
`recurring_invoice_completed_cannot_resume`	Ocurrencias agotadas o fecha de fin pasada.
`business_rule_violation`	Cualquier otra regla de dominio que bloquee la transición, como el guard de envío automático.

Un cuerpo con más de 50 ids, con ids repetidos o con un new_status fuera de [active, paused] se rechaza entero con 422 invalid_param_value antes de aplicar nada.

Código de error nuevo: recurring_invoice_completed_cannot_resume

El 422 recurring_invoice_completed_cannot_resume nombra ahora el caso que antes llegaba como una violación de regla genérica: una recurrencia que ha agotado sus ocurrencias o ha pasado su fecha de fin no se reanuda ni se activa. Se emite dentro de failures[] en la operación en bloque y como status de la respuesta en POST /v1/recurring_invoices/{recurring_invoice}/resume y /activate, cuyos contratos declaran 422 desde esta publicación. Crea una recurrencia nueva, o amplía el número de ocurrencias o la fecha de fin de esta, antes de activarla.

MCP

bulk_change_recurring_invoice_status es el espejo de la operación: scope recurring_invoices:transition, categoría write, hasta 50 ids y el mismo new_status. Devuelve los mismos contadores y el mismo failures[], así que un asistente puede contar qué se aplicó y qué se omitió. Consulta el catálogo de tools MCP.

bulk_delete_recurring_invoices y las operaciones de una sola plantilla no cambian.

Nuevos endpoints1

Endpoint	Descripción
POST`/v1/recurring_invoices/bulk-status`	Cambiar en bloque el estado de facturas recurrentes

Endpoints actualizados2

Endpoint	Descripción
POST`/v1/recurring_invoices/{recurring_invoice}/resume`	Reanudar factura recurrente
POST`/v1/recurring_invoices/{recurring_invoice}/activate`	Activar factura recurrente