Conector Axonaut PrestaShop — Documentación
Instala y configura el conector Axonaut para PrestaShop: clave API, sincronización de clientes, facturas/presupuestos, productos, cron y resolución de problemas.
El módulo Conector Axonaut PrestaShop (dfaxonaut, de DataFirefly) sincroniza automáticamente tus clientes, pedidos y productos entre PrestaShop y Axonaut, el software de gestión francés (CRM, facturación, presupuestos, tesorería). Esta guía cubre la instalación, la configuración, el funcionamiento de las sincronizaciones y la resolución de problemas.
Requisitos
- PrestaShop 8.x o 9.x, PHP 7.4 a 8.3.
- Una cuenta Axonaut activa con acceso a la API v2.
- Tu clave API de Axonaut (userApiKey), disponible en Axonaut en Ajustes > Desarrolladores > Clave API.
Instalación
- En el back-office de PrestaShop, abre Módulos > Gestor de módulos > Subir un módulo y suelta el archivo ZIP del módulo.
- Una vez instalado, haz clic en Configurar.
- También aparece una nueva pestaña Axonaut Connector en Parámetros avanzados: da acceso al panel y a los registros.
El módulo no instala ninguna dependencia de Composer al desplegar: el autoloader PSR-4 está integrado. No se requiere nada más en el servidor.
Configuración
Clave API y prueba de conexión
Pega tu clave API de Axonaut en el campo Clave API Axonaut y guarda. Después ve al panel (Parámetros avanzados > Axonaut Connector) y haz clic en Probar conexión: el módulo consulta el endpoint /me de Axonaut y muestra la cuenta asociada si todo es correcto.
Sincronización de clientes
Activa Sincronizar clientes para que cada creación de cuenta, actualización de cuenta o cambio de dirección cree o actualice una empresa de Axonaut junto con su contacto. El módulo detecta automáticamente a los profesionales (razón social o IVA intracomunitario indicado) y a los particulares (B2C), y transmite la dirección, el IVA intracomunitario y el número de empresa cuando están disponibles.
Sincronización de pedidos
Activa Sincronizar pedidos y luego elige:
- Modo: crear una factura o un presupuesto de Axonaut.
- Estados disparadores: el pedido se envía la primera vez que alcanza uno de los estados seleccionados (por ejemplo «Pago aceptado»).
- Precios con IVA: enviar los precios unitarios con IVA en lugar de sin IVA.
Cada pedido enviado incluye las líneas de producto (referencia, tipo de IVA, cantidad) y añade los gastos de envío en una línea dedicada. Un pedido ya enviado nunca se duplica.
Sincronización de productos (opcional)
Activa Sincronizar productos para reflejar tu catálogo (referencia, nombre, precio, IVA, descripción corta) en los productos de Axonaut. La sincronización se dispara cada vez que se actualiza una ficha de producto.
Tarea cron
Las sincronizaciones se ponen en cola y se procesan en segundo plano. Se intenta un procesamiento inline ligero al vuelo dentro de los hooks, pero para un funcionamiento fiable, programa la tarea cron mostrada en la configuración:
curl -s "https://tu-tienda.tld/index.php?fc=module&module=dfaxonaut&controller=cron&token=TU_TOKEN"Frecuencia recomendada: cada 5 a 15 minutos. El cron procesa la cola, purga los elementos completados (7 días) y los registros antiguos (30 días). El token se puede regenerar desde la página de configuración.
Si regeneras el token, recuerda actualizar la URL en tu planificador (cron del servidor, tarea de PrestaShop o servicio externo).
Panel y registros
La pestaña Axonaut Connector muestra los contadores (pendientes / sincronizados / fallidos) y el registro completo de operaciones, filtrable y exportable. Hay dos acciones disponibles:
- Procesar la cola ahora: fuerza el procesamiento inmediato de los elementos pendientes.
- Reintentar los fallidos: vuelve a poner en cola los elementos fallidos tras 5 intentos.
Cómo funcionan la cola y los reintentos
Cada entidad a sincronizar (cliente, pedido, producto) se coloca en una cola. Ante un error temporal (red, cuota de la API), el módulo reintenta automáticamente hasta 5 veces y luego marca el elemento como fallido. Los errores se registran con su mensaje, lo que facilita el diagnóstico. El modo depuración añade los payloads y respuestas completos de la API a los registros.
Resolución de problemas
- «Clave API vacía»: introduce la clave en la configuración antes de probar la conexión.
- Error HTTP 401/403: la clave API no es válida o ha sido revocada. Regenérala en Axonaut.
- Pedidos no enviados: comprueba que el estado alcanzado está entre los estados disparadores y que la sincronización de pedidos está activada.
- Elementos fallidos: abre el registro para leer el mensaje de error, corrige la causa y haz clic en Reintentar los fallidos.
- Nada se sincroniza en segundo plano: comprueba que la tarea cron está programada y que el token de la URL coincide con el de la configuración.
Notas técnicas
- API utilizada: Axonaut REST API v2, autenticación mediante el encabezado userApiKey.
- Endpoints: /me, /companies, /companies/{id}/employees, /employees/{id}, /products, /invoices, /quotations.
- Tablas creadas: dfaxonaut_map (correspondencias PrestaShop ↔ Axonaut), dfaxonaut_queue (cola), dfaxonaut_log (registros).
- Compatible con multitienda de PrestaShop.