Integrar Primavera com uma aplicação web sem criar dívida

TL;DR

• Não ligues a aplicação web directamente à base de dados do Primavera para escrever documentos. Podes quebrar regras fiscais, stock, numeração e lançamentos contabilísticos.
• O padrão mais seguro é ter um serviço de integração intermédio, normalmente em .NET 8 LTS, perto do ERP, que fala com a API oficial do Cegid Primavera e expõe uma API limpa à aplicação web.
• Para leituras pesadas, como catálogo, clientes, stocks ou saldos, podes usar sincronização assíncrona para PostgreSQL 16, SQL Server 2022 ou outro datastore da aplicação, com controlo de versões e reconciliação.
• As maiores falhas aparecem em idempotência, séries de documentos, arredondamentos de IVA, concorrência no stock e jobs que assumem que o ERP está sempre disponível.
• Antes de escrever uma linha de código, decide quem é dono de cada dado: ERP, aplicação web, ou ambos com regras explícitas de sincronização.

O problema real não é “ligar ao Primavera”

A pergunta “como integrar Primavera com uma aplicação web moderna?” parece técnica, mas a parte difícil não é abrir uma ligação HTTP ou instalar uma biblioteca. A parte difícil é não transformar o ERP numa caixa negra cheia de efeitos laterais invisíveis.

Cegid Primavera, especialmente em instalações ERP v10 em ambientes empresariais portugueses, costuma ser o sistema de verdade para facturação, stock, contas correntes, artigos, clientes e contabilidade. A aplicação web moderna, feita em React, Next.js, Node.js 22 LTS.NET 8 LTS ou Django, costuma ser o ponto onde utilizadores externos ou equipas internas querem trabalhar com melhor experiência, autenticação actual, pesquisa rápida e fluxos à medida.

Essa diferença cria tensão. A web app quer respostas em 100 ms a 300 ms. O ERP pode precisar de validar uma série fiscal, calcular IVA, verificar armazém, bloquear um documento, lançar movimentos e gravar várias tabelas. Tratar estas duas realidades como se fossem a mesma coisa é o caminho mais curto para dívida técnica.

Nos projectos em que a Impact Origin apanha ERP de backoffice, a regra prática é simples: o Primavera não deve ser “a base de dados da aplicação web”. Deve ser integrado como sistema externo crítico, com contrato, logs, retries, idempotência e reconciliação. Isto parece mais lento no início, mas evita meses de correcções difíceis quando aparecem documentos duplicados, stocks negativos ou facturas que não batem certo com o SAF-T.

As quatro abordagens possíveis, e quando usar cada uma

Há quatro formas comuns de integrar uma aplicação web com Primavera. Nenhuma é perfeita. A escolha depende da versão do ERP, licenciamento, volume, criticidade fiscal e equipa que vai manter o sistema.

Primeira abordagem: API oficial ou camada pública do Primavera. Em ambientes Cegid Primavera ERP v10, deves começar pela documentação oficial de extensibilidade e integração em https://developers.primaverabss.com e pela documentação específica da versão instalada. Dependendo do produto e configuração, podes ter Web API, SDK .NET, serviços de integração ou extensões. É a melhor opção para criar documentos, actualizar entidades com regras de negócio e respeitar validações internas. O custo é que precisas de conhecer bem o modelo do ERP, lidar com mensagens pouco simpáticas e, muitas vezes, correr parte da integração em Windows, perto do servidor Primavera.

Segunda abordagem: leitura directa da base de dados SQL Server. Isto pode ser aceitável para relatórios, dashboards internos ou sincronização só de leitura, desde que saibas exactamente que tabelas e vistas estás a consultar. Mesmo assim, convém preferir vistas estáveis, réplicas ou uma base intermédia. Escrever directamente nas tabelas do Primavera é uma má ideia em quase todos os casos. Não é apenas uma questão de suporte. É uma questão de consistência fiscal e operacional.

