205 lines
3.7 KiB
Markdown
205 lines
3.7 KiB
Markdown
# API Reference
|
|
|
|
## Endpoints
|
|
|
|
### Health
|
|
```
|
|
GET /api/v1/health
|
|
```
|
|
Verifica que la API está funcionando.
|
|
|
|
**Response:**
|
|
```json
|
|
{"status": "ok"}
|
|
```
|
|
|
|
---
|
|
|
|
### Obtener Clave Pública
|
|
```
|
|
GET /api/v1/auth/public-key
|
|
```
|
|
Obtiene la clave pública RSA para cifrar contraseñas.
|
|
|
|
**Response:**
|
|
```json
|
|
{"public_key": "base64_encoded_key"}
|
|
```
|
|
|
|
---
|
|
|
|
### Registrar Certificado
|
|
```
|
|
POST /api/v1/auth/register
|
|
```
|
|
Registra y valida un certificado digital.
|
|
|
|
**Request:**
|
|
```json
|
|
{
|
|
"cert_name": "mi_certificado",
|
|
"cert_path": "C:/ruta/al/certificado.p12",
|
|
"password_encrypted": "base64_encoded_password"
|
|
}
|
|
```
|
|
|
|
**Response (éxito):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"cert": {
|
|
"subject": "...",
|
|
"issuer": "...",
|
|
"expired": false,
|
|
"expiring_soon": false,
|
|
"days_until_expiry": 365
|
|
},
|
|
"token": "A1B2C3D4..."
|
|
}
|
|
```
|
|
|
|
**Response (error):**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "certificate_expired",
|
|
"cert": {
|
|
"subject": "...",
|
|
"issuer": "...",
|
|
"expired": true
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Formatos Disponibles
|
|
```
|
|
GET /api/v1/formats
|
|
```
|
|
Lista los formatos de entrada soportados. La API detecta automáticamente el formato del JSON recibido.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"formats": ["dolibarr", "native"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Alta de Factura
|
|
```
|
|
POST /api/v1/facturas
|
|
```
|
|
Registra una factura en VeriFactu. El formato de entrada se detecta automáticamente (no requiere parámetro).
|
|
|
|
**Formato nativo (por defecto):**
|
|
```json
|
|
{
|
|
"tipo": "alta",
|
|
"factura": {
|
|
"emisor_nif": "53950250R",
|
|
"emisor_nombre": "EMPRESA EJEMPLO SL",
|
|
"num_serie": "FV2026/001",
|
|
"fecha_expedicion": "17-04-2026",
|
|
"tipo_factura": "F1",
|
|
"descripcion": "Factura de prueba",
|
|
"destinatario": {
|
|
"nombre": "CLIENTE SL",
|
|
"nif": "B98765432"
|
|
},
|
|
"iva": [
|
|
{"base": 100.00, "cuota": 21.00, "tipo": 21.0}
|
|
],
|
|
"importe_total": 121.00
|
|
},
|
|
"sistema": {
|
|
"nombre": "Mi Sistema",
|
|
"nif_proveedor": "53950250R",
|
|
"version": "1.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Formato Dolibarr BFF:**
|
|
```json
|
|
{
|
|
"invoice": {
|
|
"number": "FA2024/001",
|
|
"date": "2024-09-13T00:00:00Z",
|
|
"notePublic": "Factura de prueba",
|
|
"lines": [
|
|
{"description": "Servicio", "quantity": 1, "unitPrice": 100, "taxRate": 21}
|
|
]
|
|
},
|
|
"client": {
|
|
"name": "CLIENTE SL",
|
|
"vatNumber": "B98765432"
|
|
},
|
|
"emisor": {
|
|
"nif": "53950250R",
|
|
"nombre": "EMPRESA EJEMPLO SL"
|
|
},
|
|
"sistema": {
|
|
"nombre": "Mi Sistema",
|
|
"nif_proveedor": "53950250R",
|
|
"version": "1.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
Ver [formatos.md](formatos.md) para detalles de cada formato y cómo añadir nuevos.
|
|
|
|
**Response (AEAT disponible):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"csv": "CSV1234567ABC",
|
|
"estado": "Correcto"
|
|
}
|
|
```
|
|
|
|
**Response (fallback local):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"csv": "0CE5F940CEA...",
|
|
"estado": "Correcto (local)"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Anular Factura
|
|
```
|
|
POST /api/v1/facturas/anular
|
|
```
|
|
Anula una factura previamente registrada.
|
|
|
|
**Request:**
|
|
```json
|
|
{
|
|
"tipo": "anulacion",
|
|
"factura": {
|
|
"emisor_nif": "53950250R",
|
|
"num_serie": "FV2026/001",
|
|
"fecha_expedicion": "17-04-2026"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Códigos de Error
|
|
|
|
| Código | Descripción |
|
|
|--------|------------|
|
|
| `certificate_expired` | El certificado ha expirado |
|
|
| `certificate_not_yet_valid` | El certificado aún no es válido |
|
|
| `certificate_expiring_soon` | El certificado caduca en menos de 30 días |
|
|
| `invalid_password_or_format` | Contraseña incorrecta o formato inválido |
|
|
| `file_not_found` | El archivo de certificado no existe |
|
|
| `validation_failed` | Los datos de la factura no son válidos |
|
|
| `aeat_error` | Error comunicando con la AEAT |
|
|
| `aeat_fault` | Error SOAP de la AEAT |
|
|
| `hash_save_error` | Error guardando el hash local |
|
|
| `hash_storage_error` | Error leyendo el hash anterior | |