Crelio Health & Hubble Integration Guide

This document provides comprehensive integration documentation for Crelio Health (Lab Services) and Hubble (FITCOIN Wallet) integrations with the Azodha Platform API.

Table of Contents

• Overview

• Crelio Health Integration

  • Configuration

  • Patient Registration

  • Lab Appointment Booking

  • Webhook Processing

  • API Endpoints

• Hubble Integration

  • Configuration

  • FITCOIN Operations

  • API Endpoints

• Error Handling

• Security Considerations

• Examples

Overview

The Azodha Platform provides seamless integration with:

1. Crelio Health: Lab services integration for patient registration, appointment booking, and automated lab result processing

2. Hubble: FITCOIN wallet integration for wellness rewards and digital currency management

Both integrations follow the platform's standard patterns for external service integration, including webhook processing, error handling, and data synchronization.

Crelio Health Integration

Crelio Health integration enables automated lab services including patient registration, appointment booking with billing, and real-time lab result processing through webhooks.

Configuration

Required Environment Variables

CRELIO_HEALTH_BASE_URL=https://api.creliohealth.com

Integration Setup

1. Organization Integration Configuration:

   {
     "externalProvider": "CRELIO_HEALTH",
     "integrationType": "LABS",
     "apiKey": "your_crelio_api_key",
     "attributes": {
       "organizationIdLH": "your_lab_organization_id"
     }
   }

2. Required Integration Attributes:

   • apiKey: Crelio Health API key for authentication

   • organizationIdLH: Lab organization identifier in Crelio Health system

Invoice Item Configuration

For lab booking, invoice items must include specific Crelio Health attributes:

{
  "attributes": {
    "testID": "TEST_001",
    "testCode": "BLOOD_CBC",
    "integrationCode": "INT_001",
    "dictionaryId": "DICT_001",
    "observationMapping": [
      {
        "testName": "Hemoglobin",
        "observationCodeId": 123,
        "observationGroupId": 456
      }
    ]
  }
}

Patient Registration

Process Flow

1. Patient Registration: Automatically registers patients in Crelio Health when they are created in the platform

2. External ID Mapping: Maps platform consumer UUID to Crelio Health patient ID

3. Data Synchronization: Ensures patient data consistency between systems

API Integration

Endpoint: POST /patientRegister/{apiKey}/

Request Payload:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "mobileNumber": "[phone]",
  "birthDate": "1990-01-01",
  "gender": "MALE",
  "addressLine1": "123 Main St",
  "city": "New York",
  "state": "NY",
  "zipCode": "10001",
  "country": "US"
}

Response:

{
  "code": 200,
  "patientId": 12345,
  "message": "Patient registered successfully"
}

Lab Appointment Booking

Process Flow

1. Invoice Creation: Lab appointment is created with associated invoice

2. Patient Validation: Verifies patient exists in Crelio Health system

3. Bill Registration: Registers lab bill with Crelio Health

4. Appointment Scheduling: Schedules lab appointment

5. External ID Mapping: Maps invoice and appointment IDs between systems

API Integration

Endpoint: POST /LHRegisterBillAPI/{apiKey}/

Request Payload:

{
  "organizationIdLH": "LAB_ORG_001",
  "patientId": 12345,
  "appointmentId": 67890,
  "billId": 11111,
  "testDetails": [
    {
      "testID": "TEST_001",
      "testCode": "BLOOD_CBC",
      "integrationCode": "INT_001",
      "dictionaryId": "DICT_001"
    }
  ],
  "appointmentDate": "2024-01-15T10:00:00Z",
  "patientInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "mobileNumber": "[phone]"
  }
}

Response:

{
  "code": 200,
  "billId": 11111,
  "appointmentId": 67890,
  "patientId": 12345,
  "message": "Bill registered successfully"
}

Webhook Processing

Crelio Health sends webhooks for lab results and observations. The platform processes these automatically.

Lab Report Webhook

Endpoint: POST /webhook/labs/reports

Webhook Payload:

{
  "billId": 11111,
  "Patient Id": 12345,
  "Report Id": 99999,
  "Test Name": "Complete Blood Count",
  "sampleID": "SAMPLE_001",
  "Report Date": "2024-01-16",
  "labName": "Crelio Health Lab",
  "CentreReportId": 88888,
  "reportBase64": "JVBERi0xLjQKJcOkw7zDtsO..."
}

Processing:

1. Validates webhook payload

2. Uploads PDF report to cloud storage

3. Creates file record with health record attributes

4. Notifies care team providers

5. Triggers post-processing events

Lab Observations Webhook

Endpoint: POST /webhook/labs/observations

Webhook Payload:

{
  "billId": 11111,
  "Patient Id": 12345,
  "Report Id": 99999,
  "Test Name": "Complete Blood Count",
  "sampleID": "SAMPLE_001",
  "Report Date": "2024-01-16",
  "labName": "Crelio Health Lab",
  "CentreReportId": 88888,
  "reportFormatAndValues": [
    {
      "value": "14.2",
      "highlight": 0,
      "critical": 0,
      "reportFormat": {
        "testName": "Hemoglobin",
        "descriptionFlag": 0,
        "method": "Automated Analysis"
      }
    }
  ]
}

Processing:

1. Validates webhook payload

2. Maps observation values to platform observation codes

3. Creates observation records

4. Updates file attributes

5. Triggers post-processing events

API Endpoints

Lab Report Webhook

POST /webhook/labs/reports
Content-Type: application/json
Authorization: Bearer <token>
organization_code: <org_code>
organizationid: <org_id>

{
  "billId": 11111,
  "Patient Id": 12345,
  "Report Id": 99999,
  "Test Name": "Complete Blood Count",
  "sampleID": "SAMPLE_001",
  "Report Date": "2024-01-16",
  "labName": "Crelio Health Lab",
  "CentreReportId": 88888,
  "reportBase64": "JVBERi0xLjQKJcOkw7zDtsO..."
}

Lab Observations Webhook

POST /webhook/labs/observations
Content-Type: application/json
Authorization: Bearer <token>
organization_code: <org_code>
organizationid: <org_id>

{
  "billId": 11111,
  "Patient Id": 12345,
  "Report Id": 99999,
  "Test Name": "Complete Blood Count",
  "sampleID": "SAMPLE_001",
  "Report Date": "2024-01-16",
  "labName": "Crelio Health Lab",
  "CentreReportId": 88888,
  "reportFormatAndValues": [...]
}

Hubble Integration

Hubble integration provides FITCOIN wallet functionality for wellness rewards and digital currency management.

Configuration

Required Integration Setup

1. Organization Integration Configuration:

   {
     "externalProvider": "HUBBLE",
     "integrationType": "WALLET",
     "apiKey": "your_hubble_api_key",
     "attributes": {
       "baseUrl": "https://api.hubble.com",
       "clientId": "your_client_id",
       "clientSecret": "your_client_secret"
     }
   }

2. Wallet Configuration:

   • FITCOIN wallet type must be configured for the organization

   • Consumer accounts must be linked to FITCOIN wallets

FITCOIN Operations

Get Coin Balance

Retrieves the current FITCOIN balance for a consumer.

Endpoint: GET /webhooks/hubble/consumers/{consumerId}/balance

Response:

{
  "success": true,
  "data": {
    "consumerId": "consumer-uuid-123",
    "balance": "150.50"
  }
}

Debit Coins

Debits FITCOIN from a consumer's wallet for wellness activities.

Endpoint: POST /webhooks/hubble/consumers/{consumerId}/transactions

Request Payload:

{
  "consumerId": "consumer-uuid-123",
  "amount": "25.00"
}

Response:

{
  "success": true,
  "data": {
    "consumerId": "consumer-uuid-123",
    "newBalance": "125.50",
    "transactionId": 78901
  }
}

Reverse Debit Transaction

Reverses a previous FITCOIN debit transaction.

Endpoint: POST /webhooks/hubble/consumers/{consumerId}/transactions/{transactionId}/reverse

Request Payload:

{
  "consumerId": "consumer-uuid-123",
  "originalTransactionId": 78901,
  "reason": "Service cancellation"
}

Response:

{
  "success": true,
  "data": {
    "consumerId": "consumer-uuid-123",
    "newBalance": "150.50",
    "transactionId": 78901,
    "reversalTransactionId": 78902
  }
}

SSO Authentication

Provides user information for Hubble SSO integration.

Endpoint: GET /webhooks/hubble/auth/sso

Response:

{
  "success": true,
  "data": {
    "id": "consumer-uuid-123",
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "[phone]"
  }
}

API Endpoints

Get Coin Balance

GET /webhooks/hubble/consumers/{consumerId}/balance
Authorization: Bearer <token>
organization_code: <org_code>
organizationid: <org_id>

Debit Coins

POST /webhooks/hubble/consumers/{consumerId}/transactions
Content-Type: application/json
Authorization: Bearer <token>
organization_code: <org_code>
organizationid: <org_id>

{
  "consumerId": "consumer-uuid-123",
  "amount": "25.00"
}

Reverse Debit Transaction

POST /webhooks/hubble/consumers/{consumerId}/transactions/{transactionId}/reverse
Content-Type: application/json
Authorization: Bearer <token>
organization_code: <org_code>
organizationid: <org_id>

