Verifactu. Nueva API instalable como servicio con SDK para Delphi

[[birmain]]

Hola a todos!

Sabemos bien que adaptar nuestros ERPs y sistemas de facturación en Delphi para cumplir con normativas como Verifactu puede convertirse en una pesadilla técnica. Luchar con las firmas digitales (XML-DSig), el manejo de los certificados .p12 y las conexiones directas con los servidores de la Agencia Tributaria quita muchísimo tiempo de desarrollo.

Por eso quiero compartir con la comunidad la v1.0.1 oficial del Motor Verifactu SystemsFGH para Windows.

Básicamente, son un conjunto de servicios que se encargan de forma asíncrona de recibir la informacion, almacenarla y enviarla a la AEAT, sin preocuparse de latencias, cortes de internet. Todo gestionado desde un panel de control donde se monitoriza toda la actividad, realizar informes, y obtener todo tipo de datos como apéndice a tu aplicación que solo tiene que limitarse a implementar una API sencillisima, para la que se adjuntan unos SDK para Delphi 7 y 10 que lo dan todo practicamente hecho. El panel administrativo contiene una amplia documentación y los SDK para los distintos lenguajes

¿Qué hace el Motor? En tu código Delphi tú solo te preocupas de lo de siempre: generar la factura. Le pasas los datos básicos al motor y él se encarga de:

Ensamblar el XML oficial con la estructura exigida por la Agencia Tributaria.
Firmar digitalmente el documento usando el certificado del cliente.
Gestionar la conexión y el envío automático a Hacienda
Devolverte la respuesta oficial con el codigo QR incluido ensamblado en base64


Descargas y Pruebas: Hemos colgado el ejecutable directamente en GitHub para que lo descarguéis a máxima velocidad: 👉 Descargar Instalador (GitHub Releases)
. También en la web oficial.


Nota de Seguridad: Al ser un binario muy nuevo, es normal que Chrome o el SmartScreen de Windows salte con un aviso preventivo la primera vez. Os animo a analizar el .exe con Windows Defender antes de instalarlo si queréis echarle un ojo con total tranquilidad.

Estaremos leyendo este hilo por si alguno se anima a integrarlo en sus proyectos Delphi y tiene cualquier duda o sugerencia técnica. ¡Toda crítica constructiva es más que bienvenida!

Un saludo compañeros.

[Carlos]

Hola,

Lo de "Devolverte la respuesta oficial con el codigo QR incluido ensamblado en base64" no lo entiendo.

Tanto si tienes conexión a internet como si no la factura debe llevar el QR, es algo que no tiene que ver con el XML ni con el envío.

Se emite factura y está lleva si o si el QR.

Además, la respuesta 'oficial' yo prefiero conservarla tal como llega, y ésta no lleva nada del QR.

[[birmain]]

El código QR se origina a través de una url a la AEAT que efectivamente no tiene que ver en absoluto con que haya sido enviada/aceptada o no. No obstante solo es contrastable con exito si la factura ya está en posesion de la AEAT. Por ejemplo: https://prewww2.aeat.es/wlpl/TIKE-CO...importe=505.13, esta url a la web de pruebas es completamente valida estructuralmente y tambien como prueba de que la operación ha sido aceptada, de lo contrario daría un mensaje distinto. Con esta url se puede crear un codigo QR que con su simple captación nos lleva exactamente al mismo lugar que la URL. El codigo QR puede ser un archivo .png o puede estar en base64. No obstante el API para cada operación tambien entrega la URL por si el programador que lo está utilizando quiere crear el codigo QR por sus medios.

Tanto si tienes conexión a internet como si no la factura debe llevar el QR, es algo que no tiene que ver con el XML ni con el envío.
Nada te impide crear el QR tu mismo sin haber obtenido ninguna respuesta, pero entiendo que el QR tiene validez contrastable solo si la operación es aceptada, de modo que captar el QR un segundo despues de haber enviado la operación y haber obtenido la respuesta no es mala práctica.

[Carlos]

Empezado por birmain

El código QR se origina a través de una url a la AEAT que efectivamente no tiene que ver en absoluto con que haya sido enviada/aceptada o no. No obstante solo es contrastable con exito si la factura ya está en posesion de la AEAT. Por ejemplo: https://prewww2.aeat.es/wlpl/TIKE-CO...importe=505.13, esta url a la web de pruebas es completamente valida estructuralmente y tambien como prueba de que la operación ha sido aceptada, de lo contrario daría un mensaje distinto. Con esta url se puede crear un codigo QR que con su simple captación nos lleva exactamente al mismo lugar que la URL. El codigo QR puede ser un archivo .png o puede estar en base64. No obstante el API para cada operación tambien entrega la URL por si el programador que lo está utilizando quiere crear el codigo QR por sus medios.

