Integrar Primavera com uma aplicação web moderna

TL;DR

• A melhor integração com Primavera quase nunca é acesso directo à base de dados. Para escrita, usa a API oficial ou o SDK para respeitar regras fiscais, séries, armazéns e validações do ERP.
• Trata o Primavera como sistema de registo para clientes, artigos, stock, encomendas e documentos fiscais. A aplicação web deve ter uma cópia operacional, não tentar substituir a contabilidade.
• Se o ERP está instalado na rede do cliente, não o exponhas à Internet. Usa um conector local, fila de mensagens, VPN entre redes ou túnel controlado com autenticação forte.
• A parte difícil não é chamar a API. É sincronização, idempotência, conflitos, reprocessamento, observabilidade e perceber quem manda em cada campo.
• Começa por um fluxo pequeno, por exemplo clientes e encomendas, mede latências reais e só depois avança para stock, facturação e movimentos de armazém.

Antes do código, decide que integração estás mesmo a construir

“Integrar Primavera com uma aplicação web” pode significar quatro coisas muito diferentes.

Pode ser uma loja online que precisa de enviar encomendas para o ERP. Pode ser um portal B2B onde clientes consultam facturas e saldos. Pode ser uma app operacional que precisa de stock quase em tempo real. Ou pode ser uma plataforma interna que apenas quer ler dados mestres, como clientes, artigos e condições de pagamento.

A arquitectura muda consoante a resposta. Se só precisas de leitura diária de dados mestres, uma sincronização por lote chega. Se precisas de reservar stock em checkout, tens outro problema: concorrência, latência, falhas e reconciliação. Se vais emitir documentos fiscais, não inventes numeração nem regras de IVA fora do Primavera. O ERP deve continuar a ser a autoridade fiscal.

A primeira matriz que uso nestas integrações é simples:

• Dados mestres: clientes, fornecedores, artigos, famílias, preços, condições de pagamento.
• Dados operacionais: encomendas, reservas, expedições, movimentos de armazém.
• Dados fiscais: facturas, notas de crédito, recibos, séries, impostos.
• Dados analíticos: vendas agregadas, margens, saldos, histórico.

Cada grupo tem tolerância diferente a atraso. Dados mestres podem aceitar 5 a 15 minutos. Stock pode precisar de 30 a 60 segundos, dependendo do negócio. Documentos fiscais exigem consistência e rastreabilidade. Analytics pode correr durante a noite.

A opinião forte aqui: não comeces por “qual endpoint existe?”. Começa por “qual é a origem da verdade?”. Se não souberes responder, vais acabar com dois sistemas a corrigirem o mesmo campo e ninguém confia nos dados.

As quatro formas práticas de integrar com Primavera

Em instalações Cegid Primavera ERP v10 e v11, quando disponível e bem configurada, a Web API é normalmente a primeira opção a avaliar. Mas há cenários em que o SDK, SQL Server ou ficheiros ainda fazem sentido. A escolha não deve ser religiosa.

1. Web API oficial

É a opção preferida para uma aplicação web moderna quando a cobertura funcional chega.

Vantagens concretas:

• Respeita a lógica aplicacional do ERP.
• Evita escrita directa em tabelas internas.
• É mais fácil de isolar atrás de um serviço de integração.
• Casa bem com Node.js 22 LTS.NET 8, Python ou qualquer backend HTTP.

Limitações:

• A cobertura varia por versão, licenciamento e configuração.
• Pode ter latência elevada se o ERP estiver numa rede local ligada por VPN.
• Nem sempre expõe todos os detalhes que uma integração operacional precisa.
• A autenticação e instalação no cliente podem ser mais difíceis do que parecem no ambiente de demonstração.

Antes de desenhar a arquitectura, confirma a versão exacta do Primavera, módulos licenciados, disponibilidade da Web API e documentação aplicável. A documentação técnica pública da Cegid Primavera deve ser o ponto de partida: https://developers.primaverabss.com/

2. SDK ou componente local

O SDK faz sentido quando precisas de funções que a Web API não cobre ou quando a integração tem de viver muito perto do ERP. É comum em cenários onde há lógica específica de documentos, armazéns, lotes, séries ou extensões existentes.

