Como integrar a API do Primavera: guia para V10 e cloud

O que é a API do Primavera e o que permite ligar ao ERP

A API do Primavera é a camada que permite a outras aplicações consultar informação do ERP, executar operações e, quando autorizado, criar, alterar ou remover dados. No Cegid Primavera ERP V10, a API cobre os módulos funcionais do produto e disponibiliza serviços sobre entidades como clientes, artigos, documentos, movimentos contabilísticos ou recursos humanos.

Na prática, isto permite integrar o Primavera com sistemas que precisam de trocar informação com o ERP sem depender de introdução manual de dados. Uma encomenda recebida numa loja online pode, por exemplo, originar um documento no Primavera, enquanto preços, artigos ou informação de clientes podem seguir no sentido contrário.

Web API, extensibilidade e SDK: as portas de entrada no Primavera

Existem diferentes formas de trabalhar com o Primavera, e a escolha depende sobretudo de onde corre a integração e do nível de controlo necessário.

A Web API é normalmente a opção mais indicada quando um sistema externo precisa de comunicar com o ERP através de serviços REST. No Primavera V10, expõe grande parte dos métodos da API nativa através de endpoints HTTP, permitindo integrar aplicações desenvolvidas noutras tecnologias e até executadas noutros sistemas operativos.

A extensibilidade serve para adaptar o comportamento do próprio ERP. É possível criar funcionalidades específicas, trabalhar com campos e tabelas de utilizador, acrescentar interfaces e reagir a eventos do motor. A V10 disponibiliza também eventos através da API, o que permite executar lógica própria antes ou depois de determinadas operações.

Já o que muitas equipas tratam como SDK do Primavera corresponde, na prática, às bibliotecas, assemblies, entidades e serviços .NET disponibilizados para desenvolver diretamente sobre a API e a plataforma de extensibilidade. Esta abordagem oferece um nível de controlo mais próximo do motor do ERP, mas cria também uma dependência maior da tecnologia e do ambiente Primavera.

Módulos e dados do Primavera acessíveis pela Web API

A Web API da V10 acompanha a organização funcional do ERP. Cada rota identifica o módulo, a entidade e o serviço que será executado. A documentação oficial apresenta, entre outros, estes módulos disponíveis:

O acesso efetivo depende dos módulos instalados, do licenciamento, dos serviços disponíveis na versão utilizada e das permissões atribuídas ao utilizador. A própria Web API respeita as definições de acesso configuradas no administrador do ERP.

CRM, loja online e apps: o que se costuma ligar ao Primavera

Uma integração pode fazer do Primavera o sistema onde ficam os dados financeiros e operacionais, enquanto outras aplicações continuam responsáveis pela experiência comercial, pelo comércio eletrónico ou por processos específicos.

Um CRM pode enviar novos clientes e encomendas para o ERP. Uma loja online pode consultar artigos, preços e disponibilidade e depois comunicar as vendas efetuadas. Uma aplicação de equipas no terreno pode obter informação de clientes e registar operações que terão posteriormente impacto no Primavera.

Exemplo ilustrativo de uma integração com CRM:

CRM → cliente ou oportunidade convertida → camada de integração → Web API do Primavera → criação ou atualização da entidade no ERP

No sentido inverso, a integração pode devolver ao CRM informação relevante registada no Primavera, como dados atualizados do cliente ou o estado de determinados documentos. O importante é definir antecipadamente qual sistema é responsável por cada tipo de informação e quais operações podem efetivamente escrever no ERP. Isso evita duplicações, conflitos e integrações que funcionam tecnicamente, mas deixam de ter uma fonte de dados clara.

Primavera V10 ou cloud: que Web API usar em cada caso

A forma de integrar depende primeiro do produto que está a ser utilizado. No Primavera ERP V10, a Web API corre na infraestrutura do cliente e comunica com a instalação local do ERP. Nos produtos cloud, como Jasmin e ROSE, a integração é feita através das APIs disponibilizadas online, depois de registar uma aplicação e configurar a respetiva autorização.

Embora ambas as abordagens usem serviços web, não são APIs intercambiáveis. A instalação, a autenticação e a estrutura dos endpoints são diferentes. Por isso, antes de começar a desenvolver, é importante identificar exatamente o produto e a versão que irão receber ou fornecer os dados.

