Integración de VeriFactu con sistemas antiguos: Cliente .exe

Si tu ERP, TPV o software de facturación está desarrollado en un lenguaje o entorno que no puede llamar directamente a una API REST, el cliente EXE de VeriFactuAPI es tu solución. Se trata de un ejecutable de línea de comandos que actúa como puente entre tu sistema y la API: tu software llama al .exe con unos parámetros, y el ejecutable se encarga de comunicarse con VeriFactuAPI y devolverte la respuesta.

No necesitas modificar tu stack tecnológico, instalar librerías ni gestionar certificados. Si tu sistema puede ejecutar un programa externo y leer su salida, puedes cumplir con la normativa VeriFactu sin tocar tu código.

Requisitos

• Windows (cualquier versión moderna de 64 bits)
• Capacidad de ejecutar procesos externos desde tu software y leer su salida (stdout)
• Credenciales de emisor activas en verifactuapi.es — Usuario Emisor y API Key Emisor, gestionados desde el panel web

Instalación

No requiere instalación. Copia el fichero VerifactuINVOCASH.exe en la carpeta que prefieras de tu servidor o equipo y asegúrate de que el proceso de tu software tiene permisos de ejecución sobre esa ruta.

Credenciales necesarias

Antes de realizar cualquier llamada necesitas dos credenciales asociadas al NIF emisor, que obtienes desde el panel web de VeriFactuAPI:

• Usuario Emisor — identifica al emisor dentro de la plataforma.
• API Key Emisor — clave de autenticación para ese emisor.

Ambas credenciales van siempre como los dos primeros parámetros en todas las llamadas al ejecutable, independientemente de la acción que se realice.

Sintaxis general

VerifactuINVOCASH.exe <usuario> <apikey> <accion> <parametro>

La respuesta del servidor se devuelve siempre por stdout, independientemente de la acción ejecutada. Puedes capturarla desde tu software para procesarla o registrarla en un log.

Flujo completo: alta, consulta y anulación

Acción alta — Registrar una factura

El cuarto parámetro es la ruta al fichero JSON que contiene los datos de la factura. Puedes indicarla de tres formas:

• Solo el nombre del fichero — el ejecutable lo buscará en su misma carpeta.
• Ruta relativa — se resuelve desde la carpeta donde está el .exe.
• Ruta absoluta — se usa exactamente la ruta indicada.

Llamada

VerifactuINVOCASH.exe usuario@ejemplo.com APIKEY123 alta factura.json

VerifactuINVOCASH.exe usuario@ejemplo.com APIKEY123 alta C:\facturas\FAC_2025_0001.json

Fichero JSON de entrada

Crea un fichero .json con los datos de la factura. El ejemplo siguiente corresponde al caso más habitual: una factura ordinaria (F1) con IVA al 21%.

{
  "IDEmisorFactura":        "A39200019",
  "NumSerieFactura":        "FAC/2025/0001",
  "FechaExpedicionFactura": "2025-04-22",
  "TipoFactura":            "F1",
  "DescripcionOperacion":   "Servicios de desarrollo web - Abril 2025",
  "EmitidaPorTercODesti":   null,
  "Destinatarios": [
    {
      "NombreRazon": "Cliente Ejemplo S.A.",
      "NIF":         "39707287H"
    }
  ],
  "Desglose": [
    {
      "Impuesto":                      1,
      "ClaveRegimen":                  1,
      "CalificacionOperacion":         1,
      "TipoImpositivo":                21,
      "BaseImponibleOImporteNoSujeto": 1000,
      "CuotaRepercutida":              210
    }
  ],
  "CuotaTotal":   210,
  "ImporteTotal": 1210
}

Ficheros de salida generados

Si el alta es satisfactoria, el ejecutable genera automáticamente dos ficheros en la misma carpeta que el JSON de entrada, con el mismo nombre base:

Salida por stdout

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1042,
        "estado_aeat": "No Registrado",
        "qr_image": "...",
        "url_qr": "https://..."
      }
    ]
  }
}

Acción consulta — Consultar el estado en la AEAT

El cuarto parámetro es el id del registro obtenido en la respuesta del alta.

El envío a la AEAT es asíncrono: la factura se registra inmediatamente en la plataforma con estado "No Registrado" y se envía en el siguiente ciclo de proceso. Usa esta acción para comprobar si la AEAT ya ha procesado la factura.

Llamada

VerifactuINVOCASH.exe usuario@ejemplo.com APIKEY123 consulta 1042

Salida por stdout

{
  "success": true,
  "data": {
    "items": {
      "estado_aeat":            "Correcto",
      "codigo_error_aeat":      "",
      "descripcion_error_aeat": ""
    }
  }
}

Los valores posibles de estado_aeat son:

Acción anulacion — Anular un registro de facturación

El cuarto parámetro es el id del registro de alta que se desea anular.

Llamada

VerifactuINVOCASH.exe usuario@ejemplo.com APIKEY123 anulacion 1042

Salida por stdout

{
  "success": true,
  "message": "Registro anulado correctamente",
  "code": 200
}

Integración con tu sistema

El .exe está diseñado para encajar en cualquier software que pueda lanzar procesos externos. El patrón habitual de integración es:

1. Tu software genera el fichero JSON con los datos de la factura.
2. Lanza el .exe con la acción alta y la ruta al fichero.
3. Lee stdout o el fichero _out.json generado para obtener el id del registro.
4. Guarda ese id en tu base de datos asociado a la factura.
5. Cuando necesites verificar el estado, lanza el .exe con la acción consulta y el id.

Formatos de respuesta JSON

La salida por stdout sigue la misma estructura JSON que el resto de la API de VeriFactuAPI en todos sus endpoints.

Respuesta de éxito

{
  "success": true,
  "message": "Operación realizada correctamente",
  "code": 200
}

Respuesta de error

{
  "success": false,
  "message": "El campo IDEmisorFactura es obligatorio.",
  "error": "VALIDATION_ERROR",
  "code": 400
}

Cuando success es false, revisa el campo message para identificar el problema. Los errores más habituales son credenciales incorrectas, campos obligatorios ausentes en el JSON de entrada o un id de registro inexistente en las acciones de consulta y anulación.

Próximos pasos

• Consulta la referencia completa de la API para conocer todos los campos disponibles en el JSON de alta (facturas rectificativas, regímenes especiales, etc.)
• Revisa las listas de valores (/api/listas) para conocer todos los códigos válidos de TipoFactura, Impuesto, ClaveRegimen y CalificacionOperacion

¿Listo para probarlo?

Crea tu cuenta gratuita y emite tu primera factura verificada en menos de 10 minutos. El entorno de pruebas está completamente habilitado desde el primer día: sin tarjeta, sin límites artificiales, con la misma API que usarás en producción.