188 lines
3.4 KiB
Markdown
188 lines
3.4 KiB
Markdown
# VeriFactu Middle API
|
|
|
|
API intermediaria para el protocolo VeriFactu de la AEAT.
|
|
|
|
---
|
|
|
|
## Instalación
|
|
|
|
```bash
|
|
go build .
|
|
```
|
|
|
|
---
|
|
|
|
## Configuración
|
|
|
|
Editar `config.yml`:
|
|
|
|
```yaml
|
|
server:
|
|
port: 6789
|
|
|
|
verifactu:
|
|
production: false # true para producción
|
|
|
|
certificates:
|
|
storage_path: ./data/certs/
|
|
cert_file: ./data/certs/personal.p12
|
|
cert_password: TU_CONTRASEÑA
|
|
|
|
crypto:
|
|
keys_path: ./keys/
|
|
name: "VeriFactu API"
|
|
email: "admin@example.com"
|
|
```
|
|
|
|
Las claves RSA se generan automáticamente en `./keys/` si no existen.
|
|
|
|
---
|
|
|
|
## Autenticación
|
|
|
|
### 1. Obtener clave pública
|
|
|
|
**GET /api/v1/auth/public-key**
|
|
|
|
Devuelve la clave pública RSA para cifrar la contraseña del certificado.
|
|
|
|
### 2. Registrar certificado
|
|
|
|
**POST /api/v1/auth/register**
|
|
|
|
```json
|
|
{
|
|
"cert_name": "mi-certificado",
|
|
"cert_path": "archivo.p12",
|
|
"password_encrypted": "BASE64_RSA_ENCRYPTED_PASSWORD"
|
|
}
|
|
```
|
|
|
|
Respuesta:
|
|
```json
|
|
{
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
|
}
|
|
```
|
|
|
|
### 3. Usar token
|
|
|
|
En todas las peticiones siguientes:
|
|
```
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
---
|
|
|
|
## Estructura de datos
|
|
|
|
### Enviar factura (POST /api/v1/facturas)
|
|
|
|
```json
|
|
{
|
|
"tipo": "alta",
|
|
"factura": {
|
|
"emisor_nif": "A12345678",
|
|
"emisor_nombre": "NOMBRE REGISTRADO EN AEAT",
|
|
"num_serie": "2024-001",
|
|
"fecha_expedicion": "13-09-2024",
|
|
"tipo_factura": "F1",
|
|
"descripcion": "Descripción",
|
|
"destinatario": {
|
|
"nombre": "CLIENTE SL",
|
|
"nif": "B98765432"
|
|
},
|
|
"iva": [
|
|
{"base": 100.00, "cuota": 21.00, "tipo": 21.00}
|
|
],
|
|
"importe_total": 121.00
|
|
},
|
|
"sistema": {
|
|
"nombre": "NOMBRE REGISTRADO EN AEAT PARA EL NIF PROVEEDOR",
|
|
"nif_proveedor": "A12345678",
|
|
"version": "1.0.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Anular factura (POST /api/v1/facturas/anular)
|
|
|
|
```json
|
|
{
|
|
"factura": {
|
|
"emisor_nif": "A12345678",
|
|
"num_serie": "2024-001",
|
|
"fecha_expedicion": "13-09-2024"
|
|
},
|
|
"sistema": {
|
|
"nombre": "Software",
|
|
"nif_proveedor": "A12345678",
|
|
"version": "1.0.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Campos obligatorios
|
|
|
|
| Campo | Tipo | Descripción |
|
|
|-------|------|-------------|
|
|
| `tipo` | string | `alta` o `anulacion` |
|
|
| `factura.emisor_nif` | string | NIF emisor (9 caracteres) |
|
|
| `factura.emisor_nombre` | string | Nombre del emisor exactamente como figura en el censo AEAT |
|
|
| `factura.num_serie` | string | Número de serie |
|
|
| `factura.fecha_expedicion` | string | Fecha (`dd-mm-yyyy`) |
|
|
| `factura.tipo_factura` | string | `F1`, `F2`, `R1`-`R5` |
|
|
| `factura.destinatario` | object | Obligatorio para F1, F3 y rectificativas |
|
|
| `factura.iva[]` | array | Al menos un registro |
|
|
| `factura.importe_total` | number | > 0 |
|
|
| `sistema.nombre` | string | Nombre del proveedor del software exactamente como figura en el censo AEAT para su NIF |
|
|
| `sistema.nif_proveedor` | string | NIF del proveedor del software |
|
|
| `sistema.version` | string | Versión del software |
|
|
|
|
---
|
|
|
|
## Respuestas
|
|
|
|
### Éxito
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"csv": "ABC123...",
|
|
"estado": "Correcto"
|
|
}
|
|
```
|
|
|
|
### Error de validación
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "validation_failed",
|
|
"details": [{"field": "emisor_nif", "message": "invalid NIF format"}]
|
|
}
|
|
```
|
|
|
|
### Error AEAT
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "aeat_error",
|
|
"codigo": "1000",
|
|
"mensaje": "Descripción"
|
|
}
|
|
```
|
|
|
|
Ver `ERRORES.md` para códigos de error completos.
|
|
|
|
---
|
|
|
|
## Límites
|
|
|
|
-Máximo 1.000 registros por solicitud (actualmente 1)
|
|
- Entorno actual: pruebas (sandbox)
|
|
|