Tanto si tienes conexión a internet como si no la factura debe llevar el QR, es algo que no tiene que ver con el XML ni con el envío.
Nada te impide crear el QR tu mismo sin haber obtenido ninguna respuesta, pero entiendo que el QR tiene validez contrastable solo si la operación es aceptada, de modo que captar el QR un segundo despues de haber enviado la operación y haber obtenido la respuesta no es mala práctica.

Lo de la validez del QR... pues los que están en modo 'No Veri*factu' no envían sus registros de facturación, por tanto sus QR no son contrastables... pero creo que tienen validez. De hecho si alguien escanea estos QR, Hacienda nos dirá que no existen pero se guardará su información.

[[birmain]]

API REST para VeriFactu: SDK y ejemplos para Delphi (7 y 10)

Hola a todos,

Quería compartir con la comunidad una herramienta que hemos estado desarrollando para facilitar el dolor de cabeza que supone la integración con el sistema VeriFactu de la AEAT.

Se trata de un microservicio/API REST diseñado para abstraer toda la complejidad del formato, el encadenamiento criptográfico (SHA-256) y el envío a Hacienda, permitiendo que cualquier aplicación (ERP, TPV, etc.) pueda integrarse de forma muy sencilla enviando simples peticiones JSON.

Como sabemos que en el mundo Delphi, especialmente en versiones más antiguas como Delphi 7, lidiar con las últimas normativas criptográficas o las conexiones TLS 1.2/1.3 puede requerir componentes de terceros o generar muchos problemas, hemos preparado un SDK integrado específico para Delphi.

Hemos subido a GitHub toda la documentación y ejemplos funcionales tanto para Delphi 7 (muy útil para software legacy) como para Delphi 10.

Repositorio oficial (Información, guías y demos):
https://github.com/SystemsFGH/API-Verifactu-SystemsFGH

Descarga directa de los SDK para Delphi 7 y 10:
Descargar Delphi.DSK.zip

¿Qué ventajas aporta utilizar la API desde Delphi?

• Olvídate de la generación de huellas y la firma XML; el microservicio hace el encadenamiento automático de registros.
• Envío transparente al entorno de la AEAT gestionando las respuestas.
• Los ejemplos utilizan llamadas HTTP nativas y estándar, por lo que adaptarlo a tu código es trivial.
• Permite cumplir con la normativa a los programas hechos en Delphi 7 sin necesidad de actualizar la versión del IDE o reescribir toda la aplicación.

Para que veáis que no exageramos cuando decimos que es fácil de implementar, os dejo aquí el código literal que viene en nuestro SDK de ejemplo demostrando el alta y confirmación completo en una docena de líneas:

Ejemplos de la Guía de Integración:

{ ==============================================================================
  SECCIÓN: EJEMPLOS DE LA GUÍA DE INTEGRACIÓN
  ==============================================================================
  Los siguientes métodos se corresponden fielmente con los ejemplos de código
  documentados en la "Guía de Integración VeriFactu para Delphi 7".
  Están aquí para demostrar que el código de la documentación es funcional y compilable.
  ============================================================================== }

{ ------------------------------------------------------------------------------
  7. Ejemplo de Integración: Alta Síncrona (Todo en Uno)
  ------------------------------------------------------------------------------ }
procedure TFrmMainVF.EmitirAltaSincrona_DemoDoc;
var
  Cfg: TVfDemoConfig;
  Engine: TVFEngine;
  Res: TVFIngestaAckResult;
  MiJson: string;
begin
  // 1. Configurar
  // Cfg.ApiBaseUrl := 'http://localhost:8000';
  // Cfg.TimeoutMs := 60000;
  
  // Adaptado para la Demo: Tomamos valores de la UI
  Cfg.ApiBaseUrl := Trim(edBaseUrl.Text);
  Cfg.Token := Trim(edToken.Text);
  Cfg.NifEmisor := Trim(edNif.Text);
  Cfg.TimeoutMs := StrToIntDef(edTimeoutMs.Text, 60000);

  Engine := TVFEngine.Create(Cfg);
  try
    // MiJson := '{ ... datos factura ... }';
    MiJson := MemoJson.Lines.Text;

    if Trim(MiJson) = '' then
    begin
       Log('DemoDoc: JSON vacío');
       Exit;
    end;

    // 2. Ejecutar Ciclo Completo (Ingesta -> Polling -> ACK)
    Res := Engine.IngestaYConfirmacion(MiJson, Cfg.TimeoutMs, 200, 50, True);

    if Res.Timeout then
      Log('Factura enviada al Backend, pero la AEAT tarda en responder. Consulte "Pendientes" más tarde.')
    else if Res.AckHecho then
    begin
      // 3. Éxito: Guardar Huella y QR en base de datos local
      // GuardarEnBD(Res.Pendiente.Huella, Res.Pendiente.UrlQrVerifactu);

      // PRO: Podemos imprimir el ticket con QR AHORA MISMO
      // ImprimirTicket(Res.Pendiente.UrlQrVerifactu);
      
      Log('DemoDoc: Éxito Síncrono. Huella: ' + Res.Pendiente.Huella);
      
      // Mostrar QR usando utilidades de la demo
      ShowQrFromFields(Res.Pendiente.QrVerifactu, Res.Pendiente.UrlQrVerifactu);
    end
    else
      Log('Error AEAT: ' + Res.ErrorMsg);

  finally
    Engine.Free;
  end;
