109 lines
3.2 KiB
Markdown
109 lines
3.2 KiB
Markdown
|
# VeriFactu - Protocolo AEAT
|
||
|
|
|
||
|
|
## Qué es VeriFactu
|
||
|
|
|
||
|
|
Sistema mandatory de facturación electrónica de la AEAT (Agencia Estatal de Administración Tributaria) de España.
|
||
|
|
|
||
|
|
## Obligatoriedad
|
||
|
|
|
||
|
|
A partir de cierta fecha, todas las facturas emitidas deben registrarse en VeriFactu, independientemente del formato (digital).
|
||
|
|
|
||
|
|
## Operaciones
|
||
|
|
|
||
|
|
### Alta
|
||
|
|
|
||
|
|
Registrar una factura nueva en el sistema.
|
||
|
|
|
||
|
|
**Tipos de factura:**
|
||
|
|
- F1: Factura completa
|
||
|
|
- F2: Factura simplificada (ticket)
|
||
|
|
- R1-R5: Rectificativas
|
||
|
|
|
||
|
|
### Anulación
|
||
|
|
|
||
|
|
Cancelar una factura previamente registrada.
|
||
|
|
|
||
|
|
### Subsanación
|
||
|
|
|
||
|
|
Corregir errores en facturas ya registradas.
|
||
|
|
|
||
|
|
### Consulta
|
||
|
|
|
||
|
|
Buscar facturas previamente enviadas.
|
||
|
|
|
||
|
|
## Encadenamiento de Hash
|
||
|
|
|
||
|
|
Cada factura incluye el hash de la anterior. El formato exacto validado por la AEAT es:
|
||
|
|
|
||
|
|
```
|
||
|
|
SHA256("IDEmisorFactura=NIF&NumSerieFactura=SERIE&FechaExpedicionFactura=dd-mm-yyyy&TipoFactura=F1&CuotaTotal=21.00&ImporteTotal=121.00&Huella=HASH_ANTERIOR&FechaHoraHusoGenRegistro=yyyy-mm-ddThh:mm:ss+hh:mm")
|
||
|
|
```
|
||
|
|
|
||
|
|
Para el primer registro de un emisor, `Huella` se deja vacío y en el XML se envía `<PrimerRegistro>S</PrimerRegistro>`. Para el resto, se envía `<RegistroAnterior>` con los datos de la factura anterior (nunca ambos a la vez).
|
||
|
|
|
||
|
|
## URLs
|
||
|
|
|
||
|
|
### Testing (Preproducción)
|
||
|
|
```
|
||
|
|
https://prewww1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP
|
||
|
|
```
|
||
|
|
|
||
|
|
### Producción
|
||
|
|
```
|
||
|
|
https://www1.agenciatributaria.gob.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP
|
||
|
|
```
|
||
|
|
|
||
|
|
## Formato
|
||
|
|
|
||
|
|
SOAP 1.1 sobre HTTPS con mTLS (certificado cliente cualificado). Namespaces requeridos:
|
||
|
|
|
||
|
|
- `xmlns:sum` → `https://www2.agenciatributaria.gob.es/static_files/common/internet/dep/aplicaciones/es/aeat/tike/cont/ws/SuministroLR.xsd`
|
||
|
|
- `xmlns:sum1` → `https://www2.agenciatributaria.gob.es/static_files/common/internet/dep/aplicaciones/es/aeat/tike/cont/ws/SuministroInformacion.xsd`
|
||
|
|
|
||
|
|
Campos específicos a tener en cuenta:
|
||
|
|
- `TipoHuella`: valor `01` (no `SHA-256`)
|
||
|
|
- `FechaHoraHusoGenRegistro`: formato ISO 8601 con huso horario (`yyyy-mm-ddThh:mm:ss+hh:mm`)
|
||
|
|
- `IdSistemaInformatico`: 2 caracteres (`01`, no `1`)
|
||
|
|
- `Encadenamiento`: usa `xs:choice` — o `PrimerRegistro` o `RegistroAnterior`, nunca los dos
|
||
|
|
|
||
|
|
## CSV
|
||
|
|
|
||
|
|
Código de Verificación asignado por la AEAT con formato `A-XXXXXXXXXXXXX`. Acredita el registro de la factura en Hacienda. Cuando la API opera en modo fallback local devuelve el hash SHA-256 en su lugar y el estado indica `Correcto (local)`.
|
||
|
|
|
||
|
|
## Fallback Local
|
||
|
|
|
||
|
|
Cuando AEAT no está disponible (error de red, servidor caído, etc), la API guarda la factura localmente:
|
||
|
|
- Genera el hash localmente
|
||
|
|
- Guarda en `./data/` (hash storage)
|
||
|
|
- Devuelve el hash como CSV temporal
|
||
|
|
- Estado: "Correcto (local)"
|
||
|
|
|
||
|
|
Esto permite seguir operando sin conexión a AEAT.
|
||
|
|
|
||
|
|
## Certificado Cliente
|
||
|
|
|
||
|
|
La AEAT requiere certificado cliente para aceptar requests (mTLS):
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
certificates:
|
||
|
|
storage_path: ./data/certs/
|
||
|
|
cert_file: ./data/certs/personal.p12
|
||
|
|
cert_password: tu_contraseña
|
||
|
|
```
|
||
|
|
|
||
|
|
Sin certificado válido, la API cae en fallback local.
|
||
|
|
|
||
|
|
## Datos Obligatorios
|
||
|
|
|
||
|
|
- NIF del emisor
|
||
|
|
- Número de serie
|
||
|
|
- Fecha de expedición
|
||
|
|
- Tipo de factura
|
||
|
|
- Base imponible IVA
|
||
|
|
- Cuota IVA
|
||
|
|
- Importe total
|
||
|
|
|
||
|
|
## Límites
|
||
|
|
|
||
|
|
- Máximo 1000 facturas por request
|
||
|
|
- Rate limit: consultar documentación AEAT
|