# Conector Axonaut PrestaShop: documentação

> 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,…

- Página: <https://www.datafirefly.com/pt/documentation/connecteur-axonaut-prestashop/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/connecteur-axonaut-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/connecteur-axonaut-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/connecteur-axonaut-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/connecteur-axonaut-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/connecteur-axonaut-prestashop/index.md), [pl](https://www.datafirefly.com/pl/documentation/connecteur-axonaut-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/connecteur-axonaut-prestashop/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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

1. No back-office do PrestaShop, abra _Módulos > Gestor de módulos > Carregar um módulo_ e envie o ficheiro ZIP do módulo.
2. Depois de instalado, clique em _Configurar_.
3. 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.