Middleware de integração entre PHC, ZoneSoft e XD

Há uma cena que se repete em quase todas as empresas que vendem ao balcão e fazem a gestão noutro programa: alguém, ao fim do dia, exporta um ficheiro de um lado e importa do outro. Ou pior, escreve à mão. Funciona até ao dia em que alguém adoece, se engana numa linha, ou se esquece, e a partir daí ninguém confia nos números de nenhum dos dois sistemas.

Foi para acabar com isso que desenvolvemos o nosso middleware. Não é um exportador de ficheiros com outro nome: é uma peça de software feita por nós, que fica a ligar os sistemas e a mantê-los de acordo, sem ninguém ter de se lembrar de nada.

Que volume passa por aqui todos os dias

Num só cliente nosso, mais de 2 000 documentos por dia entram no Cegid PHC através deste middleware. No sentido inverso, no mesmo cliente, descem todos os dias do PHC para o XD ou o ZoneSoft dezenas de artigos ou de preços novos ou alterados.

Estes números são de uma instalação concreta em produção, e não de um ensaio de laboratório nem da soma de todos os clientes. Servem sobretudo para dar a escala. Isto não é uma sincronização noturna de vinte linhas: é o movimento de balcão de empresas com lojas a faturar ao mesmo tempo. Quem hoje faz este trabalho à mão, ou por exportação e importação de ficheiros ao fim do dia, percebe de imediato quantas horas por semana estão aqui em causa, e percebe também o que acontece na semana em que a pessoa que costuma fazer isso está de férias.

O que liga a quê

Sincroniza o Cegid PHC com o ZoneSoft e o Cegid PHC com o XD. Podem estar os dois ligados ao PHC ao mesmo tempo, o que é o caso normal de quem tem lojas ou restaurantes com equipamento diferente e uma só contabilidade.

E liga também o XD ao ZoneSoft, diretamente, sem ter de passar por um terceiro sistema. Serve para grupos que cresceram por aquisição e ficaram com dois programas de ponto de venda diferentes a conviver.

Num sentido, nos dois, ou cada coisa no seu sentido

A direção não é uma decisão única para toda a integração. Define-se por tabela, porque raramente faz sentido tudo andar para os dois lados.

O caso mais comum é este. Artigos, preços, famílias ou clientes descem da gestão para o ponto de venda, porque é lá que devem ser criados uma vez só. Vendas, movimentos de caixa ou consumos sobem do ponto de venda para a gestão, porque é lá que têm de virar contabilidade. Tudo o resto é configuração, e pode mudar depois sem refazer nada.

Sem portos abertos nos servidores

Esta parte costuma surpreender quem já pediu orçamentos para integrações. A maioria exige abrir a firewall, publicar a base de dados ou montar uma rede privada entre instalações. Cada uma, mais uma porta.

A nossa não pede nada disso. A ligação parte sempre de dentro para fora: é o componente instalado dentro da rede da empresa que a abre. A firewall não precisa de aceitar nada vindo do exterior, não há serviço publicado na internet, e a base de dados do ERP nunca fica exposta.

Para quem tem de responder por segurança, isto deixa de ser um pormenor técnico. Nenhuma porta aberta é uma porta a menos para ser encontrada por quem varre a internet à procura de bases de dados mal protegidas, que é como começam muitos dos casos de ransomware a que somos chamados. Ver cibersegurança.

Todas as tabelas, e só os dados que interessam

Chegamos a qualquer tabela dos sistemas envolvidos, e não a um punhado de campos escolhidos por quem fez o programa. Importa. As empresas usam campos próprios, criados para o negócio delas, e são quase sempre esses que uma integração de catálogo deixa de fora.

Tão importante como passar tudo é não passar o que não deve. Filtramos nos dados. Só determinada loja, só certas séries de documentos, só uma família de artigos, só a partir de uma data. Uma empresa com sete lojas raramente quer todas as vendas de todas elas a caírem no mesmo sítio sem distinção, e um grupo com várias sociedades tem de manter as coisas separadas.

