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. El certificado se envía como base64 en el body (no como ruta de fichero).

Request:

{
  "cert_name": "mi-certificado",
  "cert_file": "BASE64_CONTENT_OF_P12_FILE",
  "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
  }
}

---

Formatos Disponibles

GET /api/v1/formats

Lista los formatos de entrada soportados. La API detecta automáticamente el formato del JSON recibido.

Response:

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

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

{
  "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 para detalles de cada formato y cómo añadir nuevos.

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