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

WebMagAPI
API Universal para
ERPs Portugueses

Plataforma 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 Porta 5200 Windows Forms Configurador

WebMagAPI — Console

$ WebMagAPI.exe

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

║ WebMagAPI — API Universal para ERPs ║

║ PHC · Primavera · Sage · XD Software ║

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

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

[INF] 2025-03-19 14:32:01 Carregando configuração de appsettings.json

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

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

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

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

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

[INF] 2025-03-19 14:32:04 Swagger UI disponível em http://localhost:5200/swagger

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

[INF] 2025-03-19 14:32:05 API online na porta 5200 ✓

Now listening on: http://localhost:5200

Press Ctrl+C to shut down.

Visão Geral

Uma API. Cinco 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 Suportados

20+

Endpoints REST

100%

REST / JSON

Win

Windows Service

PHC

Software de gestão empresarial português

SQL Server

PRI

Primavera

ERP Primavera BSS — líder de mercado

DLL Local

S50

Sage 50c

Sage 50c — contabilidade e faturação

DLL Local

S100

Sage 100c

Sage 100c — gestão avançada

DLL + Dados

XD Software

XD Software — gestão empresarial

REST API

🔗

Endpoint Único Normalizado

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

🔑

Autenticação API Key

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

📖

Swagger / OpenAPI

Documentação 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 Configurador em tempo real.

🌐

CORS & Health Check

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

Interface

Configurador 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 Configurador — v1.0

⚡ WebMagAPI Configurador

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

⚙️ Geral

🔷 PHC

🟡 Primavera

🟢 Sage 50c

🔵 Sage 100c

🟣 XD Software

📋 Logs

Configuração da API

Porta API:

API Key:

Log Level:

Serviço Windows

Nome:

Estado: Em execução

Arranque:

CORS & Segurança

Ativar CORS

Origens:

Health URL:

WebMagAPI v1.0 — .NET 9.0

Configuração

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 Configurador — Tab PHC

⚡ WebMagAPI Configurador

API Online — Porta 5200

⚙️ Geral

🔷 PHC

🟡 Primavera

🟢 Sage 50c

🔵 Sage 100c

🟣 XD Software

📋 Logs

PHC Software

Ativar PHC Ligado

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

DLL Local + 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

DLL Local + 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

DLL Local + 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

API REST

Swagger UI & Endpoints

Documentação 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:

Artigos Gestão de artigos e produtos

▼

GET /api/{erpId}/artigos Listar artigos com paginação e filtros

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 ] }

Clientes Gestão de clientes

▶

GET /api/{erpId}/clientes Listar clientes

POST /api/{erpId}/clientes Criar novo cliente

Documentos Faturas e documentos comerciais

▶

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

ERPs Gestão e diagnóstico de ERPs

▶

GET /api/erps Listar todos os ERPs configurados

POST /api/erps/{erpId}/testar Testar ligação ao ERP

GET /health Estado geral do serviço

Referência de Endpoints

Método	Endpoint	Descrição	Auth
GET	/api/{erpId}/artigos	Listar artigos com paginação e filtros	🔑 API Key
GET	/api/{erpId}/clientes	Listar clientes do ERP	🔑 API Key
GET	/api/{erpId}/documentos	Listar documentos (faturas, guias)	🔑 API Key
GET	/api/{erpId}/stock	Consultar stock por artigo/armazém	🔑 API Key
GET	/api/{erpId}/familias	Listar famílias de artigos	🔑 API Key
POST	/api/erps/{erpId}/testar	Testar e diagnosticar ligação ao ERP	🔑 API Key
GET	/health	Estado 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 Configurador. Níveis de log com código de cores para diagnóstico rápido.

WebMagAPI Configurador — Tab Logs

⚡ WebMagAPI Configurador

API Online — Porta 5200

⚙️ Geral

🔷 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] Provider PHC inicializado com sucesso

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

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

[2025-03-19 14:32:03] [INF] Provider Sage 100c inicializado 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 disponível em 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 Configurador.

📊

Log por Request

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

Arquitetura

Stack Técnica & Diagrama

Arquitetura 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.

Clientes / Consumidores

🌐 Web Apps

📱 Apps Mobile

⚙️ Serviços 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
DLL Local

🟢 Sage50cProvider
DLL Local

🔵 Sage100cProvider
DLL + Dados

🟣 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

Configurador 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 Suportados

Serilog 30 dias

API Key Auth

Health Check

.NET 9.0

Windows Forms Configurador

Porta 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

Uma API. Cinco ERPs.

Configurador 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