dbis_core/docs/integration/IRU_INTEGRATION_GUIDE.md

# IRU Integration Guide
## Complete Guide for Integrating with DBIS IRU

### Overview

This guide provides step-by-step instructions for integrating your Core Banking, CRM, or ERP system with DBIS IRU infrastructure.

### Prerequisites

- Active IRU subscription
- API credentials (API key)
- Network connectivity to DBIS infrastructure
- Technical team familiar with your core banking system

### Step 1: Obtain IRU Subscription

1. Browse marketplace: `https://marketplace.sankofaphoenix.com`
2. Select appropriate IRU offering
3. Submit inquiry
4. Complete qualification process
5. Execute IRU Participation Agreement
6. Receive subscription credentials

### Step 2: Choose Integration Method

#### Option A: Pre-Built Connector (Recommended)

If your system is supported, use a pre-built connector:

**Supported Systems:**
- Temenos T24/Temenos Transact
- Oracle Flexcube
- SAP Banking Services
- Oracle Banking Platform

**Installation:**

```typescript
import { pluginRegistry } from '@dbis/iru-sdk';
import { TemenosAdapter } from '@dbis/iru-sdk/adapters/temenos';

// Register adapter
pluginRegistry.register('temenos', new TemenosAdapter({
  apiEndpoint: 'https://your-temenos-api.com',
  apiKey: 'your-api-key',
}));
```

#### Option B: Custom Connector

If your system is not supported, build a custom connector:

```typescript
import { BasePluginAdapter } from '@dbis/iru-sdk';

class MyCustomAdapter extends BasePluginAdapter {
  constructor(config: Record<string, unknown> = {}) {
    super('MyCustomAdapter', '1.0.0', config);
  }

  // Implement required methods
  async isAvailable(): Promise<boolean> {
    // Check connectivity
  }

  mapParticipant(internalData: unknown): ParticipantCreateRequest {
    // Map your participant data to DBIS format
  }

  // ... implement other methods
}
```

### Step 3: Configure Connection

1. **Obtain API Credentials**
   - Log into Phoenix Portal
   - Navigate to API Settings
   - Generate API key
   - Download certificate (if mTLS required)

2. **Configure Network**
   - Whitelist DBIS API endpoints
   - Configure firewall rules
   - Set up VPN (if required)

3. **Configure Adapter**
   ```typescript
   const adapter = new TemenosAdapter({
     apiEndpoint: process.env.TEMENOS_API_ENDPOINT,
     apiKey: process.env.TEMENOS_API_KEY,
   });
   ```

### Step 4: Test Integration

1. **Test Connectivity**
   ```typescript
   const available = await adapter.isAvailable();
   console.log('Adapter available:', available);
   ```

2. **Test Participant Mapping**
   ```typescript
   const participant = adapter.mapParticipant(yourParticipantData);
   console.log('Mapped participant:', participant);
   ```

3. **Test Transfer Posting**
   ```typescript
   const result = await adapter.postTransfer(dbisTransfer);
   console.log('Transfer posted:', result);
   ```

### Step 5: Go Live

1. Complete integration testing
2. Obtain sign-off from DBIS
3. Switch to production endpoints
4. Monitor initial transactions
5. Verify reconciliation

### Best Practices

1. **Idempotency**: Always use idempotency keys for transfers
2. **Error Handling**: Implement retry logic with exponential backoff
3. **Monitoring**: Set up alerts for failed transfers
4. **Reconciliation**: Run daily reconciliation
5. **Security**: Rotate API keys regularly

### Troubleshooting

**Common Issues:**

1. **Connection Timeout**
   - Check network connectivity
   - Verify firewall rules
   - Check API endpoint URL

2. **Authentication Failures**
   - Verify API key is correct
   - Check key expiration
   - Ensure proper authorization header format

3. **Mapping Errors**
   - Verify data format matches expected schema
   - Check required fields are present
   - Review adapter mapping logic

### Support

- Documentation: `https://docs.dbis.org/iru`
- Support Portal: Phoenix Portal → Support
- Email: iru-support@dbis.org