VerifactuMidAPI/documentacion/api.md

API Reference

Endpoints

Health

GET /api/v1/health

Verifica que la API está funcionando.

Response:

{"status": "ok"}

---

Obtener Clave Pública

GET /api/v1/auth/public-key

Obtiene la clave pública RSA para cifrar contraseñas.

Response:

{"public_key": "base64_encoded_key"}

---

Registrar Certificado

POST /api/v1/auth/register

Registra y valida un certificado digital.

Request:

{
  "cert_name": "mi_certificado",
  "cert_path": "C:/ruta/al/certificado.p12",
  "password_encrypted": "base64_encoded_password"
}

Response (éxito):

{
  "success": true,
  "cert": {
    "subject": "...",
    "issuer": "...",
    "expired": false,
    "expiring_soon": false,
    "days_until_expiry": 365
  },
  "token": "A1B2C3D4..."
}

Response (error):

{
  "success": false,
  "error": "certificate_expired",
  "cert": {
    "subject": "...",
    "issuer": "...",
    "expired": true
  }
}

---

Alta de Factura

POST /api/v1/facturas

Registra una factura en VeriFactu. No requiere token (el certificado se selecciona internamente o usa el primero disponible).

Request:

{
  "tipo": "alta",
  "factura": {
    "emisor_nif": "53950250R",
    "num_serie": "FV2026/001",
    "fecha_expedicion": "17-04-2026",
    "tipo_factura": "F1",
    "descripcion": "Factura de prueba",
    "IVA": [
      {"base": 100.00, "cuota": 21.00, "tipo": 21.0}
    ],
    "importe_total": 121.00
  },
  "sistema": {
    "nombre": "Mi Sistema",
    "nif_proveedor": "53950250R",
    "version": "1.0"
  }
}

Response (AEAT disponible):

{
  "success": true,
  "csv": "CSV1234567ABC",
  "estado": "Correcto"
}

Response (fallback local):

{
  "success": true,
  "csv": "0CE5F940CEA...",
  "estado": "Correcto (local)"
}

---

Anular Factura

POST /api/v1/facturas/anular

Anula una factura previamente registrada.

Request:

{
  "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