# Integrations — Blazma LIMS

## Overview

Blazma integrates with 16+ external services spanning payment gateways, government health platforms, EMR/HIS systems, cloud services, and utility APIs.

---

## 1. Payment Gateways

### 1.1 Tamara (BNPL)
| Attribute | Value |
|-----------|-------|
| **Type** | Buy Now Pay Later |
| **Service** | `App\Services\TamaraService` |
| **Controller** | `App\Http\Controllers\TamaraController` |
| **Config Source** | `.env` `TAMARA_API_URL`, `TAMARA_API_TOKEN` OR `PROFILE.TAMARA_TOKEN` (per-profile) |
| **Sandbox URL** | `https://api-sandbox.tamara.co` |
| **Callback Route** | `GET /tamara/order/check` → `WebController::CheckTamaraOrder` |
| **Webhook** | `TamaraController::TamaraFeedback` |
| **Auth** | Bearer JWT token |

**Flow**: Create order on Tamara → Redirect patient → Tamara processes → Callback to `/tamara/order/check`

---

### 1.2 PayFort (Amazon Payment Services)
| Attribute | Value |
|-----------|-------|
| **Type** | Card payment |
| **Service** | `App\Services\PayfortService` |
| **Controller** | `App\Http\Controllers\PayfortController` |
| **Config** | `PAYFORT_MERCHANT_IDENTIFIER`, `PAYFORT_ACCESS_CODE`, `PAYFORT_SHA_TYPE`, `PAYFORT_SHA_REQUEST_PHRASE`, `PAYFORT_SHA_RESPONSE_PHRASE`, `PAYFORT_CURRENCY` |
| **Callback** | `PayfortController::PayFortTransactionFeedback` |
| **Return URL** | `PAYFORT_RETURN_URL` |

**Flow**: FORT tokenization → 3DS authentication → Transaction confirmation callback

---

### 1.3 TAP Payments
| Attribute | Value |
|-----------|-------|
| **Type** | Card payment |
| **Service** | `App\Services\TapService` |
| **Controller** | `App\Http\Controllers\TapController` |
| **Config** | `TAP_PUBLIC`, `TAP_SECRET` (global `.env`) OR `PROFILE.TAP_PUBLIC`, `PROFILE.TAP_SECRET` (per-profile) |
| **Callback** | `TapController::TapFeedback` |

---

### 1.4 NearPay (POS Terminal)
| Attribute | Value |
|-----------|-------|
| **Type** | Physical POS terminal |
| **Service** | `App\Services\NearPayService` |
| **Controller** | `App\Http\Controllers\TerminalController` |
| **Config** | `PROFILE.ENABLE_NEARPAY`, `PROFILE.NEARPAY_PRIVATE_KEY`, `PROFILE.NEARPAY_MERCHANT_ID` |
| **Auth** | JWT with private key |

---

## 2. Government & Healthcare Platforms

### 2.1 ZATCA (Zakat, Tax & Customs Authority)
| Attribute | Value |
|-----------|-------|
| **Purpose** | Saudi mandatory e-invoicing compliance |
| **Services** | `App\Services\Zatca\` (multiple services) |
| **Controller** | `App\Http\Controllers\ZatcaController` |
| **Jobs** | `ZatcaInvoice`, `ZatcaRefund`, `ZatcaB2BInvoice`, `ZatcaB2BCredit`, `ZatcaB2BDebit` |
| **Tables** | `ZATCA_INVOICE`, `ZATCA_B2B_INVOICE`, `ZATCA_HOSPITAL`, `ZATCA_INTEGRATION` |
| **Standards** | UBL 2.1 XML, ECDSA signing, QR code (TLV encoded) |

**Invoice Types**:
- `Simplified Invoice` — B2C (reporting mode)
- `Standard Invoice` — B2B (clearance mode, real-time)
- `Credit Note` — Refunds
- `Debit Note` — Adjustments

**Authentication**: CSR → Certificate → Private key (stored in `ZATCA_INTEGRATION`)

---

### 2.2 NPHIES (National Platform for Health Information Exchange)
| Attribute | Value |
|-----------|-------|
| **Purpose** | Saudi insurance claims, eligibility, pre-authorization |
| **Service** | `App\Services\NphiesService` |
| **Controller** | `App\Http\Controllers\InsuranceController` |
| **Job** | `NphiesResultStatusUpdate` |
| **Tables** | `INSURANCE_CLAIMS`, `INSURANCE_APPROVALS` |
| **Protocol** | FHIR R4 / REST API |

**Operations**:
- Eligibility verification
- Pre-authorization requests
- Claim submission
- Claim status polling
- Result status updates

---

### 2.3 HESN Plus (Health Information Network)
| Attribute | Value |
|-----------|-------|
| **Purpose** | Saudi MOH national health data integration |
| **Service** | `App\Services\HESNPlusService` |
| **Jobs** | `HESNPlusSendData`, `HESNReceive`, `HESNRequisition`, `HESNUpdateResult` |
| **Tables** | `HESN_PLUS_TOKEN`, `HESN_PLUS_DIRECTORATE`, `PROFILE_HESN`, `PROFILE.HESN_PLUS_*` |
| **Auth** | OAuth2 (client credentials) |
| **Token URL** | `HESN_PLU_REQ_TOKEN_URL` (default: `https://api.lean.sa/oauth/token`) |
| **Credentials** | `HESN_PLUS_KEY`, `HESN_PLUS_SECRET` (global) OR per-profile in `PROFILE` table |

