# Conector Axonaut para WooCommerce: documentação

> O Conector Axonaut para WooCommerce liga a sua loja WooCommerce ao ERP/CRM francês Axonaut. Envia automaticamente as suas encomendas para o Axonaut sob a forma de faturas ou de orçamentos,…

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

O **Conector Axonaut para WooCommerce** liga a sua loja WooCommerce ao ERP/CRM francês Axonaut. Envia automaticamente as suas encomendas para o Axonaut sob a forma de faturas ou de orçamentos, cria as empresas e os contactos correspondentes, gera notas de crédito nos reembolsos e permite-lhe importar o seu histórico. Todo o processamento é feito em segundo plano através do Action Scheduler, sem impacto no checkout, e mantém-se idempotente: uma encomenda nunca é sincronizada duas vezes.

## Requisitos

- WordPress 6.0 ou superior
- WooCommerce 7.0 ou superior
- PHP 7.4 ou superior
- Uma conta Axonaut ativa e a respetiva chave de API

O plugin não exige qualquer dependência do Composer no seu servidor e é compatível tanto com o armazenamento de encomendas de alto desempenho (HPOS) como com o armazenamento antigo.

## Instalação

1. Na administração do WordPress, vá a _Plugins > Adicionar > Carregar plugin_.
2. Selecione o ficheiro ZIP do plugin e clique em _Instalar agora_.
3. Ative a extensão.
4. Aparece um novo menu _WooCommerce > Axonaut_ na administração.

## Ligação ao Axonaut

Vá a _WooCommerce > Axonaut_, separador _Definições_.

### Obter a sua chave de API

Na sua conta Axonaut, abra a secção _Paramètres_ e depois _Développeurs_. Copie a sua chave de API pessoal.

### Introduzir e testar a chave

Cole a chave no campo _Chave de API Axonaut_ e clique em _Testar a ligação_. Uma mensagem verde confirma que a ligação está estabelecida; uma mensagem vermelha indica uma chave inválida ou um problema de rede.

A chave é guardada de forma segura e nunca é apresentada em claro depois de gravada. O teste de ligação usa a chave introduzida no campo, mesmo antes de guardar.

## Configuração

### Tipo de documento

Escolha o documento criado no Axonaut a partir de uma encomenda: **Fatura** ou **Orçamento**. Esta escolha aplica-se a todas as encomendas sincronizadas.

### Estados de disparo

Assinale os estados de encomenda que desencadeiam o envio para o Axonaut (por exemplo _Concluída_). Assim que uma encomenda atinge um desses estados, é colocada em fila para sincronização. Cada encomenda só é enviada uma vez, mesmo que mude de estado várias vezes.

### Contactos

Ative esta opção para que o comprador seja criado como contacto (employee) associado à empresa no Axonaut. A empresa, essa, é sempre criada: o Axonaut precisa dela para associar faturas e orçamentos.

### Reembolsos

Ative esta opção para que um reembolso no WooCommerce gere automaticamente uma nota de crédito no Axonaut. Só se aplica às encomendas já sincronizadas como fatura.

### Data de pagamento

Quando está ativa, a data de pagamento é transmitida ao Axonaut nas encomendas já pagas.

### Produtos

Opção facultativa: sincroniza os seus produtos WooCommerce com o catálogo do Axonaut na criação ou na atualização.

### Manutenção

Defina a duração de retenção do registo (em dias) e ative o modo de depuração para registar a totalidade das respostas da API em caso de diagnóstico.

## Sincronização das encomendas

Quando uma encomenda atinge um estado de disparo, o conector:

1. resolve ou cria a empresa Axonaut correspondente;
2. constrói o documento linha a linha, com a taxa de IVA calculada para cada linha;
3. acrescenta os portes e os eventuais encargos como linhas dedicadas;
4. transmite a data de pagamento se a encomenda já estiver paga;
5. cria a fatura ou o orçamento no Axonaut e regista o respetivo identificador na encomenda.

O processamento é assíncrono (Action Scheduler): não prolonga o tempo de passagem pela caixa. Em caso de erro temporário da API (429 ou 5xx), o envio é automaticamente repetido com um intervalo crescente, até cinco vezes.

## Empresas, contactos e IVA intracomunitário

A empresa Axonaut é criada a partir dos dados de faturação. O conector distingue automaticamente os clientes profissionais (campo de empresa preenchido) dos particulares, e transmite o número de IVA intracomunitário detetado a partir dos principais plugins de IVA da UE.

### Desduplicação