Vantagens:

• Maior acesso ao modelo funcional do ERP.
• Melhor para operações complexas que dependem da lógica interna.
• Pode correr dentro da rede do cliente, sem abrir o ERP ao exterior.

Limitações:

• Maior dependência de Windows, instalação local e versões específicas.
• Deployment mais chato, sobretudo em vários clientes.
• Escala pior do que uma API stateless na cloud.
• Obriga a disciplina forte em logs, actualizações e monitorização.

A arquitectura típica é um conector local instalado junto ao Primavera. Esse conector fala com o ERP via SDK e comunica com a aplicação web por uma fila ou API segura.

3. SQL Server directo

O Primavera assenta tipicamente em SQL Server. Isso tenta muita gente a ligar a aplicação web directamente à base de dados. Para escrita, é quase sempre um erro.

Ler pode ser aceitável em casos limitados: relatórios, analytics, exportações controladas ou sincronizações de dados que a API não expõe. Mesmo assim, usa uma conta só de leitura, vistas próprias quando possível, isolamento transaccional adequado e nunca assumas que o esquema interno é contrato público.

Vantagens:

• Muito rápido para leitura.
• Útil para grandes volumes, por exemplo 10 GB de histórico de vendas.
• Permite queries específicas para relatórios.

Limitações:

• Esquema pode mudar com actualizações.
• Escrita directa ignora validações do ERP.
• Queries mal feitas podem bloquear operação.
• Dificulta suporte com o fornecedor.

Se fores por este caminho, consulta a documentação da Microsoft sobre SQL Server Change Tracking ou CDC. Para SQL Server 2019 e 2022, ambos podem ajudar, mas têm custos operacionais diferentes: https://learn.microsoft.com/en-us/sql/relational-databases/track-changes/about-change-tracking-sql-server

4. Ficheiros, CSV, XML ou SAF-T

Ainda há integrações por ficheiro que funcionam bem. Não são bonitas, mas são previsíveis. Para importações nocturnas, exportação contabilística ou sistemas antigos, pode ser a opção menos arriscada.

Vantagens:

• Simples de auditar.
• Fácil de reprocessar.
• Bom para lotes diários.

Limitações:

• Não serve para experiência interactiva.
• Validação de erros costuma ser pobre.
• Cria atrasos e reconciliação manual.

RPA deve ser o último recurso. Se a integração depende de “clicar” no Primavera como um humano, prepara-te para falhas em actualizações, sessões expiradas e janelas inesperadas.

Arquitectura recomendada para uma aplicação web moderna

A arquitectura que mais gosto para este tipo de integração tem três peças: aplicação web, serviço de integração e conector Primavera.

A aplicação web nunca deve conhecer detalhes do Primavera. Não deve saber séries, tabelas internas, nomes de endpoints específicos ou credenciais do ERP. Deve falar com um serviço de integração através de contratos próprios: criar encomenda, sincronizar cliente, consultar estado de factura.

O serviço de integração fica na cloud, junto da aplicação. Pode ser Node.js 22 LTS.NET 8 ou outra stack com boa observabilidade. Guarda estado de sincronização em PostgreSQL 16 ou numa base equivalente. Gere filas, reprocessamentos, idempotência e mapeamentos.

O conector Primavera fica onde o ERP está. Se o Primavera está na rede do cliente, o conector também deve estar lá. Comunica para fora através de HTTPS, fila gerida ou ligação autenticada. Assim evitas abrir portas de entrada para o ERP.

Um desenho mental simples:

• Browser ou app móvel chama a tua aplicação web.
• A aplicação web grava a intenção localmente, por exemplo “encomenda criada”.
• Um job envia essa intenção para o serviço de integração.
• O serviço de integração chama o conector Primavera.
• O conector executa na Web API ou SDK.
• O resultado volta com identificadores do ERP e estado final.

Isto parece mais pesado do que “chamar o Primavera directamente”, mas paga-se rapidamente quando há falhas. E vai haver falhas: VPN em baixo, licença ocupada, timeout, artigo inexistente, cliente bloqueado, série errada, stock insuficiente.

