Versão 1.0 — .NET 9.0 · ASP.NET Core

WebMagAPI
API Universal para
ERPs Portugueses

Platform de integração REST que unifica PHC, Primavera, Sage 50c, Sage 100c e XD Software numa única API padronizada — com autenticação, Swagger e Windows Service.

.NET 9.0 ASP.NET Core Windows Service Swagger / OpenAPI Serilog API Key Auth Port 5200 Windows Forms Configurator

WebMagAPI — Console

$ WebMagAPI.exe

╔══════════════════════════════════════════════╗

║ WebMagAPI — API Universal para ERPs ║

║ PHC · Primavera · Sage · XD Software ║

╚══════════════════════════════════════════════╝

[INF] 2025-03-19 14:32:01 Starting WebMagAPI v1.0...

[INF] 2025-03-19 14:32:01 Loading configuration from appsettings.json

[INF] 2025-03-19 14:32:02 PHC Provider initialized ✓

[INF] 2025-03-19 14:32:02 Primavera Provider initialized ✓

[INF] 2025-03-19 14:32:03 Sage 50c Provider initialized ✓

[INF] 2025-03-19 14:32:03 Sage 100c Provider initialized ✓

[INF] 2025-03-19 14:32:04 XD Software Provider initialized ✓

[INF] 2025-03-19 14:32:04 Swagger UI available at http://localhost:5200/swagger

[INF] 2025-03-19 14:32:04 Health check at http://localhost:5200/health

[INF] 2025-03-19 14:32:05 API online on port 5200 ✓

Now listening on: http://localhost:5200

Press Ctrl+C to shut down.

Overview

One API. Five ERPs.

O WebMagAPI elimina a fragmentação de integrações criando uma camada de abstração unificada sobre os principais ERPs portugueses — expondo uma REST API padronizada, documentada e segura.

ERPs Supported

20+

REST Endpoints

100%

REST / JSON

Win

Windows Service

PHC

Portuguese business management software

SQL Server

PRI

Primavera

Primavera BSS ERP — market leader

Local DLL

S50

Sage 50c

Sage 50c — accounting and billing

Local DLL

S100

Sage 100c

Sage 100c — advanced management

DLL + Data

XD Software

XD Software — business management

REST API

🔗

Single Standardized Endpoint

Todos os ERPs partilham os mesmos endpoints /api/{erpId}/artigos, /clientes, /documentos. Muda o erpId, não o código.

🔑

API Key Authentication

Segurança via header X-API-Key. Chave configurável no Configurator ou diretamente no appsettings.json.

📖

Swagger / OpenAPI

Documentation automática em /swagger. Testa todos os endpoints diretamente no browser sem configuração adicional.

⚙️

Windows Service

Funciona como serviço Windows de arranque automático, ou como aplicação de consola para desenvolvimento e debug.

📋

Logging Serilog

Logs estruturados com Serilog. Ficheiros rotativos com retenção de 30 dias. Visíveis na tab Logs do Configurator em tempo real.

🌐

CORS & Health Check

CORS configurado para integrações web. Health check at /health para monitorização por load balancers e ferramentas DevOps.

Interface

Configurator Windows Forms

Aplicação Windows Forms dedicada para configurar e gerir o WebMagAPI — sem editar JSON manualmente. Gestão de ERPs, logs e controlo do serviço numa janela.

WebMagAPI Configurator — v1.0

⚡ WebMagAPI Configurator

API Online — Port 5200 Última sincronização: 14:35:12 5 ERPs configurados

⚙️ General

🔷 PHC

🟡 Primavera

🟢 Sage 50c

🔵 Sage 100c

🟣 XD Software

📋 Logs

Configuration da API

Port API:

API Key:

Log Level:

Service Windows

Nome:

Status: Em execução

Arranque:

CORS & Segurança

Enable CORS

Origens:

Health URL:

WebMagAPI v1.0 — .NET 9.0

Configuration

Tab PHC — Ligação ao ERP

Cada ERP tem a sua tab dedicada com campos de configuração adaptados ao seu método de integração.

WebMagAPI Configurator — Tab PHC

⚡ WebMagAPI Configurator

API Online — Port 5200

⚙️ General

🔷 PHC

🟡 Primavera

🟢 Sage 50c

🔵 Sage 100c

🟣 XD Software

📋 Logs

PHC Software

Enable PHC Connected

Connection String:

Empresa:

Timeout (seg):

✓ Ligação OK — 12ms

Endpoints Disponíveis

              GET /api/phc/artigos
              GET /api/phc/clientes
              GET /api/phc/documentos
              GET /api/phc/stock
              GET /api/phc/familias
            

