Validacions
El SDK aplica localment totes les validacions llistades a Validaciones y errores del servicio v1.2.2. Això et permet caçar registres mal formats abans de gastar una crida SOAP — l'AEAT retornaria el mateix diagnòstic, però en microsegons.
Cridar el validador
import {
validateInvoiceForRegister,
validateInvoiceForCancel,
} from 'verifactu-sdk/validators';
const issues = validateInvoiceForRegister(invoice);
if (issues.some((i) => i.severity === 'rejection')) {
throw new BusinessValidationError('Factura rebutjada', { code: issues[0]!.code });
}Cada ValidationResult retornat porta:
code— el codi d'error de l'AEAT més proper del catàleg.field— ruta amb punts del camp en conflicte (p. ex.breakdown.0.taxRate).severity—'rejection'rebutja el registre,'admissible'l'accepta amb advertència.message— descripció curta en anglès de la incidència.
VerifactuClient.registerInvoice executa el validador automàticament i llança BusinessValidationError en cas de rebuig; només crides el validador directament quan vols inspeccionar totes les incidències alhora.
Les 23 regles
El validador implementa una o més comprovacions per regla de l'AEAT. La correspondència és:
| Regla | Grup de camps | Què comprova | Severitat |
|---|---|---|---|
| 1 | IDFactura | Format del NIF, caràcters permesos a NumSerieFactura, FechaExpedicion ≥ 28-10-2024 i ±20 anys respecte a avui. | Rebuig |
| 2 | RechazoPrevio + Subsanacion | Només combinacions coherents (N, S, X). | Rebuig |
| 3 | TipoRectificativa | Obligatòria només si TipoFactura comença per R. | Rebuig |
| 4 | FacturasRectificadas | Només permesa en factures tipus R. | Rebuig |
| 5 | FacturasSustituidas | Només permesa en factures F3. | Rebuig |
| 6 | ImporteRectificacion | Obligatori quan TipoRectificativa = S. | Rebuig |
| 7 | FechaOperacion | ±20 anys respecte a la data d'expedició, regles especials per a ClaveRegimen 14/15. | Rebuig |
| 8 | FacturaSimplificadaArt7273 | Només a F1/F3/R1/R2/R3/R4. | Rebuig |
| 9 | FacturaSinIdentifDestinatarioArt61d | Només a F2/R5. | Rebuig |
| 10 | Macrodato | Obligatori si ImporteTotal ≥ 100 000 000 €. | Rebuig |
| 11 | EmitidaPorTerceroODestinatario | Coherència amb Tercero / Destinatarios. | Rebuig |
| 12 | Tercero | Format NIF, diferent de l'emissor, estructura NIF-IVA per país. | Rebuig |
| 13 | Destinatarios | Obligatoris per a F1/F3/R1/R2/R3/R4; prohibits per a F2/R5; format NIF; estructura NIF-IVA. | Rebuig |
| 14 | Cupon | Només permès quan TipoFactura és R1 o R5. | Rebuig |
| 15.1 | Desglose.TipoImpositivo | Tipus permès per data (segons taula històrica de l'AEAT). | Rebuig |
| 15.2 | BaseImponibleACoste | Només quan ClaveRegimen = 06 o Impuesto a 02/05. | Rebuig |
| 15.3 | TipoRecargoEquivalencia | Parella vàlida amb TipoImpositivo (21/5.2, 10/1.4, …). | Rebuig |
| 15.4 | CalificacionOperacion | S1/S2/N1/N2; mútuament excloent amb OperacionExenta. | Rebuig |
| 15.5 | OperacionExenta | E1-E6 (IVA); E7/E8 només per a IGIC; coherència amb TipoFactura. | Rebuig |
| 15.6 | ClaveRegimen | 01-21 amb sub-regles per a 02/03/04/06/07/08/10/11/14/20/21. | Rebuig |
| 15.7 | CuotaRepercutida | base × tipus amb tolerància ±10 € (≤ 3 000 € per a simplificades). | Rebuig |
| 16 | CuotaTotal | Suma de quotes repercutides amb tolerància ±10 €. | Rebuig |
| 17 | ImporteTotal | Suma de bases + impost + recàrrec amb tolerància ±10 €. | Rebuig |
| 18 | Huella anterior | 64 caràcters hex en majúscules quan és present. | Admissible (2003) |
| 19 | SistemaInformatico | SystemId 2 caràcters [A-Z0-9] excloent Ñ; coherència TipoUsoPosibleSoloVerifactu / MultiOT. | Rebuig |
| 20 | FechaHoraHusoGenRegistro | ISO 8601 vàlid amb offset; no en futur llunyà. | Rebuig / Admissible |
| 21 | NumRegistroAcuerdoFacturacion | ≤ 15 caràcters, joc de caràcters permès. | Rebuig |
| 22 | IdAcuerdoSistemaInformatico | ≤ 16 caràcters, joc de caràcters permès. | Rebuig |
| 23 | Huella | 64 caràcters hex en majúscules. | Admissible (1292) |
NIF, NIE, CIF
El validador local cobreix les tres formes d'identificador espanyol i el dígit de control:
- DNI: 8 dígits + lletra de control calculada per la taula mod-23.
- NIE: prefix
X|Y|Z+ 7 dígits + lletra de control, mateixa taula. - CIF: lletra + 7 dígits + dígit/lletra de control (algorisme mixt mod-10 / mod-11 segons l'especificació AEAT).
NIF-IVA (UE)
El validador cobreix els 28 estats membres històrics de la UE més Irlanda del Nord (GB/XI) amb gestió Brexit conscient de dates. Les estructures i les regles per país es carreguen de validators/nifIva.ts. Exemples:
| País | Codi | Estructura |
|---|---|---|
| Alemanya | DE | 9 dígits |
| França | FR | 11 caràcters (2 alfanumèrics + 9 dígits) |
| Itàlia | IT | 11 dígits |
| Portugal | PT | 9 dígits |
| Països Baixos | NL | 12 caràcters |
| Regne Unit | GB | 9 / 12 dígits; vàlid només ≤ 31-12-2020 (post-Brexit, usar XI) |
| Irlanda del Nord | XI | 9 / 12 dígits; vàlid només ≥ 01-01-2021 |
El validador accepta country=ES per completesa, però els NIFs espanyols passen per la ruta local de NIF/CIF.
Severitat
L'AEAT distingeix tres severitats:
envelope— es rebutja l'enviament complet (codis 4xxx, els posa el servei després de parsejar el sobre SOAP).record— només es rebutja el registre afectat (codis 1xxx i 3xxx).admissible— el registre s'accepta però es marca per a subsanación (codis 2xxx).
El validador local retorna els dos primers com severity: 'rejection' i el tercer com severity: 'admissible'. Els errors d'envelope vénen del nivell de cable i mai no apareixen al resultat local.
Següent
- Codis d'error — catàleg complet de codis amb el text literal en castellà d'
errores.properties. - Cadena d'empremtes