end;


{ ------------------------------------------------------------------------------
  8.1. Ingesta Asíncrona (Solo Envío)
  ------------------------------------------------------------------------------ }
procedure TFrmMainVF.EnviarFacturaAsync_DemoDoc;
var
  IngestaResp: TVFIngestaResponse;
  Cfg: TVfDemoConfig;
  Engine: TVFEngine;
  MiJson: string;
begin
  // Configuración desde UI
  Cfg.ApiBaseUrl := Trim(edBaseUrl.Text);
  Cfg.Token := Trim(edToken.Text);
  Cfg.NifEmisor := Trim(edNif.Text);
  
  Engine := TVFEngine.Create(Cfg);
  try
      MiJson := MemoJson.Lines.Text;

      // Solo enviamos al Backend, reciben OK (guardado) y nos vamos.
      IngestaResp := Engine.IngestaFromJson(MiJson);

      if IngestaResp.Ok then
        Log('Factura encolada. ID: ' + IngestaResp.Id)
      else
        Log('Error al encolar: ' + IngestaResp.ErrorMsg);
  finally
    Engine.Free;
  end;
end;


{ ------------------------------------------------------------------------------
  8.2. Recuperación de Pendientes (Polling de Confirmaciones)
  ------------------------------------------------------------------------------ }
procedure TFrmMainVF.ProcesarColaPendientes_DemoDoc;
var
  Cfg: TVfDemoConfig;
  Engine: TVFEngine;
  Pend: TVFPendientesResponse;
  // Ack: TVFAckResponse;
  I: Integer;
  Item: TVFPendienteItem;
begin
  // Configuración desde UI
  Cfg.ApiBaseUrl := Trim(edBaseUrl.Text);
  Cfg.Token := Trim(edToken.Text);
  Cfg.NifEmisor := Trim(edNif.Text);

  Engine := TVFEngine.Create(Cfg);
  try
    // 2. Recuperar las ultimas 50 facturas pendientes de ACK
    Pend := Engine.GetPendientes(50);

    if not Pend.Ok then Exit;

    for I := 0 to Length(Pend.Items) - 1 do
    begin
      Item := Pend.Items[i];

      // Status 0..3: Respuestas Finales de la AEAT
      if (Item.Status >= 0) and (Item.Status <= 3) then
      begin
         try
            // A. Procesar respuesta en el ERP
            // MiBD.ActualizarEstado(Item.IdEnvio, Item.Status, ...);
            Log('DemoDoc: Procesando Item Pendiente ID=' + IntToStr(Item.IdEnvio) + ' Status=' + IntToStr(Item.Status));

            // B. Confirmar recepción (ACK)
            Engine.AckIndice(Item.IndiceLog);

         except
            // Si falla mi BD local, NO hago ACK para que vuelva a salir luego
            Log('Error guardando en BD local, reintentaremos luego.');
         end;
      end;
    end;

  finally
    Engine.Free;
  end;
end;

Espero que a más de uno le sirva para ahorrar decenas de horas de investigación, pruebas y lectura de manuales técnicos de la agencia tributaria.

Cualquier feedback, sugerencia, pull request o duda es bienvenida por este hilo.

¡Un saludo !

[Casimiro Noteví]

[[birmain]]

¡Hola a todos de nuevo!

Creo que algunos ya habeis mirado el servicio que he creado para simplificar la integración de VeriFactu y lidiar con los envíos a la AEAT desde componentes legacy de Delphi. Hoy no vengo a hablar del Micro Server en sí, sino de una **novedad importante a nivel de documentación técnica**.

Sabemos que uno de los mayores dolores de cabeza para los desarrolladores cuando integramos pasarelas empresariales/gubernamentales sonde a veces hay documentaciones pobres, muros horribles de texto y falta de ejemplos reales en nuestro lenguaje.

