Si necesitas conectar tu aplicación o tu tienda online con Facturadirecta, la vía es su API REST. Facturadirecta expone una API que permite crear facturas, gestionar clientes, consultar productos y manejar series de facturación desde cualquier sistema externo — incluyendo WordPress y WooCommerce.
En esta guía vamos a cubrir lo esencial: cómo autenticarte, qué endpoints están disponibles, cómo crear una factura programmáticamente y cómo integrarlo con WordPress sin reinventar la rueda.
Contents
Autenticación: cómo conectar con la API
Facturadirecta utiliza autenticación por API key. Cada usuario con un plan de pago puede generar su clave desde el panel de configuración de Facturadirecta. Esta clave se envía en las cabeceras HTTP de cada petición para identificar y autorizar la cuenta.
El esquema de autenticación es sencillo: una vez tienes tu API key, la incluyes en cada llamada. No hay flujos OAuth ni tokens temporales. Esto simplifica mucho la integración, especialmente en entornos WordPress donde no quieres añadir complejidad innecesaria.
Endpoints principales
La API de Facturadirecta cubre las operaciones básicas de facturación. Los endpoints más relevantes para una integración con WooCommerce son:
Clientes: crear, actualizar y buscar clientes por email, NIF o nombre. Esto es crítico para la integración porque necesitas que cada comprador de WooCommerce tenga su ficha en Facturadirecta antes de emitir la factura.
Facturas: crear facturas con líneas de detalle, impuestos, series de facturación y métodos de pago. También puedes consultar facturas existentes o descargarlas en PDF.
Series de facturación: listar las series disponibles para asignar la correcta a cada factura según el tipo de venta o el ejercicio fiscal.
Productos: aunque para la mayoría de integraciones con WooCommerce no es necesario sincronizar productos (los datos vienen del pedido), la API permite consultar y crear productos en Facturadirecta si lo necesitas.
Flujo típico de integración desde WordPress
Cuando conectas WooCommerce con Facturadirecta, el flujo que sigue el código es este:
- Evento en WooCommerce: un pedido cambia de estado (por ejemplo, a «completado»). WordPress dispara el hook
woocommerce_order_status_completed. - Buscar o crear cliente: el plugin extrae los datos de facturación del pedido (nombre, NIF, email, dirección) y busca si ya existe en Facturadirecta. Si no existe, lo crea.
- Construir la factura: se mapean las líneas del pedido (productos, cantidades, precios, impuestos) al formato que espera la API de Facturadirecta.
- Enviar a la API: se hace una petición POST para crear la factura. La API devuelve el ID de la factura creada.
- Guardar referencia: el plugin almacena el ID de la factura en los metadatos del pedido de WooCommerce, para tener trazabilidad completa.
Si implementas esto desde cero, necesitas gestionar el manejo de errores (timeouts, respuestas 4xx/5xx), la cola de reintentos y la configuración de mapeo de impuestos. No es trivial.
Mapeo de impuestos: el detalle que complica las integraciones
Uno de los puntos donde más se atascan las integraciones personalizadas es el mapeo de impuestos. WooCommerce tiene su propio sistema de tasas fiscales (por país, por clase de impuesto), y Facturadirecta tiene el suyo. Necesitas que ambos hablen el mismo idioma.
Por ejemplo: un pedido con IVA al 21% en WooCommerce tiene que generar una factura con el tipo impositivo correcto en Facturadirecta. Si vendes a la UE con IVA intracomunitario exento, esa exención tiene que reflejarse correctamente.
Si lo haces a mano vía código, necesitas una tabla de correspondencias. El plugin Connect WooCommerce para Facturadirecta ya incluye esta lógica de mapeo, que es probablemente la parte que más tiempo te ahorrará frente a una integración custom.
Errores comunes en la integración
Después de haber desarrollado y mantenido el plugin de integración, estos son los problemas que más vemos:
API key incorrecta o caducada: parece obvio, pero es la causa número uno de fallos. Siempre verifica que la key esté activa y tenga los permisos correctos.
Campos obligatorios vacíos: Facturadirecta requiere ciertos datos del cliente (como el nombre o el país) que en WooCommerce a veces no están rellenos, especialmente en pedidos rápidos o con checkout simplificado.
Duplicados de clientes: si no buscas correctamente antes de crear, acabas con múltiples fichas del mismo cliente. El criterio de búsqueda (email, NIF, o combinación) tiene que ser consistente.
Desajustes de impuestos: cuando el mapeo no está bien configurado, las facturas se crean con importes que no cuadran con lo cobrado. Esto es un problema fiscal real.
¿Desarrollar una integración custom o usar un plugin?
Depende de tu caso. Si tienes un flujo de facturación estándar (pedido → factura, con los datos habituales), el plugin Connect WooCommerce para Facturadirecta cubre el caso sin necesidad de tocar código. Instalas, configuras API key, mapeas impuestos y funciona.
Si necesitas algo muy específico — por ejemplo, lógica de facturación condicional, integración con un ERP intermedio, o generación de albaranes además de facturas — entonces puede que necesites desarrollo a medida. En ese caso, la documentación de la API de Facturadirecta y los hooks de WooCommerce te dan la base, pero cuenta con un esfuerzo de desarrollo y mantenimiento real.
Para la mayoría de autónomos y pymes con WooCommerce, el plugin es la vía más práctica y mantenible.
Preguntas frecuentes
¿La API de Facturadirecta es gratuita?
El acceso a la API está incluido en los planes de pago de Facturadirecta. Los planes gratuitos o básicos pueden tener restricciones de acceso.
¿Hay límite de peticiones?
Facturadirecta aplica rate limiting en su API. Para el volumen habitual de una tienda WooCommerce (decenas a cientos de pedidos al día), no suele ser un problema. Si procesas miles de pedidos diarios, contacta con su soporte para confirmar límites.
¿Puedo usar la API para generar presupuestos, no solo facturas?
Sí, la API soporta la creación de presupuestos además de facturas. Sin embargo, en el contexto de WooCommerce el uso principal es la facturación automática por pedido.
¿El plugin gestiona facturas rectificativas o abonos?
Depende de la versión del plugin y las capacidades de la API en ese momento. Consulta la documentación actualizada del plugin para verificar si los reembolsos de WooCommerce generan automáticamente la factura rectificativa correspondiente.
Conclusión
La API de Facturadirecta es accesible y bien documentada para lo que necesita un autónomo o pyme con tienda online. La integración con WooCommerce es viable tanto vía desarrollo custom como con plugin, pero para la mayoría de casos el plugin resuelve el problema de forma más rápida y mantenible.
Si quieres evitarte la implementación técnica, el plugin Connect WooCommerce para Facturadirecta ya tiene resueltos los puntos más complicados: autenticación, mapeo de impuestos, gestión de clientes y manejo de errores.