Antes de qualquer chamada à API, o conector procura uma empresa já resolvida: primeiro na própria encomenda, depois na conta do cliente (se existir), e depois numa encomenda anterior com o mesmo e-mail de faturação. Os compradores recorrentes, mesmo em encomenda como convidado, são assim reconhecidos sem criar duplicados.

## Notas de crédito e reembolsos

Um reembolso no WooCommerce, total ou parcial, numa encomenda já sincronizada como fatura, gera automaticamente uma nota de crédito no Axonaut, ligada à fatura de origem.

- Os reembolsos por linha são retomados linha a linha, com o IVA recalculado.
- Os reembolsos por montante produzem uma linha de nota de crédito global.
- Os portes reembolsados são acrescentados como linha dedicada.

Cada nota de crédito é idempotente: um mesmo reembolso nunca gera duas notas de crédito.

## Importação do histórico

O separador _Importação_ permite enviar as suas encomendas existentes para o Axonaut.

1. Escolha um intervalo de datas (facultativo) e os estados de encomenda a incluir.
2. Clique em _Iniciar a importação_.
3. As encomendas são percorridas por lotes em segundo plano através do Action Scheduler; as encomendas já sincronizadas são automaticamente ignoradas.

Acompanhe o progresso no separador _Registo_.

## Ação em massa na lista de encomendas

A partir da lista de encomendas (ecrã HPOS ou ecrã antigo), selecione uma ou várias encomendas e escolha a ação em massa _Sincronizar com o Axonaut_. Uma mensagem indica o número de encomendas colocadas em fila e as ignoradas por já estarem sincronizadas.

## Metabox e ressincronização manual

Na ficha de uma encomenda, a caixa _Axonaut_ mostra o estado de sincronização: tipo e número do documento criado, empresa associada e data. Se a encomenda ainda não estiver sincronizada, um botão _Sincronizar agora_ permite um envio imediato, com apresentação do último erro, se existir.

## Registo de atividade e modo de depuração

O separador _Registo_ mostra as últimas operações (criações de empresas, faturas, notas de crédito, erros), com uma ligação direta para a encomenda em causa. A duração de retenção é configurável. O modo de depuração acrescenta ao registo o detalhe completo das respostas da API, útil para diagnosticar um problema.

## Sincronização dos produtos (opcional)

Quando a opção está ativa, cada criação ou atualização de produto no WooCommerce é refletida no catálogo do Axonaut (nome, referência SKU, preço sem IVA, taxa de IVA). A correspondência é memorizada para atualizar o produto Axonaut certo nas alterações seguintes.

## Compatibilidade HPOS

O plugin declara a sua compatibilidade com o armazenamento de encomendas de alto desempenho (High-Performance Order Storage). Todos os metadados de sincronização são gravados através da API de encomendas do WooCommerce, o que garante um funcionamento idêntico com o armazenamento antigo e com o HPOS.

## Hooks para programadores

O conector expõe vários pontos de extensão para adaptar os dados enviados ao Axonaut:

- `df_axonaut_company_payload`: filtra os dados da empresa antes da criação.
- `df_axonaut_employee_payload`: filtra os dados do contacto antes da criação.
- `df_axonaut_document_payload`: filtra os dados da fatura ou do orçamento.
- `df_axonaut_credit_note_payload`: filtra os dados da nota de crédito.
- `df_axonaut_product_payload`: filtra os dados do produto sincronizado.
- `df_axonaut_vat_meta_keys`: personaliza as chaves de meta onde procurar o número de IVA.
- `df_axonaut_order_synced`: ação acionada após a sincronização bem-sucedida de uma encomenda.
- `df_axonaut_refund_synced`: ação acionada após a criação de uma nota de crédito.

## Resolução de problemas

### O teste de ligação falha

Verifique que a chave de API está correta e ativa na sua conta Axonaut, e que o seu servidor consegue alcançar a API do Axonaut em saída HTTPS.

### Uma encomenda não é sincronizada

Certifique-se de que o seu estado consta dos estados de disparo e que ainda não foi sincronizada. Consulte o registo e a caixa Axonaut da encomenda para ver o último erro. Verifique também que a fila do Action Scheduler está a ser executada (WooCommerce > Estado > Ações agendadas).

### Uma nota de crédito não foi criada

As notas de crédito só são geradas nas encomendas já sincronizadas como _fatura_ (e não como orçamento) e quando a opção de reembolsos está ativa.

Não altere manualmente o identificador de documento Axonaut gravado numa encomenda: é ele que garante que uma encomenda nunca é enviada duas vezes.