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, e no mesmo cliente, dezenas de artigos e de preços novos ou alterados descem todos os dias do PHC para o XD e para o ZoneSoft.

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 e clientes descem da gestão para o ponto de venda, porque é lá que devem ser criados uma vez só; e vendas, movimentos de caixa e 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 é a parte que costuma surpreender quem já pediu orçamentos para integrações. A maioria das soluções exige abrir a firewall, publicar a base de dados, ou montar uma rede privada entre instalações. Cada uma dessas coisas é uma porta nova para defender.

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 inicia. 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. Isso importa porque 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 ao nível dos 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 garantir que nada é lançado duas vezes quando alguma coisa corre mal.

É por o código ser nosso que conseguimos tratar do caso específico 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 quem tem um informático interno, ou um fornecedor de confiança, a avaliar a proposta. Fica escrita sem rodeios, porque quem percebe do assunto merece detalhe e não adjetivos. Há detalhes de implementação que não publicamos, pelas razões óbvias, mas o desenho está todo aqui e explicamo-lo ao pormenor 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, e 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 lado do ZoneSoft, um worker que fala com o SQL Server Express instalado na própria máquina do posto. No lado do XD, um worker que fala com MariaDB. Cada um deles lê para extrair os documentos a sincronizar e escreve para aplicar os dados-mestre que descem.

2. Um relay online, que funciona como fila fiável. É a peça do meio, com caixa de saída e caixa de entrada, e é 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. A opção por PHP simples aqui não é preguiça: esta peça tem de correr em praticamente 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. É a diferença entre saber que a integração está a funcionar e acreditar que está.

O relay não sabe o que transporta

Esta é a decisão de que temos mais orgulho e é a que 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 e 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, incluindo o conteúdo, e vem acompanhada de marca temporal e de um número usado uma única vez, o que fecha a porta a alguém que capture um pedido válido e o repita mais tarde. A verificação é feita em tempo constante, para não deixar pistas por comparação. TLS é obrigatório e os cabeçalhos de segurança habituais estão todos ativos. Há ainda 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. E no backoffice, com acesso autenticado à parte administrativa.

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 e é, na prática, o que 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 para perceber o que passou e o que ficou a meio. Em documentos fiscais, é o que impede um duplicado.

Fila de mensagens mortas. O que falhar de forma persistente não desaparece nem fica preso num ciclo infinito de tentativas: sai para uma fila à parte, com o erro e o conteúdo original guardados, fica visível no backoffice, e é reprocessado quando a causa estiver resolvida. Uma integração que perde registos em silêncio é pior do que não ter integração nenhuma, porque ninguém fica a desconfiar dos números.

Tudo fica registado. Cada pedido, o ciclo de vida de cada mensagem e todas as falhas ficam num registo central. Quando alguém pergunta, meses depois, se determinada fatura passou e quando, a resposta é uma consulta e não uma suposição.

Que dados sobem e que dados descem

Os documentos fiscais sobem, do ERP do posto para o Cegid PHC. Vão certificados na origem, e o PHC importa-os sem renumerar nem voltar a certificar. É esta 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, e o sentido define-se tabela a tabela. Se mais tarde fizer sentido inverter alguma coisa, inverte-se por configuração e 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, a trabalhar todos os dias em empresas reais. Nomes e volumes só saem com autorização de quem nos contratou, e é regra que aplicamos a todos os clientes. Numa conversa mostramos o painel a funcionar, que é bastante mais convincente 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 ao longo dos anos, 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. Esse é 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 à solução. Isto pesa mais do que parece à primeira vista. 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 isso 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 e cada projeto é único: muda com os sistemas que se ligam, com as tabelas e os sentidos que entram, e com o volume que passa todos os dias.

Por isso o primeiro passo é uma avaliação gratuita, feita para perceber qual é a solução mais ajustada às necessidades reais da empresa e não a que dá mais trabalho 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.