{
  "consumerId": "consumer-uuid-123",
  "originalTransactionId": 78901,
  "reason": "Service cancellation"
}

SSO Authentication

GET /webhooks/hubble/auth/sso
Authorization: Bearer <token>
organization_code: <org_code>
organizationid: <org_id>

Error Handling

HTTP Status Codes

• 200 - Success

• 400 - Bad Request (validation errors)

• 401 - Unauthorized

• 403 - Forbidden

• 404 - Not Found

• 409 - Conflict (duplicate records)

• 500 - Internal Server Error

Error Response Format

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE",
    "details": {
      "field": "additional error details"
    }
  }
}

Common Error Codes

Crelio Health Errors

• LABS_INVALID_CONFIGURATION - Integration configuration missing or invalid

• LABS_REGISTRATION_FAILED - Patient registration failed

• LABS_BOOKING_FAILED - Lab appointment booking failed

• LABS_REPORT_NOT_FOUND - Lab report not found in webhook

• LABS_WEBHOOK_PROCESSING_FAILED - Webhook processing failed

• LABS_APPOINTMENT_NOT_FOUND - Appointment not found

• LABS_INVOICE_ITEM_MISSING_ATTRIBUTES - Invoice item missing required attributes

Hubble Errors

• PATIENT_NOT_FOUND - Consumer not found

• TRANSACTION_NOT_FOUND - Transaction not found

• INVALID_REVERSAL_REQUEST - Invalid reversal request

• INSUFFICIENT_BALANCE - Insufficient FITCOIN balance

Security Considerations

Authentication

• All endpoints require valid JWT tokens

• Organization-level access control enforced

• API keys stored securely in integration configuration

Data Protection

• All data transmitted over HTTPS

• Sensitive data encrypted at rest

• PII protection for patient information

Webhook Security

• Webhook payloads validated before processing

• External ID mapping prevents unauthorized access

• Audit logging for all operations

Examples

Complete Lab Workflow

1. Create Patient:

curl -X POST 'https://api.azodha.com/api/patients/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'organization_code: dev-care2u' \
  --header 'organizationid: 5' \
  --data '{
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1990-01-01",
    "gender": "MALE",
    "email": "[email protected]",
    "mobileNumber": "[phone]"
  }'

1. Create Invoice with Lab Items:

curl -X POST 'https://api.azodha.com/api/invoices/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'organization_code: dev-care2u' \
  --header 'organizationid: 5' \
  --data '{
    "consumerUuid": "patient-uuid-123",
    "appointmentId": 67890,
    "amount": 150.00,
    "paymentType": "GATEWAY",
    "invoiceToInvoiceItems": [
      {
        "id": 1,
        "quantity": 1,
        "overrideAmount": 150.00
      }
    ]
  }'

1. Lab Report Webhook (automatically processed):

curl -X POST 'https://api.azodha.com/webhook/labs/reports' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'organization_code: dev-care2u' \
  --header 'organizationid: 5' \
  --data '{
    "billId": 11111,
    "Patient Id": 12345,
    "Report Id": 99999,
    "Test Name": "Complete Blood Count",
    "sampleID": "SAMPLE_001",
    "Report Date": "2024-01-16",
    "labName": "Crelio Health Lab",
    "CentreReportId": 88888,
    "reportBase64": "JVBERi0xLjQKJcOkw7zDtsO..."
  }'

Complete Hubble Workflow

1. Get Coin Balance:

curl -X GET 'https://api.azodha.com/webhooks/hubble/consumers/consumer-uuid-123/balance' \
  --header 'Authorization: Bearer <token>' \
  --header 'organization_code: dev-care2u' \
  --header 'organizationid: 5'

1. Debit Coins:

curl -X POST 'https://api.azodha.com/webhooks/hubble/consumers/consumer-uuid-123/transactions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'organization_code: dev-care2u' \
  --header 'organizationid: 5' \
  --data '{
    "consumerId": "consumer-uuid-123",
    "amount": "25.00"
  }'

1. Reverse Transaction:

curl -X POST 'https://api.azodha.com/webhooks/hubble/consumers/consumer-uuid-123/transactions/78901/reverse' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'organization_code: dev-care2u' \
  --header 'organizationid: 5' \
  --data '{
    "consumerId": "consumer-uuid-123",
    "originalTransactionId": 78901,
    "reason": "Service cancellation"
  }'

Support

For technical support or questions about Crelio Health or Hubble integrations:

• Support Email: [email protected]

• Documentation: https://docs.azodha.com

• API Reference: https://docs.azodha.com/api-reference

---

Last updated: January 2024