Terceira abordagem: ficheiros, exports e imports. CSV, XML, Excel, SAF-T e pastas partilhadas ainda existem porque funcionam em empresas reais. São úteis quando o volume é baixo, a operação é batch e o ERP não expõe uma API adequada. A desvantagem é a latência, a falta de feedback imediato e a dificuldade em garantir idempotência. Se o utilizador precisa de saber em 2 segundos se a encomenda foi criada, ficheiro não chega.

Quarta abordagem: middleware com filas e base própria. É a minha opção preferida para integrações com alguma duração. A aplicação web fala com uma API tua. Essa API grava pedidos numa fila, por exemplo RabbitMQ 3.13, Azure Service Bus ou SQS, e um worker processa a integração com Primavera. Para dados de leitura, sincronizas para PostgreSQL 16 ou SQL Server 2022. Isto separa experiência do utilizador, disponibilidade do ERP e regras de integração.

A opinião forte: se a integração inclui facturas, encomendas, clientes, stock ou preços com impacto comercial, não faças uma chamada directa do frontend para o Primavera, nem ponhas a aplicação web dependente da latência do ERP. Usa uma camada anti-corrupção.

Arquitectura recomendada para uma integração séria

O desenho que costuma envelhecer melhor tem cinco peças.

A primeira é a aplicação web. Pode ser Next.js, React, Vue, Laravel.NET ou outra stack. Ela deve conhecer conceitos do produto, não detalhes internos do Primavera. Por exemplo, deve criar um “pedido de encomenda” no teu domínio, não tentar preencher campos obscuros de documentos comerciais do ERP.

A segunda é a API da tua aplicação. Aqui ficam autenticação, permissões, validações de entrada, auditoria e experiência de utilizador. Se um cliente submete uma encomenda, a API pode responder rápido com estado “recebida” e não bloquear durante 10 segundos à espera do ERP.

A terceira é uma fila ou tabela de outbox. A outbox é essencial quando queres garantir que a acção local e a intenção de sincronizar com o Primavera ficam gravadas na mesma transacção. Sem isto, vais ter casos em que a encomenda existe na aplicação, mas o job nunca arranca porque o processo caiu no momento errado.

A quarta é o serviço de integração. Em integrações Primavera, eu favoreço .NET 8 LTS quando a API ou SDK disponível é .NET, e corro o serviço numa máquina Windows ou servidor aplicacional com acesso de baixa latência ao Primavera e ao SQL Server. Este serviço traduz o teu domínio para documentos Primavera, aplica idempotência, trata erros e escreve logs técnicos.

A quinta é a base de leitura. Não peças ao Primavera para servir pesquisa de catálogo, listagens com filtros ricos e dashboards com 300 utilizadores. Sincroniza os dados necessários para uma base optimizada para a aplicação. Para muitos casos, PostgreSQL 16 chega perfeitamente. Para ambientes Microsoft, SQL Server 2022 também faz sentido.

Um contrato simples entre a web app e a integração pode ser assim:

{
  "externalRequestId": "web-order-982731",
  "customerCode": "C000245",
  "documentType": "ECL",
  "series": "2026",
  "currency": "EUR",
  "lines": [
    {
      "sku": "ART-001",
      "quantity": 2,
      "unitPrice": 19.99,
      "vatRate": 23
    }
  ]
}

O campo importante aqui é externalRequestId. Sem uma chave externa única, retries seguros tornam-se difíceis. Se a chamada falha por timeout, não sabes se o documento foi criado ou não. Com idempotência, podes repetir a operação e devolver o mesmo resultado.

Escrita no Primavera: onde se estragam integrações

Criar documentos comerciais é o ponto onde mais integrações falham. Encomendas, guias, facturas, notas de crédito e movimentos de stock não são simples inserts.