WebMagAPI v1.0 — .NET 9.0

Método de Integração por ERP

PHC

PHC Software

SQL Server Direct

Connection String completa (SQL Server)

Código de empresa (ex: "001")

Timeout configurável

TrustServerCertificate suportado

PRI

Primavera BSS

Local DLL + Pasta Instalação

Pasta de instalação Primavera

Servidor de base de dados

Empresa e utilizador ERP

Carregamento via reflexão .NET

S50

Sage 50c

Local DLL + Pasta Instalação

Pasta de instalação Sage 50c

Ficheiro de empresa (.s50)

Utilizador e password Sage

Integração via SDK Sage

S100

Sage 100c

Local DLL + Pasta Dados

Pasta de instalação Sage 100c

Pasta de dados da empresa

Credenciais de acesso

Integração via módulos Sage

XD Software

REST API Remota

URL da API XD Software

Utilizador e password

Token de autenticação

Comunicação HTTP/HTTPS

REST API

Swagger UI & Endpoints

Documentation interativa automática via Swagger/OpenAPI. Testa qualquer endpoint directamente no browser em http://localhost:5200/swagger.

http://localhost:5200/swagger

WebMagAPI

API Universal para ERPs Portugueses — PHC · Primavera · Sage · XD Software

v1.0

Autenticação necessária via header X-API-Key

X-API-Key:

Products Gestão de artigos e produtos

▼

GET /api/{erpId}/artigos List products with pagination and filters

GET /api/{erpId}/artigos/{codigo} Obter artigo por código

GET /api/{erpId}/artigos

Parameters

NameInDescription

erpId *pathID do ERP (phc, primavera, sage50c, sage100c, xdsoftware)

paginaqueryNúmero da página (default: 1)

porPaginaqueryItens por página (default: 20, max: 100)

Response 200 — OK

// GET /api/phc/artigos?pagina=1&porPagina=20 // Header: X-API-Key: webmagapi-key-abc123xyz { "sucesso": true, "total": 1284, "pagina": 1, "porPagina": 20, "dados": [ { "codigo": "ART001", "descricao": "Produto Exemplo A", "familia": "ELETRONICOS", "precoVenda": 49.99, "unidade": "UN", "ativo": true }, // ... mais artigos ] }

Customers Gestão de clientes

▶

GET /api/{erpId}/clientes Listar clientes

POST /api/{erpId}/clientes Create new customer

Documents Faturas e documentos comerciais

▶

GET /api/{erpId}/documentos List documents (faturas, guias, etc.)

ERPs Gestão e diagnóstico de ERPs

▶

GET /api/erps Listar todos os ERPs configurados

POST /api/erps/{erpId}/testar Test ERP connection

GET /health Status geral do serviço

Referência de Endpoints

Método	Endpoint	Descrição	Auth
GET	/api/{erpId}/artigos	List products with pagination and filters	🔑 API Key
GET	/api/{erpId}/clientes	Listar clientes do ERP	🔑 API Key
GET	/api/{erpId}/documentos	List documents (faturas, guias)	🔑 API Key
GET	/api/{erpId}/stock	Query stock por artigo/armazém	🔑 API Key
GET	/api/{erpId}/familias	List families de artigos	🔑 API Key
POST	/api/erps/{erpId}/testar	Testar e diagnosticar ligação ao ERP	🔑 API Key
GET	/health	Status geral do serviço WebMagAPI	✓ Público

Monitorização

Logs & Monitorização em Tempo Real

Serilog com ficheiros rotativos de 30 dias. Visualização integrada na tab Logs do Configurator. Níveis de log com código de cores para diagnóstico rápido.

WebMagAPI Configurator — Tab Logs

⚡ WebMagAPI Configurator

API Online — Port 5200

⚙️ General

🔷 PHC

🟡 Primavera

🟢 Sage 50c

🔵 Sage 100c

🟣 XD Software

📋 Logs

Filtro: Logs: logs\webmagapi-2025-03-19.txt

[2025-03-19 14:32:00] [DBG] Inicializando providers de ERP...

[2025-03-19 14:32:01] [INF] WebMagAPI iniciado na porta 5200

[2025-03-19 14:32:01] [INF] PHC Provider initialized com sucesso

[2025-03-19 14:32:02] [INF] Primavera Provider initialized com sucesso

[2025-03-19 14:32:02] [INF] Sage 50c Provider initialized com sucesso

[2025-03-19 14:32:03] [INF] Sage 100c Provider initialized com sucesso

