Pausar i reprendre factures recurrents en bloc

Pausar un grup de factures recurrents volia dir una crida per plantilla: POST /v1/recurring_invoices/{recurring_invoice}/pause per cada id, amb els teus propis reintents i el teu propi recompte d'errors a sobre. L'eliminació en bloc ja tenia POST /v1/recurring_invoices/bulk-delete; el canvi d'estat, no.

POST /v1/recurring_invoices/bulk-status tanca aquest buit amb el mateix contracte d'èxit parcial que fan servir les altres operacions d'estat en bloc.

L'operació


Ruta	`POST /v1/recurring_invoices/bulk-status`
Scope	`recurring_invoices:transition`
Cos	`ids` (d'1 a 50 `uuid` sense repetir) i `new_status` (`active` o `paused`)
Resposta	`200` amb 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."
      }
    ]
  }
}

Res no avorta el lot

paused pausa les recurrències actives i active reprèn les pausades. Cada id passa per la mateixa transició unitària —i per tant pels mateixos guards— que POST /v1/recurring_invoices/{recurring_invoice}/pause i /resume, així que un lot mai no aplica un canvi que la ruta d'una en una hauria rebutjat.

Els ids que no són elegibles tornen a failures[] amb el seu error_code mentre la resta del lot s'aplica:

`error_code`	Quan
`recurring_invoice_not_found`	Id desconegut, o factura recurrent d'una altra empresa.
`recurring_invoice_already_paused`	Ja està pausada i `new_status` és `paused`.
`recurring_invoice_already_active`	Ja està activa i `new_status` és `active`.
`recurring_invoice_cancelled_cannot_resume`	Recurrència cancel·lada: no es reprèn mai.
`recurring_invoice_completed_cannot_resume`	Ocurrències esgotades o data de fi passada.
`business_rule_violation`	Qualsevol altra regla de domini que bloquegi la transició, com el guard de lliurament automàtic.

Un cos amb més de 50 ids, amb ids repetits o amb un new_status fora de [active, paused] es rebutja sencer amb 422 invalid_param_value abans d'aplicar res.

Codi d'error nou: recurring_invoice_completed_cannot_resume

El 422 recurring_invoice_completed_cannot_resume anomena ara el cas que abans arribava com una violació de regla genèrica: una recurrència que ha esgotat les seves ocurrències o ha passat la data de fi no es reprèn ni s'activa. S'emet dins de failures[] a l'operació en bloc i com a status de la resposta a POST /v1/recurring_invoices/{recurring_invoice}/resume i /activate, els contractes dels quals declaren 422 a partir d'aquesta publicació. Crea una recurrència nova, o amplia el nombre d'ocurrències o la data de fi d'aquesta, abans d'activar-la.

MCP

bulk_change_recurring_invoice_status és el mirall de l'operació: scope recurring_invoices:transition, categoria write, fins a 50 ids i el mateix new_status. Retorna els mateixos comptadors i el mateix failures[], així que un assistent pot explicar què s'ha aplicat i què s'ha omès. Consulta el catàleg d'eines MCP.

bulk_delete_recurring_invoices i les operacions d'una sola plantilla no canvien.

Nous endpoints1

Endpoint	Descripció
POST`/v1/recurring_invoices/bulk-status`	Canviar en bloc l'estat de factures recurrents

Endpoints actualitzats2

Endpoint	Descripció
POST`/v1/recurring_invoices/{recurring_invoice}/resume`	Reprendre factura recurrent
POST`/v1/recurring_invoices/{recurring_invoice}/activate`	Activar factura recurrent