Verifactu. Nueva API instalable como servicio con SDK para Delphi

[[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 !