# 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 certain fecha, todas las facturasemitidas deben registrarse en VeriFactu, independientemente del formato (紙 o 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