Há regras de numeração por série. Há validações de cliente. Há artigos com unidades alternativas. Há armazéns e localizações. Há IVA incluído ou excluído. Há descontos de linha e de cabeçalho. Há arredondamentos por linha ou por documento. Há retenções e regimes fiscais. Há permissões do utilizador Primavera. Há documentos que só podem ser anulados e não apagados.

A armadilha comum: assumir que a aplicação web pode calcular totais e que o Primavera apenas grava. Em produção, isto dá diferenças de cêntimos. Uma linha com preço unitário, desconto, IVA e arredondamento pode bater certo em 95 por cento dos casos e falhar precisamente nos documentos que vão para contabilidade. A regra deve ser: a aplicação web pode mostrar estimativas, mas o Primavera deve ser a fonte final para totais fiscais do documento.

Outra armadilha: não separar erros recuperáveis de erros definitivos. Um timeout, um deadlock SQL Server ou uma falha temporária de rede deve ir para retry com backoff. Um cliente inexistente, artigo bloqueado ou série inválida não deve repetir durante 6 horas. Deve ficar em erro funcional, visível numa consola de operações.

Para volumes modestos, como 10 a 50 documentos por minuto, um worker único com concorrência controlada pode chegar. Para 300 pedidos por minuto, já tens de pensar em filas particionadas, limites por empresa, locks por artigo ou armazém e janelas de sincronização. Primavera e SQL Server não gostam de concorrência cega sobre os mesmos recursos.

Padrão mínimo para idempotência na tua base:

CREATE UNIQUE INDEX ux_erp_requests_external_id
ON erp_integration_requests (external_request_id);

Parece banal, mas evita uma classe inteira de problemas. A idempotência não deve viver só em memória nem só nos logs. Deve estar garantida por uma restrição transaccional.

Leitura, sincronização e dados que ficam desactualizados

A parte de leitura parece mais simples, mas também tem rasteiras. A aplicação web pode precisar de clientes, moradas, artigos, preços, stock, estado de encomendas, facturas e saldos. Se cada página fizer chamadas ao Primavera em tempo real, vais acabar com uma aplicação lenta e frágil.

Há três estratégias.

A primeira é leitura directa em tempo real via API. Usa-a para ecrãs administrativos com baixo volume, onde a frescura do dado é mais importante do que a velocidade. Exemplo: consultar detalhe de uma factura acabada de emitir.

A segunda é sincronização periódica. A cada 1 a 5 minutos, importas alterações para a tua base. É adequada para catálogos, clientes e preços que não mudam a cada segundo. Batches de 500 a 2 000 registos por execução são um ponto de partida razoável, ajustado depois com métricas reais.

A terceira é sincronização orientada a eventos. Se conseguires emitir eventos a partir do Primavera, ou de uma extensão, melhor. Caso contrário, podes usar timestamps, tabelas de auditoria, SQL Server Change Tracking ou uma tabela de staging preenchida pela integração. A documentação oficial do SQL Server sobre Change Tracking é relevante aqui, mas não substitui conhecimento do esquema Primavera.

O problema inevitável é consistência eventual. Um utilizador altera uma morada no ERP e a web app só vê 2 minutos depois. Isto não é necessariamente mau, desde que o produto o aceite. O erro é fingir que tens tempo real quando tens polling.

Define SLAs internos por tipo de dado. Stock visível no site pode precisar de atraso máximo de 30 segundos. Catálogo pode tolerar 15 minutos. Facturas podem aparecer em 1 minuto. Saldos de conta corrente talvez devam ser consultados sob pedido, porque o utilizador espera exactidão.

Também deves guardar metadados de sincronização: source_updated_at, synced_at, versão do conector, hash do payload e estado da última tentativa. Sem isto, quando alguém pergunta “porque é que este cliente está diferente?”, ficas a adivinhar.

Segurança, auditoria e operação

Integrações ERP têm dados sensíveis: clientes, NIF, moradas, preços, margens, documentos fiscais e, às vezes, informação clínica ou financeira dependendo do sector. Não trates a API de integração como uma API interna sem segurança.