**Token Management**: Token stored in `HESN_PLUS_TOKEN`, refreshed before expiry

---

### 2.4 HESN (Legacy)
| Attribute | Value |
|-----------|-------|
| **Purpose** | Legacy HESN integration |
| **Service** | `App\Services\HESNService` |
| **Jobs** | `HESNReceive`, `HESNRequisition` |
| **Config** | Per-profile: `PROFILE.HESN_REQ_URL`, `HESN_REQ_USER`, `HESN_REQ_PASS` |

---

### 2.5 Lean API (Health ID & Practitioner)
| Attribute | Value |
|-----------|-------|
| **Purpose** | Patient health ID verification, practitioner lookup |
| **Service** | `App\Services\LeanAPIService` |
| **Config** | `PROFILE.LEAN_PRACTITIONER_API_KEY/SECRET`, `LEAN_HEALTH_ID_API_KEY/SECRET`, `IS_LEAN_API_ENABLED` |
| **Tokens** | `PROFILE.PRACTITIONER_TOKEN`, `PROFILE.HEALTH_ID_TOKEN` |

---

## 3. EMR / HIS Integrations

### 3.1 Ayenati
| Attribute | Value |
|-----------|-------|
| **Purpose** | Ayenati EMR system integration |
| **Service** | `App\Services\AyenatiService` |
| **Controller** | `App\Http\Controllers\AyenatiController` |
| **Auth Middleware** | `AyenatiTokenAuth` |
| **Config** | `PROFILE.AYENATI_ORGANIZATION_ID` |

---

### 3.2 HL7
| Attribute | Value |
|-----------|-------|
| **Purpose** | Healthcare interoperability messaging |
| **Service** | `App\Services\HL7Service` |
| **Controller** | `App\Http\Controllers\HlController` |
| **Job** | `SendHL7InProcessMessageJob` |
| **Library** | `aranyasen/hl7` |
| **Tables** | `HL7_ERROR_LOGS` |

---

### 3.3 LDM
| Attribute | Value |
|-----------|-------|
| **Purpose** | LDM laboratory information system |
| **Service** | `App\Services\LdmService` |
| **Controller** | `App\Http\Controllers\LdmController` |
| **Auth** | `LdmAuth` middleware |
| **Config** | `PROFILE.ENABLE_LDM_INTEGRATION`, `PROFILE.LDM_HOST` |

---

### 3.4 LiveHealth
| Attribute | Value |
|-----------|-------|
| **Purpose** | LiveHealth EMR integration |
| **Service** | `App\Services\LivehealthService` |
| **Controller** | `App\Http\Controllers\LiveHealthController` |
| **Config** | `PROFILE.LIVEHEALTH_URL`, `PROFILE.LIVEHEALTH_TOKEN`, `PROFILE.LIVEHEALTH_ORG_ID` |

---