Web API do Primavera V10, instalada no servidor da empresa

Na V10, a Web API é um componente instalado na infraestrutura onde o Primavera é utilizado. É necessário ter o módulo correspondente, configurar o IIS e indicar à Web API onde se encontra a instalação do ERP. A documentação da Cegid confirma que a API corre num servidor local, embora esse servidor não tenha obrigatoriamente de ser a mesma máquina onde está instalado o ERP. Pode existir um servidor dedicado, desde que a configuração aponte corretamente para a instalação.

As rotas seguem uma estrutura própria do ERP, por exemplo:

http://servidor/WebApi/{modulo}/{entidade}/{servico}/

Isto significa que uma aplicação externa não comunica diretamente com a base de dados do Primavera. Comunica com a Web API, que por sua vez utiliza a API do produto e as respetivas regras de negócio.

Esta arquitetura também coloca mais responsabilidade na empresa ou no parceiro responsável pela infraestrutura. IIS, certificados, rede, atualizações e exposição segura do serviço têm de ser considerados na implementação.

Web API do Jasmin e do ROSE, com aplicação registada na cloud

No Jasmin e no ROSE, o ponto de partida é diferente. Em vez de instalar uma Web API num servidor da empresa, o programador regista uma aplicação no ecossistema cloud e define a forma como essa aplicação poderá autenticar-se. Para desenvolvimento e testes, a App tem ainda de ser associada à subscrição cujos dados pretende utilizar. Sem essa associação, os pedidos podem ser recusados por falta de autorização.

A autenticação destas APIs utiliza OAuth 2.0. O registo da aplicação fornece os elementos necessários para obter um token de acesso, dependendo do fluxo de autenticação escolhido. Esse token acompanha depois os pedidos enviados à API.

As rotas também refletem o modelo cloud. Em vez de apontarem para um servidor Primavera da empresa, identificam elementos como a conta e a subscrição:

https://baseurl/api/{account}/{subscription}/{module}/{resource}/

A conta identifica o cliente, a subscrição determina o contexto ao qual a aplicação tem acesso e o recurso representa os dados ou operações que se pretendem utilizar.

Assim, escolher a API correta não é apenas uma questão de preferência técnica. Se a integração é com um Primavera ERP V10, deve seguir a arquitetura e os endpoints da Web API V10. Se o sistema de origem ou destino é Jasmin ou ROSE, deve seguir o modelo de aplicações, subscrições e autenticação OAuth 2.0 disponibilizado para os produtos cloud.

Como integrar a API do Primavera passo a passo

Uma integração sólida começa antes do primeiro pedido HTTP. É preciso perceber que versão do Primavera está em uso, que dados vão circular e quem será responsável por cada operação. Só depois faz sentido configurar autenticação e começar a testar endpoints.

1. Confirmar a versão, os módulos e onde o ERP está instalado

Na V10, confirme primeiro se o módulo Web API está disponível e onde ficará instalado. A Cegid indica que a Web API necessita de IIS e corre na infraestrutura do cliente, embora possa estar num servidor diferente daquele onde está instalado o ERP.

Checklist de pré-requisitos:

• Produto identificado: Primavera ERP V10, Jasmin ou ROSE
• Módulos necessários licenciados e disponíveis
• Utilizador com permissões adequadas
• Empresa, instância e linha do produto conhecidas na V10
• IIS e módulo Web API preparados na V10
• Aplicação registada e associada à subscrição no Jasmin ou ROSE
• Conectividade entre a aplicação e a API confirmada
• Ambiente de testes separado da operação real, sempre que possível

2. Definir que entidades a integração lê e escreve

Antes de programar, liste os dados que cada sistema necessita de consultar e aqueles que poderá alterar. Por exemplo, uma loja online pode ler artigos e disponibilidade, mas escrever clientes e documentos de venda.

Também deve ficar definido qual aplicação é a fonte principal de cada dado. Se tanto o CRM como o Primavera puderem alterar livremente o mesmo cliente, será necessário decidir como tratar conflitos, duplicados e atualizações simultâneas.

Começar com este mapa reduz o número de endpoints necessários e evita conceder à integração mais acesso do que realmente precisa.

3. Preparar o acesso: instalar a Web API ou registar a aplicação

