Conector Axonaut PrestaShop: documentação
Instalar e configurar o conector Axonaut para PrestaShop: chave de API, sincronização de clientes, faturas e orçamentos, produtos, cron e resolução de problemas.
O módulo Conector Axonaut PrestaShop (dfaxonaut, editado pela DataFirefly) sincroniza automaticamente os seus clientes, encomendas e produtos entre o PrestaShop e o Axonaut, o software de gestão francês (CRM, faturação, orçamentos, tesouraria). Este guia cobre a instalação, a configuração, o funcionamento das sincronizações e a resolução de problemas.
Nota para Portugal — O Axonaut é uma solução de gestão francesa: as faturas e os orçamentos que gera seguem as regras francesas e não estão certificados pela Autoridade Tributária portuguesa. Se as suas faturas tiverem de ser emitidas em Portugal com SAF-T (PT), ATCUD e software certificado pela AT, use o Axonaut como CRM e ferramenta de gestão comercial, mantendo a emissão fiscal no seu programa certificado. O conector transmite os dados; não altera o regime de faturação aplicável à sua empresa.
Pré-requisitos
- PrestaShop 8.x ou 9.x, PHP 7.4 a 8.3.
- Uma conta Axonaut ativa com acesso à API v2.
- A sua chave de API Axonaut (userApiKey), disponível no Axonaut em Definições > Programadores > Chave API.
Instalação
- No back-office do PrestaShop, abra Módulos > Gestor de módulos > Carregar um módulo e envie o ficheiro ZIP do módulo.
- Depois de instalado, clique em Configurar.
- Aparece também um novo separador Axonaut Connector em Parâmetros avançados: dá acesso ao painel e aos registos.
O módulo não instala qualquer dependência Composer no arranque: o autoloader PSR-4 está integrado. Não é preciso mais nada do lado do servidor.
Configuração
Chave de API e teste de ligação
Cole a sua chave de API do Axonaut no campo Chave API Axonaut e grave. Vá depois ao painel (Parâmetros avançados > Axonaut Connector) e clique em Testar a ligação: o módulo consulta o endpoint /me do Axonaut e apresenta a conta associada, se estiver tudo correto.
Sincronização dos clientes
Ative Sincronizar os clientes para que cada criação de conta, atualização de conta ou alteração de morada crie ou atualize uma empresa no Axonaut, acompanhada do respetivo contacto. O módulo deteta automaticamente os profissionais (denominação social ou IVA intracomunitário preenchidos) e os particulares (B2C) e transmite a morada, o IVA intracomunitário e o número de empresa, quando existem.
Sincronização das encomendas
Ative Sincronizar as encomendas e escolha depois:
- Modo: criar uma fatura ou um orçamento no Axonaut.
- Estados que desencadeiam o envio: a encomenda é enviada na primeira vez que atinge um dos estados selecionados (por exemplo, «Pagamento aceite»).
- Preços com IVA: enviar os preços unitários com impostos incluídos em vez de sem impostos.
Cada encomenda transmitida retoma as linhas de produto (referência, taxa de IVA, quantidade) e acrescenta os portes numa linha dedicada. Uma encomenda já enviada nunca é duplicada.
Sincronização dos produtos (opcional)
Ative Sincronizar os produtos para refletir o seu catálogo (referência, nome, preço, IVA, descrição curta) nos produtos do Axonaut. A sincronização é despoletada a cada atualização de uma ficha de produto.
Tarefa cron
As sincronizações são colocadas em fila e tratadas em segundo plano. É tentado um processamento inline leve nos hooks, mas, para um funcionamento fiável, agende a tarefa cron apresentada na configuração:
curl -s "https://a-sua-loja.tld/index.php?fc=module&module=dfaxonaut&controller=cron&token=O_SEU_TOKEN"Frequência recomendada: a cada 5 a 15 minutos. O cron trata a fila, limpa os elementos concluídos (7 dias) e os registos antigos (30 dias). O token pode ser regenerado na página de configuração.
Se regenerar o token, lembre-se de atualizar o URL no seu agendador de tarefas (cron do servidor, tarefa do PrestaShop ou serviço externo).
Painel e registos
O separador Axonaut Connector apresenta os contadores (pendentes / sincronizados / falhados) e o registo completo das operações, filtrável e exportável. Estão disponíveis duas ações:
- Processar a fila agora: força o processamento imediato dos elementos pendentes.
- Repetir as falhas: recoloca em fila os elementos que falharam ao fim de 5 tentativas.
Funcionamento da fila e das repetições
Cada entidade a sincronizar (cliente, encomenda, produto) é colocada numa fila. Em caso de erro temporário (rede, quota da API), o módulo repete automaticamente até 5 vezes e marca depois o elemento como falhado. Os erros ficam registados com a respetiva mensagem, o que facilita o diagnóstico. O modo de depuração acrescenta aos registos os payloads e as respostas completas da API.
Resolução de problemas
- «Chave API vazia»: preencha a chave na configuração antes de testar a ligação.
- Erro HTTP 401/403: a chave de API é inválida ou foi revogada. Regenere-a no Axonaut.
- Encomendas não enviadas: verifique se o estado atingido faz parte dos estados que desencadeiam o envio e se a sincronização das encomendas está ativada.
- Elementos falhados: abra o registo para ler a mensagem de erro, corrija a causa e clique em Repetir as falhas.
- Nada se sincroniza em segundo plano: verifique se a tarefa cron está mesmo agendada e se o token do URL corresponde ao da configuração.
Notas técnicas
- API utilizada: Axonaut REST API v2, autenticação por cabeçalho userApiKey.
- Endpoints: /me, /companies, /companies/{id}/employees, /employees/{id}, /products, /invoices, /quotations.
- Tabelas criadas: dfaxonaut_map (correspondências PrestaShop ↔ Axonaut), dfaxonaut_queue (fila), dfaxonaut_log (registos).
- Compatível com o modo multiloja do PrestaShop.