Alcance y limitaciones

Lo que la API de Factuarea no hace a propósito, lo que aún no hace, y la forma equivalente de resolver cada caso — más cuatro capacidades que puedes dar por ausentes y no lo están.

Toda plataforma tiene fronteras. Una frontera que puedes leer antes de integrar es una decisión de diseño; una que descubres en producción es un defecto. Esta página es la única lista canónica — ninguna otra guía mantiene la suya.

Cada fila declara el escenario, su estado y el workaround: la alternativa disponible hoy, o una declaración explícita de que no la hay. Hay exactamente dos estados, porque una tercera categoría difusa es lo que convierte páginas como esta en mero adorno:

Por diseño — no lo vamos a construir. La alternativa está aquí.
En roadmap — aplazado, no descartado.

Verificado el 31 de julio de 2026 contra la v1 de la API. Una fila cuyo escenario pase a estar soportado se retira en el mismo cambio que lo implementa, en lugar de quedarse ahí como limitación obsoleta.

Limitaciones verificadas contra el código

Escenario	Estado	Workaround
Autofactura — el destinatario expide la factura en nombre del proveedor	Por diseño	No está modelada. El proveedor expide su propia factura. Si operas ambas partes, emítela desde la cuenta del proveedor.
Factura expedida por un tercero	Por diseño	El campo AEAT de expedición por tercero no se emite. Una asesoría que opera la cuenta de un cliente emite desde esa cuenta con `X-Active-Profile`; la factura se declara como expedida por la propia empresa.
Multidivisa	Por diseño	El contrato v1 expone el euro, fijo: `currency` vale siempre `EUR` y no existe columna de divisa. Filtrar un listado por cualquier otra divisa devuelve una página vacía, no un error. Factura en euros y convierte fuera de Factuarea.
TicketBAI / Batuz (País Vasco)	Por diseño	Sin alternativa dentro de Factuarea. Los sistemas forales vascos usan esquemas, certificados y endpoints distintos, y exigen su propio software homologado. Las empresas con domicilio fiscal vasco reciben el aviso durante el onboarding.
Inversión del sujeto pasivo, y cualquier régimen de operación de cabecera, declarados por la API	Por diseño	El `operation_regime` de cabecera es de solo lectura en la v1 —ni la creación ni la actualización lo aceptan—, así que toda factura creada por la API nace en régimen general y se califica `S1`. La exención y la no sujeción se declaran por línea con `lines[].exemption_reason`, pero la inversión del sujeto pasivo es la calificación `S2` y no tiene equivalente de línea: emite esas facturas desde el panel. Ver Clientes internacionales.
Suplidos fuera de la factura emitida — presupuestos, proformas, albaranes, facturas de compra, plantillas de recurrentes	Por diseño	Solo la factura emitida modela los suplidos. Incluye el importe como línea ordinaria en el documento previo, y fija `line_type` en la factura resultante mientras siga en borrador — la operación de actualización lo acepta.
Suplidos en el XML de Facturae y UBL — el importe a pagar del XML es el total fiscal, no el importe debido	En roadmap	La base imponible y las cuotas salen correctas —el suplido está bien excluido—, pero el importe a pagar se queda corto por ese importe y ningún elemento del XML transporta la diferencia. No remitas por FACe una factura con líneas de suplido mientras no se mapee el bloque nativo de Facturae 3.2.2: factura el suplido fuera de ese canal.
Suplidos en las cifras agregadas de cartera — el `pending_amount` de `GET /v1/invoices/stats`, el informe de aging y el de mayores deudores	Por diseño	Esos agregados miden volumen facturado, la misma magnitud que declara la declaración anual de operaciones con terceros, y tampoco han restado nunca los cobros parciales. Para el importe realmente debido, lee el `pending_amount` de cada factura, que sí mide contra el importe a pagar.

Diferencias deliberadas con otras plataformas

Son decisiones de producto conscientes, no huecos. Cada una existe porque la alternativa que elegimos es mejor para quien integra que el patrón que se nos pide.

Escenario	Estado	Workaround
Paginación por desplazamiento con número de páginas y salto a la página N	Por diseño	Paginación por cursor al estilo de Stripe: `limit` con límites validados, más `starting_after` o `ending_before` (mutuamente excluyentes). Las respuestas llevan `has_more` y `next_cursor`, y `next_cursor` vale `null` cuando `has_more` es falso. Ver Paginación.
Envelope de error dual permanente — nuestro envelope y RFC 9457 en el mismo cuerpo, siempre	Por diseño	Negociación de contenido. `Accept: application/problem+json` devuelve RFC 9457 puro; cualquier otro caso —`application/json`, `/`, sin cabecera `Accept`— devuelve nuestro envelope. Ver Errores.
Atomicidad total en la creación masiva — una fila mala rechaza el lote entero	Por diseño	Éxito parcial. La respuesta lleva `{dry_run, total, successful, failed, results, failures}`, donde cada fallo identifica su fila por un `index` que empieza en cero, con su propio código de error. Importa 480 de 500 y arregla las 20. Ver Operaciones masivas.
Totales de línea obligatorios en la petición (`line_total`, `taxable_base`)	Por diseño	`line_total` es una suma de control opcional verificada: se compara con el total calculado con una tolerancia de un céntimo y se descarta — nunca se persiste, nunca se devuelve. No tienes que replicar nuestro motor de cálculo. Ver Suplidos.
Representación o apoderamiento por terceros — endpoints de apoderado, documentos de autorización firmados	Por diseño	Cada empresa sube su propio certificado, que debe coincidir con su propio NIF, se valida por estructura y tamaño, y cuya contraseña se guarda cifrada.
Sustituir facturas simplificadas en dos pasos — una rectificativa más una factura completa nueva	Por diseño	Un solo paso nativo: `POST /v1/invoices/substitute-simplified` emite la factura sustitutiva agregando varias simplificadas. Ver Facturas simplificadas o completas.
SDK de Python	En roadmap	Genera un cliente a partir del documento OpenAPI publicado, o usa los SDK de TypeScript o PHP, el CLI o el servidor MCP.

