Skip to main content

🔌 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:

PatternLatencyProtocolPrimary Use Case
Real-Time API Sync<2 secondsHTTPS / RESTZATCA B2B Invoice Clearance
Event Webhooks<5 secondsHTTPS / JSONE-commerce Sales & Payment confirmations
Scheduled PollingHourly / DailyREST / GraphQLGOSI status, Qiwa employee synchronization
Batch File TransferMonthlySFTP / SIF formatWage 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 .SIF payroll 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.