Conector Axonaut para WooCommerce — Documentación
Instalar, conectar y configurar el Conector Axonaut para WooCommerce: facturas o presupuestos, empresas y contactos, abonos, importación del histórico.
El Conector Axonaut para WooCommerce une tu tienda WooCommerce con el ERP/CRM francés Axonaut. Envía automáticamente tus pedidos a Axonaut como facturas o presupuestos, crea las empresas y contactos correspondientes, genera abonos en los reembolsos y te permite importar tu histórico. Todo el procesamiento se ejecuta en segundo plano mediante Action Scheduler, sin impacto en el checkout, y es idempotente: un pedido nunca se sincroniza dos veces.
Requisitos
- WordPress 6.0 o superior
- WooCommerce 7.0 o superior
- PHP 7.4 o superior
- Una cuenta de Axonaut activa y su clave API
El plugin no requiere ninguna dependencia de Composer en tu servidor y es compatible con el almacenamiento de pedidos de alto rendimiento (HPOS) y con el almacenamiento clásico.
Instalación
- En la administración de WordPress, ve a Plugins > Añadir nuevo > Subir plugin.
- Selecciona el archivo ZIP del plugin y haz clic en Instalar ahora.
- Activa el plugin.
- Aparece un nuevo menú WooCommerce > Axonaut en la administración.
Conexión con Axonaut
Ve a WooCommerce > Axonaut, pestaña Ajustes.
Obtener tu clave API
En tu cuenta de Axonaut, abre la sección Ajustes y luego Desarrolladores. Copia tu clave API personal.
Introducir y probar la clave
Pega la clave en el campo Clave API de Axonaut y haz clic en Probar conexión. Un mensaje verde confirma que la conexión está establecida; un mensaje rojo indica una clave no válida o un problema de red.
La clave se almacena de forma segura y nunca se muestra en claro una vez guardada. La prueba de conexión utiliza la clave introducida en el campo, incluso antes de guardar.
Configuración
Tipo de documento
Elige el documento creado en Axonaut a partir de un pedido: Factura o Presupuesto. Esta elección se aplica a todos los pedidos sincronizados.
Estados desencadenantes
Marca los estados de pedido que desencadenan el envío a Axonaut (por ejemplo Completado). En cuanto un pedido alcanza uno de estos estados, se pone en cola para su sincronización. Cada pedido se envía una sola vez, incluso si cambia de estado varias veces.
Contactos
Activa esta opción para que el comprador se cree como contacto (employee) vinculado a la empresa en Axonaut. La empresa siempre se crea: Axonaut la necesita para adjuntar facturas y presupuestos.
Reembolsos
Activa esta opción para que un reembolso de WooCommerce genere automáticamente un abono en Axonaut. Solo se aplica a los pedidos ya sincronizados como facturas.
Fecha de pago
Cuando está activada, la fecha de pago se transmite a Axonaut para los pedidos ya pagados.
Productos
Opcional: sincroniza tus productos de WooCommerce con el catálogo de Axonaut al crearlos o actualizarlos.
Mantenimiento
Define el periodo de retención del registro (en días) y activa el modo depuración para registrar las respuestas completas de la API en caso de diagnóstico.
Sincronización de pedidos
Cuando un pedido alcanza un estado desencadenante, el conector:
- resuelve o crea la empresa de Axonaut correspondiente;
- construye el documento línea por línea, con el tipo de IVA calculado para cada línea;
- añade los gastos de envío y las comisiones como líneas dedicadas;
- transmite la fecha de pago si el pedido ya está pagado;
- crea la factura o el presupuesto en Axonaut y guarda su identificador en el pedido.
El procesamiento es asíncrono (Action Scheduler): no alarga el tiempo de pago. En caso de error temporal de la API (429 o 5xx), el envío se reintenta automáticamente con un retardo creciente, hasta cinco veces.
Empresas, contactos e IVA intracomunitario
La empresa de Axonaut se crea a partir de los datos de facturación. El conector distingue automáticamente a los clientes profesionales (campo empresa rellenado) de los particulares, y mapea el número de IVA intracomunitario detectado desde los principales plugins de IVA UE.
Deduplicación
Antes de cualquier llamada a la API, el conector busca una empresa ya resuelta: primero en el propio pedido, luego en la cuenta del cliente (si la hay), luego en un pedido anterior con el mismo correo de facturación. Los compradores recurrentes, incluso en compra como invitado, se reconocen sin crear un duplicado.
Abonos y reembolsos
Un reembolso de WooCommerce, total o parcial, sobre un pedido ya sincronizado como factura, genera automáticamente un abono en Axonaut, vinculado a la factura original.
- Los reembolsos por línea se reflejan línea por línea, con el IVA recalculado.
- Los reembolsos por importe producen una única línea de abono global.
- Los gastos de envío reembolsados se añaden como línea dedicada.
Cada abono es idempotente: un mismo reembolso nunca genera dos abonos.
Importación del histórico
La pestaña Importar permite enviar tus pedidos existentes a Axonaut.
- Elige un rango de fechas (opcional) y los estados de pedido a incluir.
- Haz clic en Iniciar importación.
- Los pedidos se recorren por lotes en segundo plano mediante Action Scheduler; los pedidos ya sincronizados se omiten automáticamente.
Sigue el avance en la pestaña Registro.
Acción en lote en la lista de pedidos
Desde la lista de pedidos (pantalla HPOS o pantalla clásica), selecciona uno o varios pedidos y elige la acción en lote Sincronizar con Axonaut. Un mensaje indica cuántos pedidos se pusieron en cola y cuántos se omitieron por estar ya sincronizados.
Caja meta y resincronización manual
En la pantalla de edición de un pedido, la caja Axonaut muestra el estado de sincronización: tipo y número del documento creado, empresa vinculada y fecha. Si el pedido aún no está sincronizado, un botón Sincronizar ahora permite un envío inmediato, mostrando el último error si lo hay.
Registro de actividad y modo depuración
La pestaña Registro muestra las últimas operaciones (creaciones de empresas, facturas, abonos, errores), con un enlace directo al pedido correspondiente. El periodo de retención es configurable. El modo depuración añade al registro el detalle completo de las respuestas de la API, útil para diagnosticar un problema.
Sincronización de productos (opcional)
Cuando la opción está activada, cada creación o actualización de producto de WooCommerce se refleja en el catálogo de Axonaut (nombre, referencia SKU, precio sin impuestos, tipo de IVA). La correspondencia se memoriza para actualizar el producto de Axonaut correcto en los cambios posteriores.
Compatibilidad con HPOS
El plugin declara su compatibilidad con el almacenamiento de pedidos de alto rendimiento (HPOS). Todos los metadatos de sincronización se guardan mediante la API de pedidos de WooCommerce, lo que garantiza un funcionamiento idéntico con el almacenamiento clásico y con HPOS.
Hooks para desarrolladores
El conector expone varios puntos de extensión para adaptar los datos enviados a Axonaut:
df_axonaut_company_payload— filtra los datos de la empresa antes de la creación.df_axonaut_employee_payload— filtra los datos del contacto antes de la creación.df_axonaut_document_payload— filtra los datos de la factura o del presupuesto.df_axonaut_credit_note_payload— filtra los datos del abono.df_axonaut_product_payload— filtra los datos del producto sincronizado.df_axonaut_vat_meta_keys— personaliza las claves de meta donde se busca el número de IVA.df_axonaut_order_synced— acción disparada tras la sincronización correcta de un pedido.df_axonaut_refund_synced— acción disparada tras la creación de un abono.
Resolución de problemas
La prueba de conexión falla
Comprueba que la clave API sea correcta y esté activa en tu cuenta de Axonaut, y que tu servidor pueda alcanzar la API de Axonaut por HTTPS de salida.
Un pedido no se sincroniza
Asegúrate de que su estado figure entre los estados desencadenantes y de que no se haya sincronizado ya. Consulta el registro y la caja Axonaut del pedido para ver el último error. Verifica también que la cola de Action Scheduler se esté ejecutando (WooCommerce > Estado > Acciones programadas).
No se ha creado un abono
Los abonos solo se generan para los pedidos ya sincronizados como factura (no presupuesto) y cuando la opción de reembolsos está activada.
No modifiques manualmente el identificador de documento de Axonaut guardado en un pedido: es lo que garantiza que un pedido nunca se envíe dos veces.