# 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 |