Validaciones
El SDK aplica localmente todas las validaciones listadas en Validaciones y errores del servicio v1.2.2. Esto te permite cazar registros mal formados antes de gastar una llamada SOAP — la AEAT devolvería el mismo diagnóstico, pero en microsegundos.
Llamar al validador
import {
validateInvoiceForRegister,
validateInvoiceForCancel,
} from 'verifactu-sdk/validators';
const issues = validateInvoiceForRegister(invoice);
if (issues.some((i) => i.severity === 'rejection')) {
throw new BusinessValidationError('Factura rechazada', { code: issues[0]!.code });
}Cada ValidationResult devuelto lleva:
code— el código de error de la AEAT más cercano del catálogo.field— ruta con puntos del campo en conflicto (p. ej.breakdown.0.taxRate).severity—'rejection'rechaza el registro,'admissible'lo acepta con advertencia.message— descripción corta en inglés de la incidencia.
VerifactuClient.registerInvoice ejecuta el validador automáticamente y lanza BusinessValidationError en caso de rechazo; sólo llamas al validador directamente cuando quieres inspeccionar todas las incidencias a la vez.
Las 23 reglas
El validador implementa una o más comprobaciones por regla de la AEAT. La correspondencia es:
| Regla | Grupo de campos | Qué comprueba | Severidad |
|---|---|---|---|
| 1 | IDFactura | Formato del NIF, caracteres permitidos en NumSerieFactura, FechaExpedicion ≥ 28-10-2024 y ±20 años respecto a hoy. | Rechazo |
| 2 | RechazoPrevio + Subsanacion | Sólo combinaciones coherentes (N, S, X). | Rechazo |
| 3 | TipoRectificativa | Obligatoria sólo si TipoFactura empieza por R. | Rechazo |
| 4 | FacturasRectificadas | Sólo permitida en facturas tipo R. | Rechazo |
| 5 | FacturasSustituidas | Sólo permitida en facturas F3. | Rechazo |
| 6 | ImporteRectificacion | Obligatorio cuando TipoRectificativa = S. | Rechazo |
| 7 | FechaOperacion | ±20 años respecto a la fecha de expedición, reglas especiales para ClaveRegimen 14/15. | Rechazo |
| 8 | FacturaSimplificadaArt7273 | Sólo en F1/F3/R1/R2/R3/R4. | Rechazo |
| 9 | FacturaSinIdentifDestinatarioArt61d | Sólo en F2/R5. | Rechazo |
| 10 | Macrodato | Obligatorio si ImporteTotal ≥ 100 000 000 €. | Rechazo |
| 11 | EmitidaPorTerceroODestinatario | Coherencia con Tercero / Destinatarios. | Rechazo |
| 12 | Tercero | Formato NIF, distinto del emisor, estructura NIF-IVA por país. | Rechazo |
| 13 | Destinatarios | Obligatorios para F1/F3/R1/R2/R3/R4; prohibidos para F2/R5; formato NIF; estructura NIF-IVA. | Rechazo |
| 14 | Cupon | Sólo permitido cuando TipoFactura es R1 o R5. | Rechazo |
| 15.1 | Desglose.TipoImpositivo | Tipo permitido por fecha (según tabla histórica de la AEAT). | Rechazo |
| 15.2 | BaseImponibleACoste | Sólo cuando ClaveRegimen = 06 o Impuesto en 02/05. | Rechazo |
| 15.3 | TipoRecargoEquivalencia | Pareja válida con TipoImpositivo (21/5.2, 10/1.4, …). | Rechazo |
| 15.4 | CalificacionOperacion | S1/S2/N1/N2; mutuamente excluyente con OperacionExenta. | Rechazo |
| 15.5 | OperacionExenta | E1-E6 (IVA); E7/E8 sólo para IGIC; coherencia con TipoFactura. | Rechazo |
| 15.6 | ClaveRegimen | 01-21 con sub-reglas para 02/03/04/06/07/08/10/11/14/20/21. | Rechazo |
| 15.7 | CuotaRepercutida | base × tipo con tolerancia ±10 € (≤ 3 000 € para simplificadas). | Rechazo |
| 16 | CuotaTotal | Suma de cuotas repercutidas con tolerancia ±10 €. | Rechazo |
| 17 | ImporteTotal | Suma de bases + impuesto + recargo con tolerancia ±10 €. | Rechazo |
| 18 | Huella anterior | 64 caracteres hex en mayúsculas cuando está presente. | Admisible (2003) |
| 19 | SistemaInformatico | SystemId 2 caracteres [A-Z0-9] excluyendo Ñ; coherencia TipoUsoPosibleSoloVerifactu / MultiOT. | Rechazo |
| 20 | FechaHoraHusoGenRegistro | ISO 8601 válido con offset; no en futuro lejano. | Rechazo / Admisible |
| 21 | NumRegistroAcuerdoFacturacion | ≤ 15 caracteres, juego de caracteres permitido. | Rechazo |
| 22 | IdAcuerdoSistemaInformatico | ≤ 16 caracteres, juego de caracteres permitido. | Rechazo |
| 23 | Huella | 64 caracteres hex en mayúsculas. | Admisible (1292) |
NIF, NIE, CIF
El validador local cubre las tres formas de identificador español y el dígito de control:
- DNI: 8 dígitos + letra de control calculada por la tabla mod-23.
- NIE: prefijo
X|Y|Z+ 7 dígitos + letra de control, misma tabla. - CIF: letra + 7 dígitos + dígito/letra de control (algoritmo mixto mod-10 / mod-11 según la spec AEAT).
NIF-IVA (UE)
El validador cubre los 28 estados miembros históricos de la UE más Irlanda del Norte (GB/XI) con gestión Brexit consciente de fechas. Las estructuras y las reglas por país se cargan desde validators/nifIva.ts. Ejemplos:
| País | Código | Estructura |
|---|---|---|
| Alemania | DE | 9 dígitos |
| Francia | FR | 11 caracteres (2 alfanuméricos + 9 dígitos) |
| Italia | IT | 11 dígitos |
| Portugal | PT | 9 dígitos |
| Países Bajos | NL | 12 caracteres |
| Reino Unido | GB | 9 / 12 dígitos; válido sólo ≤ 31-12-2020 (post-Brexit, usar XI) |
| Irlanda del Norte | XI | 9 / 12 dígitos; válido sólo ≥ 01-01-2021 |
El validador acepta country=ES por completitud, pero los NIF españoles pasan por la ruta local de NIF/CIF.
Severidad
La AEAT distingue tres severidades:
envelope— se rechaza el envío completo (códigos 4xxx, los pone el servicio tras parsear el sobre SOAP).record— sólo se rechaza el registro afectado (códigos 1xxx y 3xxx).admissible— el registro se acepta pero se marca para subsanación (códigos 2xxx).
El validador local devuelve los dos primeros como severity: 'rejection' y el tercero como severity: 'admissible'. Los errores de envelope vienen del nivel de cable y nunca aparecen en el resultado local.
Siguiente
- Códigos de error — catálogo completo de códigos con el texto literal en español de
errores.properties. - Cadena de huellas