### 3.5 HIS (Hospital Information System)
| Attribute | Value |
|-----------|-------|
| **Purpose** | Generic HIS integration |
| **Jobs** | `HisLog`, `HisResultReady` |
| **Tables** | `PROFILE_HIS`, `PROFILE_HIS_ENDPOINT` |
| **Config** | `PROFILE.HIS_ID`, `PROFILE_HIS_ENDPOINT` (configurable per endpoint) |

---

### 3.6 ERP (Dynamic / SAP)
| Attribute | Value |
|-----------|-------|
| **Purpose** | Enterprise resource planning sync |
| **Services** | `App\Services\ERP\` |
| **Controller** | `App\Http\Controllers\ErpController` |
| **Jobs** | `ERPInvoice`, `ERPInvoiceClient`, `ERPInvoiceClientCash`, `ERPRefund`, `ERPRefundClient`, `ERPRefundClientCash`, `ERPMovement` |
| **Tables** | `ERP_INTEGRATION`, `ERP_COMPANIES`, `PROFILE_ERP_CREDENTIAL` |
| **Config** | `ERP_DYNAMIC_AUTH`, `ERP_DYNAMIC_HOST` |

---

### 3.7 MTC
| Attribute | Value |
|-----------|-------|
| **Purpose** | MTC integration |
| **Service** | `App\Services\MTCService` |
| **Job** | `Mtc` |
| **Config** | `PROFILE.IS_MTC`, `PROFILE.MTC_SECRET_KEY` |

---

## 4. Cloud Services

### 4.1 AWS S3 (File Storage)
| Attribute | Value |
|-----------|-------|
| **Purpose** | Store uploaded files, reports, images |
| **Bucket** | `blazma.com` |
| **Region** | `eu-west-1` |
| **Config** | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`, `AWS_BUCKET` |
| **Driver** | `league/flysystem-aws-s3-v3` |
| **Service** | `App\Services\FileService` |

**Used for**: Report PDFs, patient photos, insurance documents, signatures, logos, attachments

---

### 4.2 AWS SES (Email - Production)
| Attribute | Value |
|-----------|-------|
| **Purpose** | Transactional email delivery (production) |
| **Dev Config** | `MAIL_MAILER=log` (no emails sent in dev) |

---

### 4.3 Firebase FCM (Push Notifications)
| Attribute | Value |
|-----------|-------|
| **Purpose** | Mobile push notifications to patients and staff |
| **Service** | `App\Services\FCMService` |
| **Config** | `PROFILE.FCM_SERVER_KEY`, `PROFILE.FCM_SERVICE_ACCOUNT` |
| **Library** | `firebase/php-jwt` |
| **Tables** | `DEVICE_TOKENS` (patients), `SYSTEM_USER_DEVICE_TOKEN` (staff) |

**Token Management**: Device tokens registered on app login, used for targeted push delivery

---

## 5. Communication Services

### 5.1 SMS — Unifonic
| Attribute | Value |
|-----------|-------|
| **Purpose** | SMS notifications |
| **Service** | `App\Services\SMSService` |
| **Job** | `SendSMSJob` |
| **Config** | `PROFILE.UNIFONIC_USER`, `PROFILE.UNIFONIC_PASSWORD`, `PROFILE.UNIFONIC_SENDER_ID`, `PROFILE.IS_UNIFONIC=1` |

---

### 5.2 SMS — ConnectSaudi
| Attribute | Value |
|-----------|-------|
| **Purpose** | Alternative SMS provider |
| **Config** | `PROFILE.CONNECTSAUDI_SENDER_ID`, `PROFILE.IS_CONNECT_SAUDI=1` |

---

### 5.3 SMS — BAB SMS
| Attribute | Value |
|-----------|-------|
| **Purpose** | Alternative SMS provider (BAB) |
| **Config** | `PROFILE.IS_BAB_SMS=1` |

---

### 5.4 WhatsApp
| Attribute | Value |
|-----------|-------|
| **Purpose** | WhatsApp notifications and alerts |
| **Service** | `App\Services\WhatsAppService` |
| **Job** | `SendWhatsAppJob` |
| **Config** | `PROFILE.WHATSAPP_ENABLED`, `PROFILE.WHATSAPP_PROVIDER`, `PROFILE.WHATSAPP_API_KEY`, `PROFILE.WHATSAPP_USER_NAME`, `PROFILE.WHATSAPP_TEMPLATE_CONFIG` |