Painel e relatórios

Tem um painel próprio, onde se vê o que está a passar, quando passou e em que volume. Uma integração que trabalha em silêncio é confortável até ao dia em que para, e nesse dia a diferença entre reparar de manhã ou reparar ao fim da semana é toda.

E há uma coisa que se ganha por acréscimo: relatórios cruzados que nenhum dos sistemas dá sozinho, porque cada um só conhece metade da história. Vendas do balcão lado a lado com compras e stocks da gestão, por loja, por família, pelo período que interessar.

Porque é que isto não é uma exportação de ficheiros

Trocar ficheiros entre dois programas é fácil de montar e difícil de manter. O trabalho a sério está no meio: fazer corresponder códigos que são diferentes de um lado e do outro, respeitar as regras de cada sistema em vez de escrever por cima delas, e assegurar que nada é lançado duas vezes quando alguma coisa corre mal.

Como o código é nosso, tratamos do caso de cada empresa em vez de pedir à empresa que se adapte ao que o programa aceita. Ver desenvolvimento de software e o código é seu.

Como está construído por dentro

Esta secção é para o informático interno, ou o fornecedor de confiança, que avalia a proposta. Vai sem rodeios. Quem percebe do assunto merece detalhe, não adjetivos. Há pormenores de implementação que não publicamos, pelas razões óbvias, mas o desenho está todo aqui e explicamo-lo numa chamada.

Três peças, e nenhuma delas obriga a abrir um porto

1. Um agente em cada máquina de ERP

Desenvolvido em .NET 8, em C#, corre como serviço Windows no posto. A arquitetura do agente é comum. O que muda é o adaptador para a base de dados de cada programa. No lado do Cegid PHC, uma API em .NET 8 com Dapper sobre SQL Server, que serve os dados-mestre e importa os documentos que sobem. No ZoneSoft, um worker ligado ao SQL Server Express instalado na própria máquina do posto. No XD, o worker fala com MariaDB. Cada um lê para extrair os documentos a sincronizar e escreve para aplicar os dados-mestre que descem.

2. Um relay online, que serve de fila fiável

É a peça do meio, com caixa de saída e caixa de entrada. É ela que permite que as máquinas de ERP só façam ligações de saída. Está desenvolvida em PHP 8.1 sobre MySQL, sem framework, com um único ponto de entrada e um carregador de classes próprio. PHP simples, aqui, não é preguiça. Esta peça tem de correr em quase qualquer alojamento, sem depender de uma pilha que a empresa depois não consiga manter.

3. Um backoffice para ver o que se passa

Aplicação em React 18 com TypeScript, construída com Vite e TailwindCSS, com TanStack Query para os dados e Recharts para os gráficos. Mostra a profundidade da fila, as mensagens que morreram, que nós estão ativos e o registo dos pedidos. Ver, em vez de acreditar.

O relay não sabe o que transporta

É a decisão de que temos mais orgulho. Costuma decidir a conversa com um responsável de segurança. O conteúdo de negócio é cifrado no próprio nó, antes de sair, com cifra autenticada moderna do tipo XChaCha20-Poly1305 ou AES-256-GCM. O relay recebe blocos cifrados, move-os e entrega-os. Não tem a chave. Nunca lê o conteúdo.

A consequência prática é simples de dizer a um administrador ou a um auditor: mesmo que a peça do meio fosse comprometida por inteiro, o que lá está não se lê. As faturas, os preços e os clientes da empresa não estão em texto legível em lado nenhum do percurso.

Como se prova que um pedido é legítimo

Cada pedido que um nó faz ao relay vai assinado, com HMAC-SHA256 ou com Ed25519 através da libsodium. A assinatura cobre o pedido inteiro, conteúdo incluído. Leva marca temporal e um número usado uma única vez, o que fecha a porta a quem capture um pedido válido para o repetir mais tarde. A verificação é feita em tempo constante, para não deixar pistas por comparação. TLS obrigatório. Os cabeçalhos de segurança habituais estão todos ativos, e há limitação de ritmo por origem para que ninguém possa martelar o serviço.