No Primavera V10, é necessário instalar e configurar a Web API, preparar o IIS e garantir que o utilizador utilizado pela integração tem acesso aos serviços pretendidos. As permissões configuradas no ERP condicionam aquilo que esse utilizador consegue executar através da API.

No Jasmin e no ROSE, o processo passa pelo registo de uma App. É nessa configuração que se escolhe o fluxo OAuth e, quando aplicável, se gera o Client Secret. Para desenvolvimento e testes, a aplicação também tem de ser associada à subscrição que pretende consultar, caso contrário a API pode responder com HTTP 403.

4. Pedir o token de autenticação OAuth 2.0

Na Web API V10, a autenticação começa com um pedido ao endpoint /WebApi/token. O token recebido é depois enviado nos pedidos seguintes através do header Authorization: Bearer {access_token}.

Um pedido simplificado pode ter esta forma:

curl -X POST "http://servidor:2018/WebApi/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=UTILIZADOR" \
  -d "password=PASSWORD" \
  -d "company=EMPRESA" \
  -d "instance=Default" \
  -d "line=evolution" \
  -d "grant_type=password" \
  -d "sessionkey=INTEGRACAO_001"

A sessionkey merece atenção especial. Deve identificar um contexto de integração independente e não deve ser partilhada indiscriminadamente entre utilizadores ou processos concorrentes.

No Jasmin e no ROSE, os parâmetros dependem do fluxo escolhido no registo da App. A autenticação cloud utiliza o serviço de identidade da Primavera e elementos como Client ID, Client Secret, redirect URI e scope. A documentação indica, por exemplo, o scope application para Jasmin e rose-api para ROSE.

5. Explorar os endpoints no Swagger e testar no Postman

Na versão 2 da Web API V10, o Swagger é a principal interface para descobrir os métodos disponíveis, consultar parâmetros e experimentar pedidos. O endereço predefinido é /WebApi/swagger/ui/index, e é possível selecionar o módulo e a versão que se pretende explorar.

As rotas v2 seguem esta estrutura:

http://servidor:2018/WebApi/v2/{modulo}/{entidade}/{servico}/

GET /WebApi/v2/{modulo}/{entidade}/{servico}/
POST /WebApi/v2/{modulo}/{entidade}/{servico}/
PUT /WebApi/v2/{modulo}/{entidade}/{servico}/
DELETE /WebApi/v2/{modulo}/{entidade}/{servico}/

Authorization: Bearer {access_token}
Accept: application/json

A versão 2 acrescenta v2 antes do módulo e utiliza os métodos HTTP GET, POST, PUT e DELETE conforme a operação. Também uniformiza a estrutura das respostas.

O Postman é útil para validar primeiro a autenticação e depois testar cada chamada isoladamente. A Cegid disponibiliza uma coleção para o Primavera ERP V10 com variáveis como URL da API, utilizador, empresa e instância, o que permite confirmar a comunicação antes de implementar essa lógica na aplicação final.

6. Tratar a expiração do token, os pedidos em paralelo e o logout

Na V10, o access_token tem por predefinição cerca de 20 minutos de validade, embora o valor possa ser alterado através de TokenExpirationMinutes no Web.config. Quando expira, a API devolve HTTP 401 e deve ser solicitado um novo token. Para reutilizar o mesmo contexto, a Cegid recomenda enviar o token expirado no header Authorization durante a renovação.

A concorrência também deve ser planeada. Por predefinição, a V10 protege um mesmo contexto contra chamadas simultâneas. Integrações com vários workers ou processos paralelos devem utilizar tokens e sessionkeys distintos para isolar os contextos, em vez de fazer vários pedidos concorrentes sobre a mesma sessão.

Por fim, expirar o token não significa libertar automaticamente o contexto de integração. A Web API disponibiliza um endpoint de logout para terminar esse contexto e libertar recursos do IIS e sessões associadas ao ERP:

POST /WebApi/Base/Logout
Authorization: Bearer {access_token}

O logout explícito é particularmente importante em integrações contínuas ou com elevada carga, onde deixar contextos antigos ativos pode acumular recursos desnecessariamente.

Quando a Web API não chega: estender o Primavera à medida

A Web API cobre grande parte das operações necessárias numa integração com o Primavera V10, mas há situações em que os endpoints standard não resolvem todo o processo. Pode ser necessário executar uma operação que não está publicada, combinar vários passos numa única chamada ou aplicar regras específicas do negócio.

