Topall anual de documents a l’API i MCP

30 de setembre de 2026

Què canvia

La creació interactiva de documents de venda compta per al topall anual de l’empresa a l’app, l’API v1, MCP, l’assistent, les importacions, els duplicats i les conversions. Amb l’aplicació del topall activada, en esgotar-lo v1 retorna HTTP 402 amb error.type: payment_required_error i error.code: plan_limit_exceeded. MCP retorna JSON-RPC -32004 amb message: plan_limit_exceeded i data.http_status: 402; no utilitza el cos d’error REST.

Les factures de venda, rectificatives i substitutives, els pressupostos, albarans i factures proforma compten en crear-se. Una conversió compta la factura nova, a més del document d’origen que ja va comptar. Emetre, enviar o anul·lar un document existent no suma ni retorna una unitat. Eliminar un esborrany elegible retorna una unitat a la finestra anual vigent. Les factures del proveïdor no compten.

Les operacions v1 afectades (14 en total) i les seves tools MCP

Aquestes operacions existents poden rebutjar la creació interactiva en arribar al topall. Conserven les seves URLs, camps de request i noms de tools.

L’operació de generació manual d’una factura recurrent actualment no té una tool MCP equivalent.

POST /v1/invoices/bulk-create i bulk_create_invoices informen dels rebutjos per topall per fila mitjançant failures[]. El lot REST conserva la seva response 200/207; no pertany a aquest grup de 14 amb un 402 global.

Llegeix els detalls de l’error

L’error v1 exposa error.details. Ramifica segons el error.code estable; error.message és text en castellà per a persones i pot canviar. Aquest exemple prové del contracte de response de factures:

{
  "error": {
    "type": "payment_required_error",
    "code": "plan_limit_exceeded",
    "message": "Has alcanzado el límite anual de documentos de tu plan (7/7). El periodo termina el 2027-03-14; amplía el plan para seguir creando documentos ahora.",
    "param": null,
    "details": {
      "resource": "documents_year",
      "current": 7,
      "limit": 7,
      "period_end": "2027-03-14T23:59:59+01:00"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#plan_limit_exceeded",
    "request_id": "req_01HKQS5NDOCUMENTQUOTA01"
  }
}

A MCP, aquests mateixos quatre camps són a error.data, juntament amb http_status, code i el hint en castellà:

{
  "jsonrpc": "2.0",
  "id": "req-42",
  "error": {
    "code": -32004,
    "message": "plan_limit_exceeded",
    "data": {
      "http_status": 402,
      "code": "plan_limit_exceeded",
      "resource": "documents_year",
      "current": 7,
      "limit": 7,
      "period_end": "2027-03-14T23:59:59+01:00",
      "hint": "Has alcanzado el límite anual de documentos de tu plan (7/7). El periodo termina el 2027-03-14; amplía el plan para seguir creando documentos ahora."
    }
  }
}

Les emissions automàtiques continuen i compten

Les factures recurrents programades, les factures d’integracions de cobraments, comandes de botigues i cicles de subscripció, les rectificatives de reemborsaments d’integracions i les autofactures de subscripció continuen emetent-se en esgotar el topall documental. Compten i poden elevar l’ús per sobre del topall. Demanar manualment «generar ara» en una recurrent és interactiu i pot rebutjar-se. Un rebuig manual per topall no registra una fallada de generació de la recurrent.

L’ús documental d’Enterprise es regeix pel teu contracte; aquest canvi no introdueix un topall automàtic de documents per a aquest pla. L’ús continua comptant-se.

Anticipa’t al topall

Revisa el teu pla amb GET /v1/account/billing i consulta l’ús de documents a l’app. El titular rep avisos en creuar el 80 %, arribar al 100 % i superar per primera vegada el topall mitjançant una emissió automàtica, una vegada per finestra anual i llindar. Actua davant dels avisos abans que s’aturin les altes interactives.

Després de plan_limit_exceeded, amplia el teu pla per crear documents ara o espera fins que hagi passat el period_end real. Reintentar immediatament no allibera quota documental. Continua respectant Retry-After per als errors independents de límit de peticions.

Documentació relacionada