Introducción
VeriFactu es el sistema de verificación de facturas de la Agencia Tributaria que garantiza la integridad y autenticidad de la documentación fiscal electrónica. En el sector sanitario, especialmente en clínicas privadas, la integración correcta de este sistema es fundamental para cumplir con las obligaciones tributarias y mantener la trazabilidad de las transacciones. Este artículo ofrece una guía técnica completa para implementar VeriFactu en software de gestión clínica.
1. Requisitos Técnicos y Estándares
Formatos de Datos Soportados
VeriFactu opera sobre facturas electrónicas en formato UBL 2.1 (Universal Business Language) o FacturaE. Los requisitos técnicos principales incluyen:
- Codificación: UTF-8 obligatoria en todos los archivos
- Firma Digital: XAdES (XML Advanced Electronic Signatures) con nivel mínimo XAdES-EPES
- Timestamp: Incluir sello de tiempo de autoridad de sellado de tiempo (TSA)
- Estructura XML: Validación contra esquemas XSD de la Agencia Tributaria
Protocolos de Comunicación
La comunicación con la plataforma VeriFactu requiere:
- Protocolo HTTPS/TLS 1.2 mínimo (se recomienda 1.3)
- Certificados X.509 válidos con cadena de confianza completa
- Timeouts: 30-60 segundos para operaciones de envío
- Reintentos: Implementar exponential backoff (3-5 intentos máximo)
Volumen y Capacidad
Para clínicas medianas-grandes se recomienda:
- Capacidad de procesamiento: mínimo 1000 registros por lote
- Almacenamiento: 10 años de historial fiscal (según normativa)
- Ancho de banda: 10 Mbps mínimo para transferencias simultáneas
2. Integración con API de VeriFactu
Endpoints Principales
Producción: https://www1.agenciatributaria.es/wlpl/BUCV3FRJS
Pre-producción: https://www1dev.agenciatributaria.es/wlpl/BUCV3FRJS
Flujo de Integración
1. Autenticación
- Utilizar certificado digital de la persona física o entidad
- Implementar certificado de cliente (mTLS)
- Las credenciales deben rotarse cada 12 meses
2. Envío de Facturas
POST /registro/v1/envio-lote
Content-Type: application/xml
Authorization: Certificate-based
3. Consulta de Estado
GET /registro/v1/estado/{idLote}
4. Descarga de Confirmación
GET /registro/v1/descarga/{idLote}
Manejo de Respuestas
Implementar gestión robusta de códigos HTTP:
- 200/201: Éxito - guardar identificador de lote
- 400: Error de validación - registrar detalles XML
- 401: Problema de certificado - verificar vigencia
- 503: Servicio no disponible - reintentar después
3. Requisitos de Certificados Digitales
Tipo de Certificado
- Certificado de Persona Física: DNI-e o Certificado de Firma Electrónica
- Certificado de Entidad: CIF emitido por ACCV, Camerfirma o equivalente
- Validez: Mínimo 2 años a partir de la instalación
Proceso de Instalación en el Sistema
Exportar certificado en formato PKCS#12
- Incluir clave privada y certificado público
- Proteger con contraseña fuerte (mínimo 16 caracteres)
Almacenamiento seguro
- Guardar en almacén de certificados del SO o KeyStore Java
- Implementar permisos de acceso restrictivos
- Nunca almacenar en código fuente o configuración
Validación automática
- Verificar vigencia en cada 24h
- Alertar con 30 días de anticipación antes de vencimiento
- Implementar proceso automático de renovación
4. Auditoría y Preservación de Datos
Requisitos de Trazabilidad
Toda la documentación procesada debe incluir:
- Metadatos: Timestamp preciso (UTC), ID de usuario, IP origen
- Logs de Transacción: Almacenamiento inmutable de todas las operaciones
- Respuestas de Servidor: Guardar XML de confirmación completo
- Estados Intermedios: Registro de cambios de estado del lote
Implementación de Audit Trail
Estructura de registro mínima:
├── ID_TRANSACCION (UUID)
├── TIMESTAMP (ISO 8601 UTC)
├── USUARIO_SISTEMA
├── CERTIFICADO_USADO
├── TIPO_OPERACION (ENVIO, CONSULTA, DESCARGA)
├── ESTADO (PENDIENTE, PROCESANDO, COMPLETADO, ERROR)
├── RESPUESTA_SERVIDOR (full XML)
└── HASH_DOCUMENTO (SHA-256)
Preservación a Largo Plazo
- Retención: Mantener registros 10 años mínimo
- Integridad: Usar WORM storage (Write Once, Read Many) si es posible
- Encriptación: Cifrar datos en reposo (AES-256)
- Respaldos: Realizar copias redundantes en diferentes ubicaciones
5. Checklist de Compatibilidad de Software
- Generación de XML UBL 2.1 validado contra XSD oficial
- Firma XAdES-EPES con timestamp incluido
- Soporte para HTTPS/TLS 1.2+ con validación de certificados
- Gestión de certificados digitales (importación, validación, renovación)
- Almacenamiento seguro de claves privadas
- Compresión GZIP para envíos (recomendado)
- Cola de intentos fallidos con reintentos automáticos
- Logging detallado de todas las operaciones
- Interfaz de consulta de estado de lotes
- Notificaciones de error a responsables de TI
- Cumplimiento de horarios de disponibilidad de la plataforma
- Documentación de procesos de recuperación ante fallos
6. Testing y Validación Previa a Producción
Fase 1: Validación Local (Semana 1-2)
- Validar XML contra esquemas XSD
- Verificar estructura de firma XAdES
- Probar almacenamiento de certificados
Fase 2: Entorno Pre-producción (Semana 2-4)
- Conectar a servidor pre-producción de la Agencia Tributaria
- Enviar lotes de prueba (mínimo 50 facturas)
- Validar respuestas y confirmaciones
- Probar reintentos y recuperación de errores
Fase 3: Validación de Carga (Semana 4-6)
- Simular volumen mensual de facturas
- Medir tiempos de procesamiento
- Verificar uso de memoria y CPU
- Comprobar almacenamiento de logs
Fase 4: Testing de Seguridad (Semana 6-8)
- Realizar auditoría de permisos de certificados
- Validar encriptación de datos en tránsito
- Probar integridad de audit trail
- Verificar acceso a datos sensibles
7. Desafíos Comunes de Integración
Problema: Certificado No Reconocido
Síntoma: Error 401 al conectar Solución:
- Verificar cadena de confianza completa
- Confirmar que la Autoridad Certificadora está en lista de confianza de Java/SO
- Validar formato PKCS#12 y estructura de certificado
Problema: Timeout en Envío de Lotes
Síntoma: Conexión interrumpida durante upload Solución:
- Implementar compresión GZIP
- Dividir lotes en componentes más pequeños (máx. 500 facturas)
- Aumentar timeout progresivamente (máximo 120 segundos)
Problema: Inconsistencia en Timestamps
Síntoma: Facturas rechazadas por validación de fecha Solución:
- Sincronizar servidor con NTP (Network Time Protocol)
- Incluir timestamp de TSA en firma
- Registrar zona horaria en todos los logs
Problema: Pérdida de Confirmaciones
Síntoma: No se reciben ACKs de lotes enviados Solución:
- Implementar polling automático cada 5 minutos
- Guardar ID de lote en base de datos antes de enviar
- Crear tabla de reconciliación diaria
Recomendaciones Finales
- Designar responsable técnico dedicado para la integración
- Documentar todos los cambios en repositorio versionado
- Realizar auditorías trimestrales de cumplimiento
- Capacitar al equipo en normativa tributaria y procedimientos
- Establecer SLA con proveedor de hosting o cloud
- Monitorear continuamente métricas de entrega y errores
La integración de VeriFactu es crítica para la continuidad operativa de cualquier clínica. Una implementación técnicamente sólida garantiza cumplimiento fiscal, evita sanciones y proporciona confiabilidad operativa a largo plazo.
Última actualización: Marzo 2026 Autor: Equipo Técnico de Clinily Categoría: Desarrollo y Integración Tiempo de lectura: 12-15 minutos