Nesses casos, o Primavera permite ir além da Web API standard através de dois mecanismos diferentes. É possível criar serviços REST próprios dentro da Web API ou utilizar a extensibilidade do motor para executar código quando determinadas operações acontecem no ERP.

Criar endpoints próprios numa extensão da Web API

A Cegid permite estender a Web API V10 com novos métodos quando a funcionalidade necessária não está disponível nativamente. Esses métodos ficam integrados na própria Web API e podem utilizar o contexto do ERP, evitando a necessidade de desenvolver um serviço web completamente separado.

Um caso típico seria uma aplicação externa precisar de executar uma operação composta que a API standard não disponibiliza diretamente. Em vez de obrigar essa aplicação a fazer várias chamadas e reproduzir lógica do ERP, pode ser criado um endpoint específico que concentra o processo.

A extensão é desenvolvida como uma biblioteca .NET Framework. A classe que publica o serviço deve funcionar como um ApiController, usar a configuração de rotas adequada e implementar os métodos HTTP necessários. A documentação oficial mostra, por exemplo, um endpoint personalizado que utiliza a API de Vendas para gerar um documento em PDF.

Depois de compilada, a assembly é colocada na pasta bin da Web API. O código personalizado pode então recorrer ao ProductContext para aceder ao contexto do ERP e aos respetivos serviços.

Isto permite criar operações como:

• devolver informação calculada que não existe num endpoint standard;
• executar vários passos do ERP através de uma única chamada;
• disponibilizar uma função específica de um processo interno;
• transformar ou preparar dados antes de os devolver ao sistema externo.

Mesmo num endpoint desenvolvido à medida, convém manter autenticação, validação de parâmetros e regras de negócio do Primavera. O objetivo da extensão é acrescentar uma camada adequada ao processo, não contornar os mecanismos do ERP.

Reagir a eventos do ERP com a extensibilidade do motor

Nem todas as integrações precisam de começar com um pedido vindo de fora. Às vezes, o requisito é executar uma ação automaticamente quando algo acontece dentro do próprio Primavera.

A V10 disponibiliza eventos ao nível da API através do mecanismo de extensibilidade do motor. Uma extensão pode subscrever eventos associados aos serviços do ERP e executar código em momentos concretos do processo. A documentação oficial apresenta, por exemplo, o evento AntesDeGravar no serviço de Vendas.

Isto permite criar comportamentos como validar informação antes de gravar um documento, completar dados automaticamente ou desencadear uma operação adicional quando um processo do ERP é executado.

A lógica pode ser pensada assim:

Operação no Primavera → evento do motor → extensão personalizada → validação ou ação adicional

Para implementar este modelo, o projeto referencia as assemblies de extensibilidade e os componentes do módulo que pretende acompanhar. A classe herda depois do serviço correspondente e implementa os eventos necessários. A assembly compilada tem de ser registada no ERP para que a extensão seja carregada.

A diferença para um endpoint personalizado é importante. O endpoint é chamado explicitamente por outro sistema. Um evento do motor é executado em resposta a uma operação do próprio ERP. Quando a integração precisa de receber pedidos externos, faz sentido olhar para a extensão da Web API. Quando precisa de reagir ao que acontece dentro do Primavera, a extensibilidade do motor tende a ser o mecanismo mais adequado.

Erros que comprometem uma integração com o Primavera

Uma integração pode funcionar nos primeiros testes e, ainda assim, ficar frágil em produção. No Primavera, alguns dos problemas mais sérios surgem quando se contornam as regras do ERP, se expõe a Web API sem proteção suficiente ou se assume que todas as versões da API funcionam da mesma forma.

Escrever diretamente na base de dados SQL

Alterar diretamente as tabelas SQL do Primavera pode parecer uma forma rápida de criar clientes, atualizar artigos ou inserir documentos. O problema é que uma operação do ERP raramente corresponde apenas à gravação de uma linha numa tabela.

A API do Primavera trabalha sobre os serviços e regras de negócio do ERP. É essa camada que deve ser utilizada para operações que alteram informação funcional. A própria arquitetura da Web API foi criada para disponibilizar através de REST os serviços da API do produto.

