Validacións
O SDK aplica localmente todas as validacións listadas en Validaciones y errores del servicio v1.2.2. Isto permíteche cazar rexistros mal formados antes de gastar unha chamada SOAP — a AEAT devolvería o mesmo diagnóstico, pero en microsegundos.
Chamar ao validador
import {
validateInvoiceForRegister,
validateInvoiceForCancel,
} from 'verifactu-sdk/validators';
const issues = validateInvoiceForRegister(invoice);
if (issues.some((i) => i.severity === 'rejection')) {
throw new BusinessValidationError('Factura rexeitada', { code: issues[0]!.code });
}Cada ValidationResult devolto leva:
code— o código de erro da AEAT máis próximo do catálogo.field— ruta con puntos do campo en conflito (p. ex.breakdown.0.taxRate).severity—'rejection'rexeita o rexistro,'admissible'acéptao con advertencia.message— descrición curta en inglés da incidencia.
VerifactuClient.registerInvoice executa o validador automaticamente e lanza BusinessValidationError en caso de rexeitamento; só chamas ao validador directamente cando queres inspeccionar todas as incidencias á vez.
As 23 regras
O validador implementa unha ou máis comprobacións por regra da AEAT. A correspondencia é:
| Regra | Grupo de campos | Que comproba | Severidade |
|---|---|---|---|
| 1 | IDFactura | Formato do NIF, caracteres permitidos en NumSerieFactura, FechaExpedicion ≥ 28-10-2024 e ±20 anos respecto a hoxe. | Rexeitamento |
| 2 | RechazoPrevio + Subsanacion | Só combinacións coherentes (N, S, X). | Rexeitamento |
| 3 | TipoRectificativa | Obrigatoria só se TipoFactura empeza por R. | Rexeitamento |
| 4 | FacturasRectificadas | Só permitida en facturas tipo R. | Rexeitamento |
| 5 | FacturasSustituidas | Só permitida en facturas F3. | Rexeitamento |
| 6 | ImporteRectificacion | Obrigatorio cando TipoRectificativa = S. | Rexeitamento |
| 7 | FechaOperacion | ±20 anos respecto á data de expedición, regras especiais para ClaveRegimen 14/15. | Rexeitamento |
| 8 | FacturaSimplificadaArt7273 | Só en F1/F3/R1/R2/R3/R4. | Rexeitamento |
| 9 | FacturaSinIdentifDestinatarioArt61d | Só en F2/R5. | Rexeitamento |
| 10 | Macrodato | Obrigatorio se ImporteTotal ≥ 100 000 000 €. | Rexeitamento |
| 11 | EmitidaPorTerceroODestinatario | Coherencia con Tercero / Destinatarios. | Rexeitamento |
| 12 | Tercero | Formato NIF, distinto do emisor, estrutura NIF-IVA por país. | Rexeitamento |
| 13 | Destinatarios | Obrigatorios para F1/F3/R1/R2/R3/R4; prohibidos para F2/R5; formato NIF; estrutura NIF-IVA. | Rexeitamento |
| 14 | Cupon | Só permitido cando TipoFactura é R1 ou R5. | Rexeitamento |
| 15.1 | Desglose.TipoImpositivo | Tipo permitido por data (segundo táboa histórica da AEAT). | Rexeitamento |
| 15.2 | BaseImponibleACoste | Só cando ClaveRegimen = 06 ou Impuesto en 02/05. | Rexeitamento |
| 15.3 | TipoRecargoEquivalencia | Parella válida con TipoImpositivo (21/5.2, 10/1.4, …). | Rexeitamento |
| 15.4 | CalificacionOperacion | S1/S2/N1/N2; mutuamente excluínte con OperacionExenta. | Rexeitamento |
| 15.5 | OperacionExenta | E1-E6 (IVA); E7/E8 só para IGIC; coherencia con TipoFactura. | Rexeitamento |
| 15.6 | ClaveRegimen | 01-21 con sub-regras para 02/03/04/06/07/08/10/11/14/20/21. | Rexeitamento |
| 15.7 | CuotaRepercutida | base × tipo con tolerancia ±10 € (≤ 3 000 € para simplificadas). | Rexeitamento |
| 16 | CuotaTotal | Suma de cotas repercutidas con tolerancia ±10 €. | Rexeitamento |
| 17 | ImporteTotal | Suma de bases + imposto + recarga con tolerancia ±10 €. | Rexeitamento |
| 18 | Huella anterior | 64 caracteres hex en maiúsculas cando está presente. | Admisible (2003) |
| 19 | SistemaInformatico | SystemId 2 caracteres [A-Z0-9] excluíndo Ñ; coherencia TipoUsoPosibleSoloVerifactu / MultiOT. | Rexeitamento |
| 20 | FechaHoraHusoGenRegistro | ISO 8601 válido con offset; non en futuro afastado. | Rexeitamento / Admisible |
| 21 | NumRegistroAcuerdoFacturacion | ≤ 15 caracteres, conxunto de caracteres permitido. | Rexeitamento |
| 22 | IdAcuerdoSistemaInformatico | ≤ 16 caracteres, conxunto de caracteres permitido. | Rexeitamento |
| 23 | Huella | 64 caracteres hex en maiúsculas. | Admisible (1292) |
NIF, NIE, CIF
O validador local cobre as tres formas de identificador español e o díxito de control:
- DNI: 8 díxitos + letra de control calculada pola táboa mod-23.
- NIE: prefixo
X|Y|Z+ 7 díxitos + letra de control, mesma táboa. - CIF: letra + 7 díxitos + díxito/letra de control (algoritmo mixto mod-10 / mod-11 segundo a spec AEAT).
NIF-IVA (UE)
O validador cobre os 28 estados membros históricos da UE máis Irlanda do Norte (GB/XI) con xestión Brexit consciente de datas. As estruturas e as regras por país cárganse de validators/nifIva.ts. Exemplos:
| País | Código | Estrutura |
|---|---|---|
| Alemaña | DE | 9 díxitos |
| Francia | FR | 11 caracteres (2 alfanuméricos + 9 díxitos) |
| Italia | IT | 11 díxitos |
| Portugal | PT | 9 díxitos |
| Países Baixos | NL | 12 caracteres |
| Reino Unido | GB | 9 / 12 díxitos; válido só ≤ 31-12-2020 (post-Brexit, usar XI) |
| Irlanda do Norte | XI | 9 / 12 díxitos; válido só ≥ 01-01-2021 |
O validador acepta country=ES por completude, pero os NIFs españois pasan pola ruta local de NIF/CIF.
Severidade
A AEAT distingue tres severidades:
envelope— rexéitase o envío completo (códigos 4xxx, ponos o servizo tras parsear o sobre SOAP).record— só se rexeita o rexistro afectado (códigos 1xxx e 3xxx).admissible— o rexistro acéptase pero márcase para subsanación (códigos 2xxx).
O validador local devolve os dous primeiros como severity: 'rejection' e o terceiro como severity: 'admissible'. Os erros de envelope veñen do nivel de cable e nunca aparecen no resultado local.
Seguinte
- Códigos de erro — catálogo completo de códigos co texto literal en castelán de
errores.properties. - Cadea de pegadas