Somando, a validação acontece em três camadas independentes. Na origem, em cada máquina de ERP, com assinatura e cifra antes de sair. No relay, com verificação de assinatura, de marca temporal, de repetição e de ritmo. No backoffice, com acesso autenticado.

Idempotência e mensagens que falham

Idempotência

Cada nó guarda o seu próprio registo local, em SQLite, do que já aplicou. A mesma mensagem entregue duas vezes não duplica nada. Parece um pormenor de engenharia. Na prática, separa uma integração que se retoma sozinha depois de uma quebra de linha de outra que obriga alguém a comparar tabelas à mão. Em documentos fiscais, é o que impede um duplicado.

Fila de mensagens mortas

O que falhar repetidamente não desaparece nem fica preso num ciclo infinito de tentativas. Sai para uma fila à parte. Fica lá com o erro e o conteúdo original, visível no backoffice, e é reprocessado quando a causa estiver resolvida. Uma integração que perde registos em silêncio é pior do que nenhuma, porque ninguém desconfia dos números.

Tudo fica registado

Cada pedido, o ciclo de vida de cada mensagem e todas as falhas ficam num registo central. Alguém pergunta, meses depois, se determinada fatura passou e quando? A resposta sai de uma consulta. Ninguém supõe.

Que dados sobem e que dados descem

Os documentos fiscais sobem, do ERP do posto para o Cegid PHC. Vão certificados na origem. O PHC importa-os sem renumerar nem voltar a certificar. É a parte que um contabilista atento pergunta primeiro, e é por isso que está desenhada assim.

Os dados-mestre descem, do PHC para os postos: clientes, artigos, preços e existências. Cada worker trata dos dois sentidos para o seu programa. O sentido define-se tabela a tabela. Inverter alguma coisa mais tarde faz-se por configuração, não por desenvolvimento novo.

E nada disto obriga a abrir um único porto na firewall, pela razão explicada acima: a ligação parte sempre de dentro para fora.

Já está a correr

Está em produção, todos os dias, em empresas reais. Nomes e volumes só saem com autorização de quem nos contratou. É regra para todos os clientes. Numa conversa mostramos o painel a funcionar, que convence mais do que qualquer descrição.

O que perguntamos antes de dizer que sim

Que versões de cada programa estão instaladas, que tabelas e campos próprios foram criados entretanto, quantos documentos passam por dia, e o que tem de acontecer quando os dois lados discordarem. Esta última é a pergunta que separa uma integração que dura de uma que dá problemas ao segundo mês.

Também confirmamos o acesso: mexer nos dados de uma empresa faz-se com autorização escrita de quem manda nela, e não de outra maneira.

Quanto custa

Desde 10 € + IVA por mês. É o valor de entrada, com a integração já a funcionar e com as atualizações e o suporte incluídos.

O valor é mensal e inclui todas as atualizações e o suporte. Pesa mais do que parece. Os programas de gestão e os de balcão são atualizados várias vezes por ano, e é quase sempre aí que as integrações partem. Quando acontecer, não há orçamento novo nem discussão sobre quem paga o conserto. Está incluído.

Uma tabela de preços seria fingir que isto é um produto de prateleira, e não é. Somos uma empresa de consultoria. Cada projeto muda com os sistemas que se ligam, com as tabelas que entram e com o volume que passa todos os dias.

Por isso o primeiro passo é uma avaliação sem custo, para perceber o que se ajusta ao caso da empresa, não o que dá mais a faturar. Dela sai um levantamento escrito, com as tabelas e os sentidos identificados um a um, e o valor mensal para aquele caso.

Valores a que acresce IVA à taxa legal em vigor. Serviços dirigidos a empresas e profissionais.

Procura assistência a uma destas marcas? Temos página própria: ZoneSoft em Bragança e Trás-os-Montes ou XD Software em Bragança e Trás-os-Montes.