🔌 Integration Patterns
BayanCore connects transactional operations with external entities, local banks, e-commerce storefronts, and Saudi government services using secure, standardized integration patterns.
1. Integration Styles
The system utilizes four main integration styles depending on latency and regulatory requirements:
| Pattern | Latency | Protocol | Primary Use Case |
|---|---|---|---|
| Real-Time API Sync | <2 seconds | HTTPS / REST | ZATCA B2B Invoice Clearance |
| Event Webhooks | <5 seconds | HTTPS / JSON | E-commerce Sales & Payment confirmations |
| Scheduled Polling | Hourly / Daily | REST / GraphQL | GOSI status, Qiwa employee synchronization |
| Batch File Transfer | Monthly | SFTP / SIF format | Wage Protection System (WPS) bank payroll |
2. Government Portals & APIs
Government integrations are non-negotiable for compliance.
[BayanCore Integration Layer]
├── ZATCA Fatoora API (Clearance & PCSIDs) ──> Real-Time TLS
├── Qiwa Portal (Employment Contracts) ──────> API Sync / Web Scraping
├── Muqeem Service (Iqama Status Checks) ────> API Sync / Polling
└── GOSI (Social Insurance Filings) ────────> Monthly API upload
ZATCA Fatoora Integration
- Protocol: REST API over HTTPS.
- Security: Mutual TLS (mTLS) authenticated using the client's production Cryptographic Stamp Identifier (PCSID).
- Downtime Resilience: If the ZATCA API goes offline, the integration layer queues outbound invoices in a local Redis database and periodically retries with exponential backoff, ensuring local operations are not blocked.
Qiwa & Muqeem (MHRSD)
- Employment Verification: Syncs active contracts, employee details, and probation timelines from Qiwa.
- Iqama Expiries: Periodically polls the Muqeem portal to verify residency card validities. The system alerts the HR dashboard 30 days before expiries and auto-drafts renewal requests.
GOSI
- Contribution Audits: Cross-references the company's active employee rosters and salaries against GOSI records to ensure correct monthly calculations and avoid penalties.
3. Banking & Payment Gateways
Local financial system integrations facilitate invoice payments and Wage Protection compliance.
Payment Gateways (Moyasar, PayTabs)
- Mechanism: Integrated into the billing workflow. When an invoice is issued, the customer receives a payment link supporting Mada, Apple Pay, and credit cards.
- Reconciliation: Gateway payment events trigger webhooks that record payment entries in ERPNext and auto-reconcile the ledger.
Open Banking (ISO 20022) & Bank Feeds
- Statement Ingestion: Syncs statements from Saudi banks (such as Al Rajhi, SNB, Riyad Bank) via direct Open Banking API connections or secure SFTP exports.
- SIF (Wage Protection File) Uploads: Generates bank-compliant
.SIFpayroll files to be uploaded to bank business portals, conforming to Saudi Wage Protection rules.
4. E-Commerce Integrations (Salla, Zid)
For trading businesses, BayanCore maintains real-time synchronization with local e-commerce platforms.
- Order Sync: Webhooks from Salla or Zid trigger automatic Sales Order drafting in BayanCore.
- Inventory Reconciliation: Stock updates in the warehouse trigger outbound inventory syncs to the online storefront, preventing stockouts and double-selling.