> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spn.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

> WhatsApp (Gupshup), OpenAI, Khata OCR, and PDF generation

## Gupshup (WhatsApp)

Gupshup receives WhatsApp messages and sends replies on behalf of the business number.

**Required env vars:**

```
GUPSHUP_PARTNER_EMAIL
GUPSHUP_PARTNER_PASSWORD
GUPSHUP_APP_ID
GUPSHUP_HEENA_ORDER_PLACEMENT_SUB_TAG
ALLOWED_PHONE_NUMBERS
```

**Order flow:**

1. Customer sends an order via WhatsApp
2. Gupshup forwards it to `POST /gupshup_incoming_webhook`
3. Backend validates the sender against `ALLOWED_PHONE_NUMBERS`
4. Message is sent to OpenAI for parsing
5. An `OrderDraft` is created
6. A WhatsApp confirmation is sent back to the customer
7. Staff review and convert the draft at `/order-drafts`

***

## OpenAI

OpenAI is used with **structured output (JSON mode)** to parse unstructured WhatsApp order messages into typed order entries.

**Used in:** `services.py` / `gupshup_incoming_webhook.py`

**Required env var:**

```
OPENAI_API_KEY
```

***

## Khata OCR

Processes scanned/photographed hand-written ledger pages.

**Flow:**

1. Upload a photo or PDF of a khata page via `POST /khata-upload` or `/khata-upload-v2`
2. Backend converts PDF to image using `pdf2image` if needed
3. OCR extracts transaction data
4. User reviews in a multi-step UI: `UploadStep` → `ReviewStep` → `AssignStep`
5. On submission, entries are posted to the relevant party ledgers

***

## PDF Generation

PDFs are generated server-side using **reportlab** via `pdf_service.py`.

| Endpoint                              | Description         |
| ------------------------------------- | ------------------- |
| `GET /karigar-ledger/{id}/pdf/{side}` | Karigar ledger PDF  |
| `GET /client-ledger/{id}/pdf/{side}`  | Client ledger PDF   |
| `GET /polisher-ledger/{id}/pdf`       | Polisher ledger PDF |
| `GET /bullion-ledger/{id}/pdf/{side}` | Bullion ledger PDF  |
| `GET /client-orders/pdf`              | Client orders PDF   |

The `side` parameter accepts `in` or `out`. All responses return `Content-Type: application/pdf` and trigger a browser download.

***

## HTTP Client (Frontend)

The Axios instance (`src/lib/axiosInstance.ts`) is configured with:

| Setting         | Value                                          |
| --------------- | ---------------------------------------------- |
| Base URL        | `VITE_API_BASE_URL` or `http://localhost:8000` |
| Timeout         | 600,000 ms (10 min — for large PDF/upload ops) |
| Auth header     | `Bearer testToken` (placeholder)               |
| 401/403 handler | Logs unauthorized access                       |
| 500 handler     | Logs server errors                             |

***

## CORS

The backend allows requests from:

* `http://localhost:5173` (Vite dev server)
* `http://localhost:3000`
* Production EC2 domain (`ec2-15-207-84-167.ap-south-1.compute.amazonaws.com`)

Configured in `backend/src/sj/__init__.py` using FastAPI's `CORSMiddleware`.