Conector Sellsy PrestaShop: documentação

Apresentação

O conector Sellsy da DataFirefly liga a sua loja PrestaShop ao Sellsy, a solução SaaS francesa de CRM, faturação e gestão. Sincroniza automaticamente os seus clientes, produtos, encomendas, faturas, pagamentos e notas de crédito do PrestaShop para o Sellsy, através da API Sellsy v2. A sincronização é unidirecional: PrestaShop → Sellsy.

Instalação

1. No back-office do PrestaShop, vá a Módulos > Gestor de módulos.
2. Clique em Instalar um módulo e carregue o ficheiro dfsellsy.zip.
3. Depois de instalado, clique em Configurar.

O módulo cria duas tabelas (dfsellsy_link para a correspondência PrestaShop ↔ Sellsy e dfsellsy_log para o registo) e um separador «Sellsy Connector» no menu Módulos.

Criar o acesso à API no Sellsy

O conector utiliza a autenticação OAuth2 (client credentials) da API v2.

1. No Sellsy, abra Menu > Definições > Portal do programador.
2. No separador API V2, clique em Criar um acesso API.
3. Escolha o colaborador associado ao acesso (de preferência um administrador, para dispor de todas as permissões) e assinale os scopes necessários (clientes, documentos, catálogo, pagamentos).
4. Grave e copie depois o Client ID e o Client Secret.

Configuração do módulo

Na página de configuração do módulo, preencha:

• Client ID e Client Secret: as credenciais OAuth2 criadas no Sellsy. Deixe o campo do secret vazio para conservar o valor já gravado.
• Sincronizar os clientes: cria ou atualiza uma entidade no Sellsy no registo e na atualização de um cliente.
• Sincronizar as encomendas: transforma as encomendas em documentos do Sellsy.
• Tipo de documento Sellsy para as encomendas: fatura ou nota de encomenda.
• Momento da sincronização das encomendas: na confirmação do pagamento ou na validação da encomenda.
• Validar os documentos Sellsy: valida automaticamente faturas e notas de crédito depois da criação (caso contrário, ficam em rascunho no Sellsy).
• Registar os pagamentos: regista os pagamentos do PrestaShop na fatura do Sellsy (apenas no tipo fatura).
• Sincronizar os reembolsos como notas de crédito: cria uma nota de crédito no Sellsy a cada nota de crédito do PrestaShop e liga-a à fatura de origem.
• Sincronizar os produtos: envia o catálogo para os itens do Sellsy.

Utilize o botão Testar a ligação à API para verificar as suas credenciais antes de ativar as sincronizações.

Sincronização dos clientes

No registo ou na atualização de um cliente, o módulo cria ou atualiza uma entidade no Sellsy. Os clientes com o campo «empresa» preenchido passam a empresas no Sellsy (com o SIRET, quando existe), os restantes a particulares. Uma pesquisa por e-mail evita duplicados e a morada de faturação principal é enviada na criação.

Sincronização das encomendas

Consoante o momento escolhido, uma encomenda validada ou paga passa a um documento do Sellsy com as linhas de produto, os portes e os descontos de carrinho (numa linha negativa). As taxas de IVA do PrestaShop são automaticamente correspondidas às taxas do Sellsy. Cada encomenda é sincronizada uma única vez (idempotência).

Faturas, validação e pagamentos

Quando o tipo de documento é «fatura»:

• se a opção Validar os documentos estiver ativa, a fatura é validada automaticamente depois da criação;
• se a opção Registar os pagamentos estiver ativa, cada pagamento do PrestaShop é registado na fatura, sem duplicados, incluindo os pagamentos parciais ou múltiplos;
• se a encomenda tiver sido criada na validação e o pagamento chegar mais tarde, o módulo regista apenas os novos pagamentos na fatura existente.

Notas de crédito por reembolso

Na geração de uma nota de crédito no PrestaShop, o módulo cria uma nota de crédito no Sellsy a partir das linhas reembolsadas (produtos e portes), valida-a se a opção estiver ativa e associa-a depois à fatura de origem, quando esta existe do lado do Sellsy.

Sincronização dos produtos

A sincronização dos produtos é opcional. Depois de ativada, os produtos são enviados para o catálogo do Sellsy na criação e na atualização. Também pode lançar uma sincronização em massa a partir da página «Sellsy Connector» (processamento em lotes de 20).

Tarefas agendadas (cron)

Um cron integrado permite recuperar aquilo que os hooks em tempo real possam ter falhado. Agende os URL apresentados na página de configuração:

• .../module/dfsellsy/cron?token=O_SEU_TOKEN&job=orders
• ...&job=customers
• ...&job=products
• ...&job=retry (repete as entidades com erro que ainda não foram associadas)

O parâmetro limit (20 por predefinição, máximo de 100) controla o tamanho do lote por execução.

Registo de sincronização

A página «Sellsy Connector» apresenta um registo filtrável (por entidade e por estado) de cada operação, com a mensagem devolvida pelo Sellsy em caso de erro. Um botão Repetir os erros volta a executar as falhas com um clique.

Resolução de problemas

• «Ligação falhada»: verifique o Client ID e o Client Secret e confirme que os scopes necessários estão assinalados no Sellsy.
• Um erro num campo de documento (HTTP 422): algumas contas Sellsy têm exigências específicas (menções de faturação eletrónica, campos obrigatórios). Consulte a mensagem do registo para identificar o campo em causa.
• Entidades duplicadas: o módulo procura por e-mail antes de criar; certifique-se de que o e-mail do cliente está preenchido.
• Nada se sincroniza: verifique se as opções em causa estão ativas e teste a ligação à API.