Tope anual de documentos en la API y MCP

30 de septiembre de 2026

Producción mide actualmente el uso de documentos sin bloquear la creación interactiva. Las respuestas de rechazo y los pasos de recuperación descritos a continuación se aplican cuando se activa la aplicación del tope documental.

Qué cambia

La creación interactiva de documentos de venta cuenta para el tope anual de la empresa en la app, la API v1, MCP, el asistente, las importaciones, los duplicados y las conversiones. Con la aplicación del tope activada, al agotarlo v1 responde HTTP 402 con error.type: payment_required_error y error.code: plan_limit_exceeded. MCP responde JSON-RPC -32004 con message: plan_limit_exceeded y data.http_status: 402; no utiliza el cuerpo de error REST.

Las facturas de venta, rectificativas y sustitutivas, los presupuestos, albaranes y facturas proforma cuentan al crearse. Una conversión cuenta la factura nueva, además del documento de origen que ya contó. Emitir, enviar o anular un documento existente no suma ni devuelve una unidad. Eliminar un borrador elegible devuelve una unidad a la ventana anual vigente. Las facturas del proveedor no cuentan.

Las operaciones v1 afectadas (14 en total) y sus tools MCP

Estas operaciones existentes pueden rechazar la creación interactiva al alcanzar el tope. Conservan sus URLs, campos de request y nombres de tools.

Operación v1	Tool MCP
`POST /v1/invoices`	`create_invoice`
`POST /v1/invoices/{invoice}/duplicate`	`duplicate_invoice`
`POST /v1/invoices/{invoice}/corrective`	`create_corrective_invoice`
`POST /v1/invoices/substitute-simplified`	`substitute_simplified_invoice`
`POST /v1/quotes`	`create_quote`
`POST /v1/quotes/{quote}/duplicate`	`duplicate_quote`
`POST /v1/quotes/{quote}/convert`	`convert_quote`
`POST /v1/delivery_notes`	`create_delivery_note`
`POST /v1/delivery_notes/{delivery_note}/duplicate`	`duplicate_delivery_note`
`POST /v1/delivery_notes/{delivery_note}/convert`	`convert_delivery_note`
`POST /v1/proformas`	`create_proforma`
`POST /v1/proformas/{proforma}/duplicate`	`duplicate_proforma`
`POST /v1/proformas/{proforma}/convert`	`convert_proforma`
`POST /v1/recurring_invoices/{recurring_invoice}/generate`	—

La operación de generación manual de una factura recurrente actualmente no tiene una tool MCP equivalente.

POST /v1/invoices/bulk-create y bulk_create_invoices informan los rechazos por tope por fila mediante failures[]. El lote REST conserva su response 200/207; no pertenece a ese grupo de 14 con un 402 global.

Lee los detalles del error

El error v1 expone error.details. Ramifica según el error.code estable; error.message es texto en español para personas y puede cambiar. Este ejemplo procede del contrato de response de facturas:

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

Campo	Significado
`resource`	El recurso agotado: `documents_year`.
`current`	Documentos ya contados en la ventana vigente; la creación rechazada no consume una unidad.
`limit`	El tope anual fijo de documentos aplicado a la empresa.
`period_end`	El fin real de la ventana anual, como timestamp ISO 8601 completo con su desplazamiento. Espera hasta que haya pasado ese instante, sin asumir un reinicio por año natural.

En MCP, esos mismos cuatro campos están en error.data, junto con http_status, code y el hint en español:

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

Las emisiones automáticas continúan y cuentan

Las facturas recurrentes programadas, las facturas de integraciones de cobros, pedidos de tiendas y ciclos de suscripción, las rectificativas de reembolsos de integraciones y las autofacturas de suscripción siguen emitiéndose al agotar el tope documental. Cuentan y pueden elevar el uso por encima del tope. Pedir manualmente «generar ahora» en una recurrente es interactivo y puede rechazarse. Un rechazo manual por tope no registra un fallo de generación de la recurrente.

El uso documental de Enterprise se rige por tu contrato; este cambio no introduce un tope automático de documentos para ese plan. El uso sigue contándose.

Anticípate al tope

Revisa tu plan con GET /v1/account/billing y consulta el uso de documentos en la app. El titular recibe avisos al cruzar el 80 %, alcanzar el 100 % y superar por primera vez el tope mediante una emisión automática, una vez por ventana anual y umbral. Actúa ante los avisos antes de que se detengan las altas interactivas.

Tras plan_limit_exceeded, amplía tu plan para crear documentos ahora o espera hasta que haya pasado el period_end real. Reintentar inmediatamente no libera cuota documental. Sigue respetando Retry-After para los errores independientes de límite de peticiones.

Documentación relacionada

Tratamiento de errores

Errores y límites de peticiones de MCP

Endpoints actualizados14

Endpoint	Descripción
POST`/v1/invoices`	Crea una factura
POST`/v1/invoices/{invoice}/duplicate`	Duplicar una factura
POST`/v1/invoices/{invoice}/corrective`	Generar factura rectificativa
POST`/v1/invoices/substitute-simplified`	Sustituir facturas simplificadas por factura completa
POST`/v1/quotes`	Crea un presupuesto
POST`/v1/quotes/{quote}/duplicate`	Duplicar un presupuesto
POST`/v1/quotes/{quote}/convert`	Convertir presupuesto en factura
POST`/v1/delivery_notes`	Crear un albarán
POST`/v1/delivery_notes/{delivery_note}/duplicate`	Duplicar un albarán
POST`/v1/delivery_notes/{delivery_note}/convert`	Convertir albarán en factura
POST`/v1/proformas`	Crea una proforma
POST`/v1/proformas/{proforma}/duplicate`	Duplicar una proforma
POST`/v1/proformas/{proforma}/convert`	Convertir proforma en factura
POST`/v1/recurring_invoices/{recurring_invoice}/generate`	Genera una factura a partir de una plantilla recurrente