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

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.

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.

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.