Para operações síncronas, define orçamentos claros. Numa aplicação web, eu tentaria manter p95 abaixo de 800 ms para operações comuns. Uma chamada ao Primavera através de rede local, VPN e API pode facilmente passar 2 segundos em p95. Para checkout ou criação de encomenda, prefiro aceitar a operação localmente e processar em segundo plano, mostrando “em validação” quando o negócio permitir.

Sincronização, idempotência e origem da verdade

A parte mais subestimada é idempotência. Se a tua app envia a mesma encomenda duas vezes por causa de um timeout, o Primavera não deve acabar com dois documentos.

Cria uma chave externa estável. Pode ser web_order_id, customer_id ou integration_request_id. Essa chave deve viajar até ao Primavera sempre que houver campo próprio, observação técnica ou tabela de extensão. Se não houver sítio limpo para guardar, mantém uma tabela de mapeamento no serviço de integração.

Um modelo mínimo em PostgreSQL 16 pode ser este:

create table primavera_sync_map (
  id bigserial primary key,
  entity_type text not null,
  external_id text not null,
  primavera_id text not null,
  primavera_company text not null,
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now(),
  unique (entity_type, external_id, primavera_company)
);

create table primavera_sync_cursor (
  source_name text primary key,
  cursor_value text not null,
  updated_at timestamptz not null default now()
);

Este modelo não resolve tudo, mas impede uma categoria inteira de problemas: duplicação silenciosa. Também permite reprocessar eventos sem medo.

Para sincronização Primavera para web, tens três estratégias principais:

• Polling por data de alteração: simples, suficiente para muitos casos. Usa janelas sobrepostas, por exemplo voltar sempre 2 minutos atrás, para compensar relógios e transacções demoradas.
• Change Tracking ou CDC em SQL Server: melhor para volume e precisão, mas aumenta acoplamento à base de dados.
• Eventos por extensão no ERP: melhor quando disponível, porque aproxima a integração de eventos reais de negócio.

Atenção ao relógio. Datas sem timezone são uma armadilha clássica. Se a aplicação web guarda UTC e o ERP trabalha em hora local, as transições de horário de Verão podem criar buracos ou duplicados. Guarda cursores por identificador monotónico quando possível. Quando não for possível, usa janelas sobrepostas e deduplicação.

Um job simples deve ter esta forma lógica, não necessariamente este código exacto:

async function syncCustomers() {
  const cursor = await loadCursor("primavera_customers");
  const changed = await primavera.listCustomersChangedSince(cursor);

  for (const customer of changed) {
    await upsertCustomerFromPrimavera(customer);
    await saveMapping("customer", customer.code, customer.primaveraId);
  }

  const nextCursor = calculateSafeCursor(changed, cursor);
  await saveCursor("primavera_customers", nextCursor);
}

A função mais importante aqui é calculateSafeCursor. Se avançares o cursor para “agora” em vez de para o último registo processado com margem de segurança, vais perder alterações em produção.

Segurança e operação em produção

Não exponhas a Web API do Primavera directamente à Internet com uma password longa e esperança. Isto é pedir problemas.

O mínimo aceitável:

• TLS em todas as ligações.
• Autenticação por cliente técnico, com permissões mínimas.
• Segredos guardados em cofre, por exemplo Azure Key Vault, AWS Secrets Manager ou HashiCorp Vault.
• Logs sem NIF, tokens, IBAN, moradas completas ou dados pessoais desnecessários.
• Allowlist de IP quando fizer sentido.
• Rotação de credenciais com processo documentado.
• Separação por empresa, ambiente e tenant.

Se usares OAuth 2.0, lê a especificação relevante em https://www.rfc-editor.org/rfc/rfc6749 e valida o fluxo suportado pela instalação. Muitas integrações empresariais antigas ainda usam padrões que hoje seriam evitados numa app pública. Compensa com isolamento de rede, expiração curta e permissões reduzidas.

Define também limites operacionais. Um ERP não é uma API pública desenhada para 300 RPS. Em muitos cenários, 2 a 10 pedidos por segundo já é mais do que suficiente. Para sincronização, prefere lotes de 100 a 500 registos, com pausa e retry com backoff. Timeouts de 10 a 30 segundos são razoáveis para operações pesadas, mas não devem bloquear pedidos HTTP de utilizadores finais.