Capacidades que puedes dar por ausentes

Cuatro cosas que Factuarea sí hace y que quien llega de otras plataformas espera habitualmente no encontrar:

Capacidad	Dónde
Factura sustitutiva de simplificadas, en una sola llamada — agregar varios tiques en una factura completa sin rectificativa previa	Facturas simplificadas o completas · `POST /v1/invoices/substitute-simplified`
Subsanación de registros VeriFactu rechazados, expuesta en la API pública — reparar una declaración rechazada sin anular la factura	Subsanación de registros VeriFactu · `POST /v1/verifactu/records/{id}/subsanar`
Rectificativa por diferencias con base imponible negativa — la forma fiscalmente correcta de expresar un abono	Facturas rectificativas
Catálogo fiscal AEAT consultable por la API — regímenes indirectos, regímenes de operación, causas de exención con su artículo de la LIVA, tipos de retención y los pares legales de IVA y recargo, en tres idiomas	Claves de régimen · `GET /v1/tax-catalog`

Ninguna de ellas está anunciada ni en desarrollo: las cuatro son operaciones vivas hoy.

Dónde vive el razonamiento fiscal

Esta página lista fronteras. Las guías que explican las reglas que hay detrás:

Estados de envío VeriFactu

El ciclo de vida del registro, reintento y subsanación.

Facturas rectificativas

R1–R5, sustitución frente a diferencias.

Claves de régimen

Calificación de cabecera y catálogo de régimen por línea.

Impuestos territoriales

IVA, IGIC e IPSI.

Suplidos

Importes pagados por cuenta del cliente.

Clientes internacionales

Identificación alternativa y mapa de escenarios.

Trazabilidad

Esta página documenta la ausencia de comportamiento, algo que ninguna regla de negocio puede afirmar. Sus filas se anclan, por tanto, de forma distinta a las demás guías fiscales: a un punto verificado del código, a la decisión registrada para la plataforma o —cuando sí existe una regla de negocio— a esa regla.

Limitaciones verificadas contra el código:

Fila	Anclaje
Autofactura	No existe esa capacidad en el dominio. Las únicas apariciones del concepto son la factura que Factuarea emite a sus propios suscriptores y la comprobación de la empresa del sistema — ninguna de las dos es una capacidad de la API.
Factura expedida por un tercero	El campo AEAT de expedición por tercero no se emite nunca; cero apariciones en el código de la aplicación.
Multidivisa	`InvoiceV1Resource` devuelve el literal `'EUR'`, y el repositorio de lectura de la v1 documenta que cualquier otra divisa produce una página vacía.
TicketBAI / Batuz	`BR-VFC-019` — deliberadamente fuera del alcance del contexto VeriFactu.
Inversión del sujeto pasivo por la API	Ninguna petición de la v1 acepta `operation_regime`; el recurso de factura lo devuelve de solo lectura. `BR-VFC-029` deriva la calificación de ese régimen de cabecera, y `BR-INV-032` acota el catálogo de línea a causas de exención y no sujeción, sin códigos `S`.
Suplidos fuera de la factura emitida	`BR-INV-037` y el objeto de valor del tipo de línea, que declara que solo la factura emitida modela los suplidos; `BR-INV-040` para la restricción de la factura simplificada.
Suplidos en el XML de Facturae y UBL	El edge case de aviso de `BR-INV-042`, que deja registrado que el importe a pagar de ambos documentos es el total fiscal y que el bloque nativo de Facturae 3.2.2 aún no está mapeado.
Suplidos en las cifras agregadas de cartera	El edge case de `BR-INV-045`, que deja registrado que los agregados miden volumen facturado y que se dejan midiendo eso a propósito.

Diferencias deliberadas: ancladas a los componentes HTTP compartidos que implementan la alternativa —la paginación por cursor, el negociador de contenido de errores, el recurso de éxito parcial de las operaciones masivas—, a BR-INV-044 para la suma de control opcional de línea, a BR-VFC-003, BR-VFC-004, BR-VFC-022 y BR-VFC-024 para los certificados propios de cada empresa, y a BR-INV-015 y BR-INV-016 para la sustitución en un solo paso. La fila del SDK de Python refleja una decisión registrada de planificarlo aparte cuando la especificación se estabilice: está aplazado, no descartado, y por eso su estado es En roadmap y no Por diseño.

Capacidades: cada una se ancla a la ruta viva que la materializa — public-api.v1.invoices.substitute_simplified, public-api.v1.verifactu.records.subsanar y public-api.v1.tax-catalog.show — más BR-VFC-033 para la base imponible negativa y BR-TAX-028 para el catálogo fiscal.