Erro comum: usar SQL como se fosse a API

Consultar diretamente uma base de dados para reporting controlado é um cenário diferente de escrever nela. Fazer INSERT, UPDATE ou DELETE diretamente sobre tabelas internas pode ignorar validações, relações entre entidades e lógica executada pelo ERP. Para criar ou alterar dados de negócio, prefira a Web API, a API nativa ou os mecanismos de extensibilidade disponibilizados pelo Primavera.

Esta separação torna a integração mais previsível e reduz também a dependência da estrutura interna da base de dados, que pode evoluir com atualizações do produto.

Abrir a Web API da V10 à internet sem proteção

Na V10, a Web API corre na infraestrutura do cliente e depende de IIS. Pode estar instalada num servidor dedicado, o que facilita a criação de arquiteturas de integração, mas também significa que a segurança da publicação do serviço fica sob controlo dessa infraestrutura.

Publicar diretamente uma instalação interna na internet apenas para permitir o acesso de um CRM, loja online ou aplicação móvel cria uma superfície de exposição desnecessária. O facto de a Web API exigir autenticação não substitui os restantes controlos de segurança.

Quando o acesso remoto é necessário, a arquitetura deve prever HTTPS, certificados válidos, regras de firewall e uma exposição tão limitada quanto possível. Dependendo do cenário, podem ainda fazer sentido uma VPN, reverse proxy, gateway ou restrições por rede. As credenciais e tokens nunca devem ficar embutidos em aplicações cliente sem proteção adequada.

O princípio é simples: a aplicação externa deve conseguir chegar aos endpoints necessários, mas isso não implica tornar toda a Web API livremente acessível a partir da internet.

Ignorar a versão 2 da Web API e as rotas que mudaram

Outro erro frequente é reutilizar exemplos antigos sem confirmar para que versão da Web API foram escritos. A versão 2 introduziu alterações relevantes na estrutura dos endpoints e no modo como pedidos e respostas são tratados.

Na v2, uma resposta segue uma estrutura comum com campos como Version, StatusCode, ErrorMessage e Results. O Swagger passou também a desempenhar um papel central na descoberta e teste dos métodos disponíveis.

Por isso, alterar apenas o URL de uma integração antiga para acrescentar /v2/ pode não ser suficiente. O código deve ser revisto quanto aos verbos HTTP utilizados, formato das respostas, tratamento de erros e gestão de pedidos concorrentes. Confirmar a versão logo no início evita desenvolver sobre exemplos que já não correspondem ao comportamento esperado da Web API.

Conector pronto ou integração à medida com o Primavera

Depois de confirmar que o Primavera disponibiliza os dados e operações necessários, falta decidir como construir a ligação. Nem todas as integrações justificam desenvolvimento de raiz. Para processos comuns, um conector já existente pode reduzir significativamente o trabalho inicial. Quando existem regras próprias, fluxos complexos ou necessidades que ultrapassam os endpoints standard, uma integração à medida oferece maior controlo.

A decisão deve considerar não apenas o custo de implementação, mas também manutenção, atualizações do ERP, tratamento de erros, volume de dados e facilidade de alterar o processo no futuro.

Quando um conector de mercado é suficiente

Um conector pronto faz sentido quando a necessidade corresponde a um fluxo relativamente comum e o produto suporta explicitamente a versão e os módulos do Primavera utilizados.

Imagine, por exemplo, uma loja online que apenas precisa de sincronizar artigos, clientes, stocks e documentos através de operações já previstas pelo conector. Se os campos necessários estiverem disponíveis, as regras de sincronização forem simples e o fornecedor garantir compatibilidade com o ambiente existente, desenvolver toda a integração de raiz pode acrescentar complexidade sem benefício proporcional.

Antes de escolher, convém confirmar exatamente o que significa "integração com Primavera". Deve ficar claro quais entidades são suportadas, em que sentido os dados circulam, com que frequência são sincronizados e como são tratados erros, duplicados e alterações de versão.

Isto é especialmente importante na V10, porque a Web API é instalada na infraestrutura do cliente e requer o respetivo módulo e IIS configurado. Um conector que dependa da Web API continua, portanto, condicionado por essa infraestrutura e pelas permissões disponíveis no ERP.

Quando compensa desenvolver a integração à medida