A autenticação entre serviços deve usar OAuth 2.0, mTLS, chaves rotativas ou, no mínimo, tokens com expiração curta guardados num secret manager. A aplicação web nunca deve guardar credenciais Primavera nem expô-las ao browser. Se usares Azure, Key Vault é uma opção natural. Em AWS, Secrets Manager. Em servidores próprios, pelo menos usa permissões restritas e rotação operacional.

A autorização deve ser explícita. Um utilizador que pode ver encomendas na aplicação web não deve automaticamente poder emitir documentos no ERP. A integração deve mapear acções para permissões internas.

Logs são obrigatórios, mas não despejes NIFs, moradas e payloads completos sem critério. Regista correlação, IDs, tipo de documento, duração, resultado e mensagem de erro sanitizada. Para observabilidade, OpenTelemetry é uma boa base. O objectivo é responder depressa a perguntas simples: quantos pedidos falharam, há quanto tempo a fila está atrasada, qual é o p95 de criação de documentos, que erros funcionais estão a bloquear a operação.

Métricas mínimas:

• latência p95 e p99 por operação, por exemplo criar encomenda, criar cliente, sincronizar stock
• tamanho da fila e idade do pedido mais antigo
• taxa de sucesso e falha por tipo de erro
• número de retries por hora
• diferença entre source_updated_at e synced_at

Alertas devem ser poucos e úteis. Uma falha isolada não deve acordar ninguém. Uma fila com pedidos há mais de 10 minutos, ou 20 por cento de erros nos últimos 15 minutos, já merece atenção.

Plano de implementação em fases

Não comeces pela parte mais difícil. Um plano sensato reduz risco e mostra cedo onde estão as surpresas.

Fase 1: inventário. Confirma versão exacta do Primavera, módulos usados, SQL Server, licenças, empresas, séries, tipos de documento, customizações, utilizadores e ambiente de testes. Sem ambiente de testes parecido com produção, vais testar em clientes reais, e isso raramente corre bem.

Fase 2: matriz de domínio. Lista entidades e dono do dado. Cliente é criado onde? Artigo nasce no ERP ou na web app? Stock é autoritativo no Primavera? Preços promocionais vivem onde? Esta matriz evita discussões tardias.

Fase 3: leitura primeiro. Sincroniza clientes, artigos e stocks para a aplicação. Mede latência, qualidade dos dados e diferenças. Nesta fase aparecem códigos duplicados, artigos inactivos usados em documentos, moradas incompletas e regras que ninguém escreveu.

Fase 4: escrita de baixo risco. Começa por criar uma entidade simples ou uma encomenda em estado controlado. Não comeces por facturação final se a equipa ainda não domina séries, impostos e anulações.

Fase 5: operação assistida. Durante as primeiras semanas, mantém uma consola interna com pedidos pendentes, falhados, reprocessáveis e ignorados. Integrações sem ecrã operacional obrigam developers a corrigir dados directamente, o que é mau sinal.

Fase 6: endurecimento. Só depois optimizas concorrência, batches, caching, reconciliação diária e alertas. Uma reconciliação nocturna entre documentos da aplicação e documentos Primavera é barata e apanha problemas antes do cliente.

A minha recomendação prática: reserva tempo para dados sujos. Em integrações ERP, o código raramente é o único problema. O histórico e as excepções da operação actual têm sempre mais impacto do que o diagrama inicial sugere.

Conclusão

Integrar Primavera com uma aplicação web moderna exige mais do que uma API. Exige fronteiras claras, idempotência, sincronização bem desenhada, segurança e operação visível. Escrever directamente na base do ERP pode parecer rápido, mas costuma sair caro. O caminho certo é tratar o Primavera como sistema crítico e construir uma camada de integração que aguente falhas reais.

Se estás a enfrentar um problema parecido, marca uma conversa em https://impact-origin.com/agendamento.