SAP Business One QuePagar Integration

A comprehensive integration solution that automatically synchronizes SAP Business One documents (Invoices and Credit Notes) with the QuePagar platform. This solution provides both automated synchronization via a Windows Service and on-demand querying via a RESTful Web API.

🚀 Features

• Automated Synchronization: Windows Service that runs on a configurable schedule
• RESTful API: On-demand document querying and synchronization
• Robust Delta Updates: Uses UDFs to track last sent timestamps, preventing data loss
• Comprehensive Error Handling: Detailed logging and error recovery
• JWT Authentication: Secure API access with token-based authentication
• SAP DI API Integration: Full integration with SAP Business One's Data Interface API
• Configurable: Easy configuration via appsettings.json files

📋 Prerequisites

• SAP Business One 10.0 or higher
• .NET 6.0 Runtime
• SQL Server (for SAP B1 database)
• Windows Server 2016 or higher (for Windows Service)
• QuePagar API access and credentials

🏗️ Architecture

The solution consists of four main components:

1. SAPQuePagarModels: Data models and DTOs
2. SAPQuePagarDataAccess: SAP DI API integration and data access layer
3. SAPQuePagarService: Windows Service for automated synchronization
4. SAPQuePagarWebAPI: RESTful Web API for on-demand operations

📦 Installation

1. SAP Business One Setup

First, run the setup scripts to create the required User Defined Tables and Fields:

-- Run these scripts in your SAP B1 database
-- 1. CreateUserDefinedTables.sql
-- 2. CreateUserDefinedFields.sql (or use the DI API script)

2. Configure User Defined Fields

Create the following UDFs in SAP Business One:

Business Partner (OCRD) UDFs:

• U_IsAffiliated (Alphanumeric, 1 char, Y/N)
• U_QuePagarLastSync (Date)

Invoice (OINV) UDFs:

• U_QuePagarLastSent (Date)
• U_QuePagarStatus (Alphanumeric, 20 chars)
• U_QuePagarError (Alphanumeric, 255 chars)
• U_QuePagarDocId (Alphanumeric, 50 chars)

Credit Note (ORIN) UDFs:

• U_QuePagarLastSent (Date)
• U_QuePagarStatus (Alphanumeric, 20 chars)
• U_QuePagarError (Alphanumeric, 255 chars)
• U_QuePagarDocId (Alphanumeric, 50 chars)

3. Build the Solution

# Clone or download the solution
cd "SAP Business One Simple Program Development"

# Restore NuGet packages
dotnet restore

# Build the solution
dotnet build

4. Configure the Applications

Windows Service Configuration

Edit SAPQuePagarService/appsettings.json:

{
  "IntegrationConfig": {
    "QuePagarApiKey": "YOUR_QUEPAGAR_API_KEY",
    "QuePagarBaseUrl": "https://quepagar.com/api/v1",
    "SAPServer": "YOUR_SAP_SERVER",
    "SAPDatabase": "YOUR_SAP_DATABASE",
    "SAPUsername": "YOUR_SAP_USERNAME",
    "SAPPassword": "YOUR_SAP_PASSWORD",
    "SyncIntervalMinutes": 30,
    "JwtSecretKey": "YOUR_JWT_SECRET_KEY_AT_LEAST_32_CHARACTERS"
  }
}

Web API Configuration

Edit SAPQuePagarWebAPI/appsettings.json:

{
  "IntegrationConfig": {
    "QuePagarApiKey": "YOUR_QUEPAGAR_API_KEY",
    "QuePagarBaseUrl": "https://quepagar.com/api/v1",
    "SAPServer": "YOUR_SAP_SERVER",
    "SAPDatabase": "YOUR_SAP_DATABASE",
    "SAPUsername": "YOUR_SAP_USERNAME",
    "SAPPassword": "YOUR_SAP_PASSWORD",
    "JwtSecretKey": "YOUR_JWT_SECRET_KEY_AT_LEAST_32_CHARACTERS"
  },
  "JwtSettings": {
    "SecretKey": "YOUR_JWT_SECRET_KEY_AT_LEAST_32_CHARACTERS",
    "Issuer": "SAPQuePagarIntegration",
    "Audience": "QuePagarAPI",
    "ExpirationMinutes": 60
  }
}