[2025-03-19 14:32:03] [WRN] Provider XD Software: timeout configurado (<30s) pode ser insuficiente

[2025-03-19 14:32:04] [INF] Swagger UI available at http://localhost:5200/swagger

[2025-03-19 14:32:05] [INF] API online — aguardando pedidos HTTP

[2025-03-19 14:33:12] [INF] GET /api/phc/artigos — 200 OK — 45ms — 20 registos

[2025-03-19 14:33:45] [INF] GET /api/primavera/clientes — 200 OK — 78ms — 150 registos

[2025-03-19 14:34:02] [INF] POST /api/erps/sage50c/testar — 200 OK — 123ms

[2025-03-19 14:34:55] [WRN] GET /api/xdsoftware/stock — timeout parcial — 3000ms

[2025-03-19 14:35:10] [ERR] GET /api/sage100c/documentos — Falha de autenticação no ERP

[2025-03-19 14:35:22] [INF] GET /health — 200 OK — 2ms — Healthy

[2025-03-19 14:35:30] [INF] GET /api/phc/familias — 200 OK — 15ms — 42 registos

─────────────────────────────────────────────────

[2025-03-19 14:35:45] [INF] Log rotation: ficheiro webmagapi-2025-03-19.txt (4.2 MB)

█

● INFO: 12 ● WARN: 2 ● ERROR: 1 ● DEBUG: 1 Retenção: 30 dias | Ficheiro atual: 4.2 MB

WebMagAPI v1.0 — .NET 9.0

📁

Ficheiros Rotativos

Logs em logs\webmagapi-YYYY-MM-DD.txt. Retenção automática de 30 dias. Rotação diária com compressão opcional.

🎨

Níveis com Código de Cores

DEBUG (azul) · INFO (verde) · WARN (amarelo) · ERROR (vermelho). Visíveis tanto na consola como no Configurator.

📊

Log por Request

Cada request REST é registado com método, endpoint, status HTTP, tempo de resposta e número de registos retornados.

Architecture

Stack Técnica & Diagrama

Architecture em camadas com separação clara entre a API, os providers de ERP e os clientes. Desenhada para extensibilidade — adicionar um novo ERP é implementar uma interface.

Customers / Consumidores

🌐 Web Apps

📱 Apps Mobile

⚙️ Services Backend

🤖 Automações (n8n, Zapier)

📊 BI / Dashboards

🛒 E-commerce

↓ HTTP/JSON + X-API-Key

WebMagAPI — ASP.NET Core

🔑 API Key Middleware

🛣️ REST Controllers

📖 Swagger / OpenAPI

❤️ Health Check

🌐 CORS

📋 Serilog

↓ IErpProvider Interface

Providers de ERP

🔷 PhcProvider
SQL Server

🟡 PrimaveraProvider
Local DLL

🟢 Sage50cProvider
Local DLL

🔵 Sage100cProvider
DLL + Data

🟣 XdSoftwareProvider
REST API

↓ SQL / SDK / HTTP

ERPs Portugueses

PHC
SQL Server DB

Primavera
Engine DLL

Sage 50c
SDK DLL

Sage 100c
SDK DLL

XD Software
REST API

⬡

.NET 9.0

Runtime

🌐

ASP.NET Core

Web Framework

🖥️

Windows Forms

Configurator UI

📋

Serilog

Logging

📖

Swagger

OpenAPI / Docs

⚙️

Win Service

Background Host

🔑

API Key Auth

X-API-Key Header

📄

JSON Config

appsettings.json

Resumo

WebMagAPI
Uma API. Todos os ERPs.

Integra qualquer sistema com os ERPs portugueses líderes de mercado.
Produção-ready. Sem código extra. Sem complexidade desnecessária.

REST API Aberta

Windows Service

Swagger UI

5 ERPs Supported

Serilog 30 dias

API Key Auth

Health Check

.NET 9.0

Windows Forms Configurator

Port 5200

# Instalar e iniciar como serviço Windows
$ WebMagAPI.exe install
$ WebMagAPI.exe start
# API disponível em:
→ http://localhost:5200/swagger
→ http://localhost:5200/health
→ http://localhost:5200/api/{erpId}/artigos

WebMagAPI API Universal paraERPs Portugueses

One API. Five ERPs.

Configurator Windows Forms

Tab PHC — Ligação ao ERP

Swagger UI & Endpoints

Referência de Endpoints

Logs & Monitorização em Tempo Real

Stack Técnica & Diagrama

WebMagAPI
API Universal para
ERPs Portugueses