Dándole una vuelta de tuerca a eso, **hemos reestructurado radicalmente cómo documentamos nuestros SDKs**. En vez de PDFs estáticos corporativos, hemos publicado una nueva remesa de guías técnicas diseñadas para copiar, pegar y entender de un vistazo: con el código fuente desplegable nativo en Pascal y demostraciones visuales.

Os dejo aquí los enlaces directos a las nuevas documentaciones para nuestro lenguaje:

👉 SDK de integración estructurado para Delphi 7:
https://www.systemsfgh.com/documentation/sdk_delphi7.md

👉 SDK de integración estructurado para Delphi 10 (y superiores):
https://www.systemsfgh.com/documenta...dk_delphi10.md

Para ilustrar esta nueva filosofía de "cero cajas negras", hemos montado unas demostraciones de arquitectura limpias grabadas directamente desde la IDE de Delphi. En dichos vídeos se aprecia la pantalla dividida: a un lado nuestro panel web que administra el servicio, y al otro las aplicaciones de Delphi enviando lotes masivos y asíncronos para comprobar los Tiempos de Respuesta reales de las colas de la AEAT:

Videoguías y demostraciones en vivo de los SDKs:
🎬 Vídeo 1: https://youtu.be/XRn_FgcbQMM
🎬 Vídeo 2: https://youtu.be/gbpBQKYmjug
🎬 Vídeo 3: https://youtu.be/Ozc1VpDHrFE

Hemos preparado las 'Units' de tal forma que tragan la estructura que pide Hacienda mediante un JSON neutro y limpio, sin que tengáis que tocar las tripas de TLS ni XMLDsigs.

La idea de este cambio es que tener una pasarela en Delphi operativa no pase nunca de la media hora de pruebas locales. Pasaos a ojear el material y las APIs y, como siempre, cualquier *feedback* arquitectónico, duda implementando las Units o mejora de los componentes, o si alguno se ha decidido a probar, mejor interactuar por GitHub o correo electrónico: [email protected]

¡Un saludo!

[keno_71]

Gracias Birmain, le echaremos un vistazo

[[birmain]]

¡Hola a todos!

He creado nuevo codigo para la demostración en Delphi 7 y 10+ para la API de Veri*Factu. Muchos en la comunidad nos estamos enfrentando al mismo muro: lidiar con criptografía avanzada, construcción de XMLs pesados, enrutamiento SSL y gestión de certificados oficiales. Hacerlo de forma nativa mermando el rendimiento del ERP ya es molesto, pero si además tienes que dar soporte a software legacy en Delphi 7 o similar, puede convertirse en un auténico dolor de cabeza.



Para que veáis lo sencillo que puede quedar el código en Delphi, acabamos de publicar nuevas guías interactivas con el SDK Nativo:

1. Documentación SDK Delphi 7 (Legacy)
   Ideal para quienes arrastran ERPs históricos. Demuestra cómo usar nuestra unidad oficial uVFEngine.pas nativamente en D7 sin depender de librerías extrañas de terceros que corrompen el entorno.
   
2. Documentación SDK Delphi 10+
   La variante moderna. Interfaz 100% idéntica al código del D7, para que el salto generacional de tu aplicación no requiera reescribir la integración fiscal.
   
3. API Quickstart y Ejemplos de Código Interactivos
   En este enlace caeréis directamente en nuestro hub de fragmentos de código. Podréis visualizar exactamente cómo unificar las llamadas HTTP con el patrón de sondeo asíncrono IngestaYConfirmacion en todas sus versiones (no solo Delphi, sino la comparativa frente a cURL, C#, PHP, Python o Node) por si tenéis integraciones en paralelo).

Espero que estos recursos os ahorren decenas de horas de programación y documentacion, a los que hasta ahora no hayais resuelto esta meta. Echadle un ojo a las URLs y cualquier sugerencia arquitectónica, duda o feedback será enormemente bienvenido en GitHub o preguntas directas en la propia web.

¡Un saludo!

P.D: Disculpar, los dos primeros enlaces ya los había puesto, no obstante estan revisados y he añadido contenido. El tercero es completamente nuevo.

[[birmain]]

Disculpar mi insistencia en los enlaces. Se está mejorando la web y algunos han quedado obsoletos.

Documentación Oficial y SDKs (VeriFactu Micro-Servicio)

• Guía de Integración Rápida (API REST O(1))
  En este primer enlace buscar al final la implementacion del comienzo rápido en Delphi 7 y Delphi 10+
• Descargar y usar el SDK para Delphi 10 (Nativo)
• Descargar y usar el SDK Legacy para Delphi 7 (AnsiString)

Un saludo !!

[Casimiro Noteví]