O desenvolvimento à medida torna-se mais relevante quando o processo não cabe num fluxo predefinido. Pode ser necessário combinar dados de vários sistemas, transformar informação antes de a gravar, aplicar validações específicas ou controlar com precisão quando cada operação acontece.

A própria arquitetura do Primavera favorece este tipo de cenário. A Web API REST permite integrar o ERP com sistemas externos muito diferentes e expõe a gama funcional do produto através de serviços próprios.

Quando esses serviços não são suficientes, a Cegid permite ainda estender a Web API com novos métodos. Esses endpoints personalizados podem utilizar o mesmo contexto do ERP e implementar funcionalidades que não estão publicadas nativamente.

Uma integração à medida tende, por isso, a justificar-se quando existem regras próprias do negócio, várias aplicações envolvidas, necessidades específicas de segurança ou desempenho, ou operações que um conector comercial não consegue representar corretamente.

Também oferece maior controlo sobre logs, recuperação após falhas, sincronização e evolução do processo. Em contrapartida, esse controlo traz responsabilidade técnica. O código terá de ser testado, documentado e revisto quando houver alterações relevantes no ERP ou na infraestrutura. A escolha não deve ser simplesmente entre "comprar" e "programar", mas entre adaptar o processo às capacidades de um conector ou construir uma integração que siga exatamente o processo necessário.

Perguntas frequentes sobre a Web API do Primavera

A Web API do Primavera V10 tem de estar no mesmo servidor que o ERP?

Não. A Web API V10 é executada na infraestrutura do cliente, mas não tem obrigatoriamente de estar instalada na mesma máquina do ERP.

A Cegid prevê a instalação num servidor dedicado. Nesse cenário, é necessário configurar no Web.Config a chave ERPInstalationPath, para que a Web API conheça a localização da instalação do Primavera. O servidor onde corre a Web API tem também de conseguir aceder aos recursos necessários do ERP. (Developers Network)

Posso ter mais do que uma instância da Web API no mesmo IIS?

Sim. A documentação oficial confirma que é possível executar várias instâncias da Web API V10 no mesmo servidor IIS e também distribuí-las por vários servidores. (Developers Network)

No mesmo IIS, podem ser criadas aplicações Web separadas, cada uma com o seu diretório virtual. Também é possível atribuir application pools diferentes para separar a gestão de recursos.

É importante evitar conflitos nos bindings e portas utilizados. Em ambientes com várias instâncias, convém ainda documentar claramente cada endpoint e respetiva finalidade, para não confundir ambientes, clientes ou integrações. (Developers Network)

Onde ficam os registos de erros da Web API do Primavera V10?

A Web API V10 utiliza NLog para registar atividade, erros e eventos internos. Segundo a documentação atual da Cegid, os logs são guardados por defeito na pasta AplWebAPI. (Developers Network)

Os registos podem incluir erros internos, problemas de autenticação ou acesso ao ERP e informação sobre os pedidos recebidos. A configuração do logging é feita no Web.Config, através do elemento nlog. (Developers Network)

Também é possível ajustar o nível de detalhe, recorrendo a níveis como Error, Warning, Info ou Debug. Em produção, deve existir atenção ao volume de logs e ao espaço em disco, sobretudo numa Web API que recebe muitos pedidos.

Onde está a documentação oficial da API do Primavera?

A principal referência técnica é a Cegid Developers Network, onde a documentação está separada por produto e tecnologia.

Para o Primavera ERP V10, existem áreas específicas para Web API, arquitetura, autenticação, Swagger, versão 2, extensibilidade e exemplos de implementação. O Swagger da própria instalação permite ainda consultar os controllers, métodos, parâmetros e respostas efetivamente disponíveis na Web API instalada. (Developers Network)

Para produtos cloud, a documentação possui áreas próprias para Jasmin e ROSE, com os respetivos recursos, rotas e mecanismos de autenticação. A Cegid mantém uma área de documentação API que encaminha para as referências de cada produto cloud. (Developers Network)

Esta separação é importante: ao procurar um endpoint ou exemplo, confirme sempre se a página consultada corresponde a V10, Jasmin ou ROSE. Apesar de todos permitirem integrar aplicações com o ecossistema Primavera/Cegid, a arquitetura, autenticação e formato das APIs não são necessariamente os mesmos.