Guía para enviar Facturas Electrónicas a Agencia Tributaria Española con PHP

En este artículo, te explicaremos paso a paso cómo comunicarte con el servicio XML de Hacienda Española para enviar facturas electrónicas utilizando PHP. Este enfoque es ideal para empresas o desarrolladores que necesitan automatizar el proceso de gestión de facturas.

Requisitos Previos

Antes de empezar, asegúrate de contar con lo siguiente:

1. Certificado Digital:

   • Necesitarás un certificado digital en formato PFX o PEM, como el certificado de la FNMT, para autenticarte ante Hacienda.

2. PHP Configurado:

   • PHP 7.4 o superior con las extensiones cURL y openssl habilitadas.

3. Acceso al Servicio SOAP:

   • Hacienda ofrece servicios web SOAP para gestionar facturas electrónicas. Necesitarás el endpoint y el esquema XML correspondiente.

4. Entorno de Pruebas:

   • Antes de enviar datos reales, utiliza el entorno de pruebas de Hacienda para verificar que todo funcione correctamente.

Paso 1: Configuración del Certificado Digital

El certificado digital es fundamental para autenticarte. Asegúrate de tenerlo almacenado en tu servidor y sigue estos pasos:

1. Guarda el archivo del certificado en un lugar seguro, por ejemplo, /ruta/a/tu-certificado.pfx.

2. Ten a mano la contraseña del certificado, ya que será necesaria para establecer la conexión segura.

Paso 2: Crear el Código PHP

A continuación, te proporcionamos el código PHP para enviar una factura electrónica a través del servicio SOAP de Hacienda:

<?php
// Ruta al archivo del certificado (formato PFX o PEM)
define('CERT_FILE', '/ruta/a/tu-certificado.pfx');
define('CERT_PASS', 'contraseña-certificado'); // Contraseña del certificado

// Endpoint del servicio SOAP de Hacienda (ajusta según el servicio específico)
define('SOAP_ENDPOINT', 'https://www2.agenciatributaria.gob.es/.../servicio');

// Namespace del servicio SOAP (ajusta según el WSDL específico)
define('SOAP_NAMESPACE', 'https://www2.agenciatributaria.gob.es/.../namespace');

// Crear el cuerpo de la solicitud SOAP (XML)
function createSoapRequest($facturaXML) {
    return <<<XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="SOAP_NAMESPACE">
    <soapenv:Header/>
    <soapenv:Body>
        <ns:EnviarFactura>
            <ns:Factura>
                <![CDATA[{$facturaXML}]]>
            </ns:Factura>
        </ns:EnviarFactura>
    </soapenv:Body>
</soapenv:Envelope>
XML;
}

try {
    // XML de ejemplo de la factura (ajusta según el esquema de Hacienda)
    $facturaXML = <<<XML
<Factura>
    <Emisor>
        <NIF>12345678A</NIF>
        <Nombre>Mi Empresa S.L.</Nombre>
    </Emisor>
    <Receptor>
        <NIF>87654321B</NIF>
        <Nombre>Cliente Ejemplo S.L.</Nombre>
    </Receptor>
    <Detalles>
        <BaseImponible>1000.00</BaseImponible>
        <IVA>210.00</IVA>
        <Total>1210.00</Total>
    </Detalles>
</Factura>
XML;

    // Crear la solicitud SOAP
    $soapRequest = createSoapRequest($facturaXML);

    // Configuración del cliente cURL
    $ch = curl_init(SOAP_ENDPOINT);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: text/xml; charset=utf-8',
        'SOAPAction: ""'
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $soapRequest);

    // Configurar el certificado para la conexión segura
    curl_setopt($ch, CURLOPT_SSLCERT, CERT_FILE);
    curl_setopt($ch, CURLOPT_SSLCERTPASSWD, CERT_PASS);

    // Realizar la llamada
    $response = curl_exec($ch);

    if (curl_errno($ch)) {
        throw new Exception('Error en la conexión: ' . curl_error($ch));
    }

    // Verificar el código de respuesta HTTP
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($httpCode !== 200) {
        throw new Exception("HTTP Code: $httpCode. Respuesta del servidor: $response");
    }

    curl_close($ch);

    // Mostrar la respuesta del servicio
    echo "Respuesta de Hacienda: n$responsen";

} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}
?>

Paso 3: Personalizar el XML de la Factura

El bloque $facturaXML contiene el ejemplo de una factura electrónica. Adáptalo a las necesidades de tu negocio siguiendo el esquema requerido por Hacienda. Esto incluye:

• Datos del emisor (NIF, nombre, etc.).

• Datos del receptor.

• Detalles de la factura (base imponible, IVA, total, etc.).

Paso 4: Realizar Pruebas

1. Usar el entorno de pruebas de Hacienda:

   • Verifica que tu integración funcione correctamente sin afectar datos reales.

2. Depurar errores:

   • Si encuentras problemas, revisa la respuesta del servicio y los mensajes de error.

Paso 5: Firmar el XML (Opcional)

Si el servicio SOAP lo requiere, deberás firmar digitalmente el XML antes de enviarlo. Para ello, puedes usar librerías como xmlseclibs.

Por ejemplo:

require_once 'xmlseclibs/xmlseclibs.php';

$doc = new DOMDocument();
$doc->loadXML($facturaXML);

$objDSig = new XMLSecurityDSig();
$objDSig->signWithKey($key, $cert);
$objDSig->add509Cert($cert);
$objDSig->appendSignature($doc->documentElement);

Conclusión

Con esta guía, deberías ser capaz de enviar facturas electrónicas a Hacienda utilizando PHP. Este enfoque combina cURL para realizar solicitudes SOAP seguras con certificados digitales para autenticarte.

Si tienes alguna duda o necesitas más ayuda, no dudes en contactarnos o dejar tus preguntas en los comentarios.