5. Install and Run

Windows Service

# Publish the service
dotnet publish SAPQuePagarService -c Release -o ./publish

# Install as Windows Service
sc create "SAPQuePagarIntegration" binPath="C:\path\to\publish\SAPQuePagarService.exe"
sc start "SAPQuePagarIntegration"

Web API

# Run the Web API
dotnet run --project SAPQuePagarWebAPI

# Or publish and run
dotnet publish SAPQuePagarWebAPI -c Release -o ./publish
dotnet ./publish/SAPQuePagarWebAPI.dll

🔧 Configuration

Affiliated Suppliers Setup

1. Open SAP Business One
2. Go to Business Partners
3. Edit a supplier and set U_IsAffiliated to "Y"
4. Add the supplier to the @AFFILIATEDSUPPLIERS table:

INSERT INTO [@AFFILIATEDSUPPLIERS] 
(Code, Name, U_CardCode, U_CardName, U_IsActive, U_CreatedDate)
VALUES 
('SUP001', 'Supplier 1', 'S00001', 'Supplier Name', 'Y', GETDATE())

Sync Settings

Configure sync behavior in the @QUEPAGARSETTINGS table:

-- Update sync interval (in minutes)
UPDATE [@QUEPAGARSETTINGS] 
SET U_SettingValue = '15' 
WHERE U_SettingKey = 'SyncIntervalMinutes'

-- Enable/disable logging
UPDATE [@QUEPAGARSETTINGS] 
SET U_SettingValue = 'true' 
WHERE U_SettingKey = 'EnableLogging'

📡 API Usage

Authentication

Get a JWT token:

curl -X POST "https://your-api-url/api/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_sap_username",
    "password": "your_sap_password",
    "company": "your_company"
  }'

Query Documents

Query specific documents:

curl -X POST "https://your-api-url/api/documents/query" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "docIds": ["12345", "67890"]
  }'

Sync Documents

Sync specific documents with QuePagar:

curl -X POST "https://your-api-url/api/documents/sync" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "docIds": ["12345", "67890"]
  }'

Get Sync Status

curl -X GET "https://your-api-url/api/documents/status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

🔍 Monitoring and Logging

Log Files

Logs are written to the configured directory (default: C:\Logs\SAPQuePagarIntegration):

• SAPQuePagarService.log - Windows Service logs
• SAPQuePagarWebAPI.log - Web API logs
• Integration.log - Integration operation logs

Event Viewer

The Windows Service logs to the Windows Event Viewer under:

• Source: SAPQuePagarIntegration
• Log: Application

Health Checks

• Web API Health: GET /health
• Service Status: Check Windows Services console

🛠️ Troubleshooting

Common Issues

1. SAP Connection Failed

   • Verify SAP server credentials
   • Check SAP server accessibility
   • Ensure DI API is properly installed

2. QuePagar API Errors

   • Verify API key is correct
   • Check network connectivity
   • Review API rate limits

3. Documents Not Syncing

   • Check if suppliers are marked as affiliated
   • Verify document status is "Open"
   • Review UDF values

4. Service Won't Start

   • Check configuration files
   • Verify .NET 6.0 is installed
   • Review Windows Event Log

Debug Mode

Enable debug logging by setting:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

📊 Data Flow

1. Windows Service runs on schedule
2. Connects to SAP using DI API
3. Queries affiliated suppliers from @AFFILIATEDSUPPLIERS table
4. Fetches documents where UpdateDate > U_QuePagarLastSent or U_QuePagarLastSent IS NULL
5. Transforms documents to QuePagar format
6. Sends to QuePagar API with authentication
7. Updates UDFs only on successful transmission
8. Logs results for monitoring

🔒 Security

• JWT tokens for API authentication
• SAP credentials validation
• Configurable CORS policies
• Secure configuration management
• No hardcoded credentials

📈 Performance

• Configurable batch sizes
• Efficient delta updates
• Connection pooling
• Async operations
• Memory management

🤝 Support

For support and questions:

1. Check the troubleshooting section
2. Review log files
3. Contact the development team
4. Submit issues via the project repository

📄 License

This project is proprietary software. All rights reserved.

---

Version: 1.0.0
Last Updated: December 2024
Compatibility: SAP Business One 10.0+, .NET 6.0+