---

## 6. AI & Intelligence

### 6.1 OpenAI
| Attribute | Value |
|-----------|-------|
| **Purpose** | AI test recommendations based on patient symptoms |
| **Service** | `App\Services\MyHealthAiService` |
| **Job** | `GenerateAiRecommendationJob` |
| **Config** | `OPENAI_API_KEY` |
| **Config** | `PROFILE.ENABLE_AI_RECOMMENDATION`, `PROFILE.AI_AUTO_APPROVE` |
| **Tables** | `END_USER_AI_RECOMMENDATION`, `END_USER_AI_RECOMMENDATION_PACKAGES` |

---

## 7. Hardware / Devices

### 7.1 Scandit (Barcode Scanning)
| Attribute | Value |
|-----------|-------|
| **Purpose** | Mobile barcode scanning for sample tracking |
| **Config** | `SCANDIT_TOKEN` |
| **Usage** | Frontend SDK in mobile/web app |

---

### 7.2 Analyzers (Lab Instruments)
| Attribute | Value |
|-----------|-------|
| **Purpose** | Bidirectional communication with lab analyzers |
| **Protocol** | ASTM / HL7 (defined per `ANALYZER_TYPE_FILE`) |
| **Service** | `LabController` (result receiving) |
| **Tables** | `ANALYZER_TYPE`, `ANALYZER_TYPE_FILE`, `PROFILE_ANALYZER`, `ANALYZER_PACKAGE_REFERENCE` |
| **Config** | `PROFILE.BARCODE_REQUEST`, `PROFILE.ENABLE_BARCODE_ANALYZER` |

---

## 8. Redis

| Attribute | Value |
|-----------|-------|
| **Purpose** | Queue broker + cache |
| **Queue DB** | Redis DB 0 (`REDIS_DB=0`) |
| **Cache DB** | Redis DB 1 (`REDIS_CACHE_DB=1`) |
| **Client** | `phpredis` |
| **Host** | `127.0.0.1:6379` |
| **Monitoring** | Laravel Horizon (`/horizon` dashboard) |

---

## 9. Integration Configuration Reference

Most integrations are configured **per-profile** via the `PROFILE` table, allowing different labs to use different providers. Global fallbacks are in `.env`.

| Integration | Config Location |
|-------------|----------------|
| SMS (Unifonic) | `PROFILE.UNIFONIC_*` |
| SMS (ConnectSaudi) | `PROFILE.CONNECTSAUDI_SENDER_ID` |
| WhatsApp | `PROFILE.WHATSAPP_*` |
| FCM Push | `PROFILE.FCM_SERVER_KEY`, `FCM_SERVICE_ACCOUNT` |
| Email SMTP | `PROFILE.PORT`, `HOST`, `USERNAME`, `PASSWORD`, `MAIL_FROM_*` |
| TAP Payments | `PROFILE.TAP_PUBLIC`, `TAP_SECRET` |
| Tamara | `PROFILE.TAMARA_TOKEN` |
| NearPay | `PROFILE.NEARPAY_PRIVATE_KEY`, `NEARPAY_MERCHANT_ID` |
| HESN | `PROFILE.HESN_REQ_URL`, `HESN_REQ_USER`, `HESN_REQ_PASS` |
| HESN Plus | `PROFILE.HESN_PLUS_*` |
| LiveHealth | `PROFILE.LIVEHEALTH_URL`, `LIVEHEALTH_TOKEN`, `LIVEHEALTH_ORG_ID` |
| LDM | `PROFILE.LDM_HOST` |
| HIS | `PROFILE_HIS`, `PROFILE_HIS_ENDPOINT` |
| ERP | `PROFILE_ERP_CREDENTIAL`, `ERP_INTEGRATION` |
| Lean API | `PROFILE.LEAN_*` |
| ZATCA | `ZATCA_INTEGRATION`, `ZATCA_HOSPITAL` |
| AWS | `.env` only (`AWS_*`) |
| OpenAI | `.env` only (`OPENAI_API_KEY`) |
| Scandit | `.env` only (`SCANDIT_TOKEN`) |