# Karza Integration

## Purpose

The service integrates with Karza for electricity bill verification and Aadhaar OCR/masking flows.

Main files:

- `integrations/karza.py`
- `static_functions.py`

## Electricity Bill Verification

Implementation:

```text
KarzaIntegration.electricity_bill_verification()
```

Endpoint called:

```text
{KARZA_URL}/v2/elec
```

Headers:

```json
{
  "content-type": "application/json",
  "x-karza-key": "KARZA_ELEC_API_KEY"
}
```

Payload fields:

| Field | Source |
| --- | --- |
| `consumer_id` | function argument |
| `service_provider` | function argument |
| `district` | function argument |
| `regMobileNo` | function argument |
| `consent` | defaults to `Y` |

The call timeout is 60 seconds.

## Saving Utility Validation

Implementation:

```text
KarzaIntegration.save_utility_validation()
```

For successful Karza responses where `status-code` is `101`:

1. Insert full Karza response into `utility_validation`.
2. Parse bill amount if available.
3. Generate a bill validation report PDF.
4. Return success and the resolved monthly bill amount.

For failed validation:

1. Insert a comment into `comments`.
2. Return failure and bill amount `0`.

## Bill Validation Report

Implementation:

```text
KarzaIntegration.generate_bill_validation()
```

Flow:

1. Flatten Karza result data.
2. Render HTML using Jinja2.
3. Convert HTML to PDF with `pdfkit`.
4. Upload PDF to S3.
5. Insert a row in `consumer_application_files`.

Generated S3 key:

```text
{application_id}/electricity_bill_validation_report.pdf
```

Inserted file type:

```text
electricity_bill_validation_report
```

## Static Function Wrapper

`StaticFunctions.run_karza_validation()` orchestrates:

1. Call electricity verification.
2. Save utility validation.
3. Return status, message, and bill amount.

This function can be invoked from schemas through component/static function resolution.

## Aadhaar Masking

Implementation:

```text
StaticFunctions.MaskAadhar()
```

Endpoint called:

```text
{KARZA_URL}/v3/ocr/kyc
```

Purpose:

- Send Aadhaar document content to Karza OCR with `maskAadhaar: true`.
- Download masked image from Karza result.
- Upload masked file to S3.
- If masking fails, upload original unmasked content as fallback with failure status.

Successful S3 key pattern:

```text
{application_id}/masked_{doc_side}.{ext}
```

Fallback S3 key pattern:

```text
{application_id}/unmasked_{doc_side}.{ext}
```

## Configuration

| Variable | Purpose |
| --- | --- |
| `KARZA_URL` | Karza base URL |
| `KARZA_ELEC_API_KEY` | Electricity verification API key |
| `karza_api_key` | OCR/Aadhaar masking API key |
| `AWS_BUCKET` | Bucket for generated reports and masked files |
| `AWS_REGION_NAME` | S3 client region |
| `LENDER_KMGCP_LOGO` | Logo used in generated bill validation report |

## Database Tables

Karza-related code references:

- `utility_validation`
- `consumer_application_files`
- `comments`
- `karza_video_webhooks`

Additional journey checks in `static_functions.py` read Karza VKYC status from `karza_video_webhooks`.

## Failure Modes

| Symptom | Likely Cause |
| --- | --- |
| Karza API failure | Bad URL, bad API key, timeout, invalid payload |
| Bill amount falls back | Missing or negative bill amount in Karza response |
| PDF not generated | `wkhtmltopdf` missing or PDF rendering error |
| Report not visible | S3 upload failed or DB insert failed |
| Masked Aadhaar missing | OCR result did not include image URL or S3 upload failed |
| Unmasked fallback uploaded | Masking failed after original content was available |

## Documentation Requirement

Any endpoint using Karza should document:

- which Karza function is called
- request fields passed to Karza
- database rows inserted
- generated S3 files
- fallback behavior
- client-facing response when Karza fails