Observabilidade não é opcional. Regista cada pedido de integração com:

• Identificador da operação.
• Entidade de negócio.
• Empresa Primavera.
• Estado, tentativa e erro normalizado.
• Latência.
• Identificador devolvido pelo ERP.

Usa RFC 9110 como referência para semântica HTTP quando desenhares a tua API interna: https://www.rfc-editor.org/rfc/rfc9110

A mensagem de erro “falhou ao criar documento” não chega. Precisas de saber se falhou por timeout, validação fiscal, cliente bloqueado, artigo inexistente ou quebra de rede.

Plano de implementação que evita surpresas caras

Eu implementaria por fases.

Primeiro, inventário. Versão exacta do Primavera, módulos, empresas, bases de dados, ambiente de testes, Web API disponível, SDK necessário, responsáveis internos e horários de operação. Sem isto, estás a adivinhar.

Segundo, mapa de dados. Lista campos obrigatórios e opcionais. Define equivalências: cliente web para cliente Primavera, SKU para artigo, morada para entidade, método de pagamento para condição de pagamento, taxa de IVA para regime fiscal.

Terceiro, decide autoridade por campo. O email do cliente pode ser editado na web? A morada fiscal vem sempre do ERP? O preço é calculado pela app ou pelo Primavera? Se duas pessoas puderem editar o mesmo campo em sistemas diferentes, precisas de regra de conflito.

Quarto, cria ambiente de testes com dados parecidos aos reais. Dados perfeitos não testam integrações. Precisas de clientes bloqueados, artigos sem stock, NIF inválido, moradas incompletas, séries fechadas e documentos anulados.

Quinto, implementa um fluxo pequeno de ponta a ponta. Por exemplo, criar cliente e enviar encomenda. Só depois acrescenta facturação, stock e recibos.

Sexto, cria reprocessamento administrativo. Alguém da operação deve conseguir ver falhas e reenviar uma integração corrigida, sem pedir a um programador para correr scripts.

Sétimo, mede. Latência p50, p95 e p99. Taxa de erro. Tempo médio até sincronização. Número de retries. Operações bloqueadas por validação.

Oitavo, documenta decisões. Não num PDF bonito que ninguém lê. Num documento técnico vivo, ligado ao repositório, com contratos, campos, exemplos de payload e regras de negócio.

Armadilhas comuns em produção

A primeira armadilha é escrever directamente nas tabelas do Primavera. Pode funcionar num teste pequeno e falhar quando entram séries, impostos, armazéns, permissões, alterações de versão ou fechos contabilísticos. Para escrita operacional e fiscal, evita.

A segunda é assumir que stock é um número simples. Stock pode depender de armazém, localização, lote, reserva, encomendas pendentes e regras comerciais. Se a web mostra “5 unidades” e o armazém trabalha com reservas, vais vender o que não tens.

A terceira é ignorar documentos anulados ou rectificados. Integrações ingénuas só sincronizam criações. Depois aparecem notas de crédito, anulações e acertos manuais no ERP, e a aplicação web continua a mostrar dívida ou encomendas fechadas incorrectamente.

A quarta é não tratar multiempresa. Muitas instalações Primavera têm várias empresas. O mesmo código de cliente pode existir em mais do que uma. A tua chave de mapeamento deve incluir empresa, não apenas identificador.

A quinta é não separar erros técnicos de erros de negócio. Timeout deve ir para retry automático. “Cliente bloqueado” não deve repetir 100 vezes. Deve ir para fila de intervenção humana.

A sexta é esquecer upgrades. Uma actualização do Primavera, SQL Server ou conector pode mudar comportamento. Antes de actualizar produção, corre uma bateria curta de testes de integração: criar cliente, criar encomenda, consultar documento, anular fluxo de teste, sincronizar alteração.

Conclusão

Integrar Primavera com uma aplicação web moderna é sobretudo um problema de arquitectura e operação, não de endpoints. Escolhe API ou SDK para escrita, usa SQL só com muito critério para leitura, e desenha desde o início para falhas, retries e reconciliação. Se estás a enfrentar um problema parecido, marca uma conversa em https://impact-origin.com/agendamento.