# ABDM Scan & Share — bridge CSP_001 → CareKiosk

The ABDM gateway already calls the registered bridge (`https://myapp.appdoc.in`) when a patient scans a counter QR in the ABHA / PHR app. The bridge forwards that request to CareKiosk, gets a token back, and answers the gateway. No ABDM re-registration is needed.

```
ABHA app ──scan──▶ ABDM gateway ──/v1.0/patients/profile/share──▶ Bridge (CSP_001)
                                                                     │  forward (signed)
                                                                     ▼
                                                    POST https://<console_host>/api/abdm/share
                                                                     │  {status, tokenNumber, healthId, resp.requestId}
Bridge ──/v1.0/patients/profile/on-share──▶ ABDM gateway ──▶ token shown in ABHA app
```

## 1. Forward the share (bridge → CareKiosk)
Forward the gateway's JSON body **unchanged**. CareKiosk reads the v1.0 shape (`profile.patient.healthId`, `healthIdNumber`, `identifiers[MOBILE]`, `profile.hipCode`, `metaData.hipId`, `metaData.context`) and v3-style keys (`abhaAddress`, `abhaNumber`).

Headers:
| Header | Value |
|---|---|
| `Content-Type` | `application/json` |
| `X-CK-Timestamp` | Unix seconds (must be within 5 minutes of server time) |
| `X-CK-Signature` | lower-case hex `HMAC-SHA256(secret, timestamp + "." + rawBody)` |
| `X-HIP-ID` | optional; used if the body has no hipId/hipCode |
| `REQUEST-ID` | optional; used if the body has no requestId |

`secret` = `abdm_webhook_secret` from CareKiosk `app/config.php` (printed by `php bin/migrate.php`). Optionally restrict by IP with `abdm_bridge_ips`.

```bash
TS=$(date +%s); BODY=$(cat share.json)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
curl -X POST https://console.carekiosk.in/api/abdm/share -H "Content-Type: application/json" \
     -H "X-CK-Timestamp: $TS" -H "X-CK-Signature: $SIG" --data "$BODY"
```

## 2. Response from CareKiosk
Success (HTTP 200):
```json
{"status":"SUCCESS","tokenNumber":"ABH-012","healthId":"sunita.more@sbx","resp":{"requestId":"<gateway requestId>"},"expiry":"1800"}
```
Failure (HTTP 4xx/5xx): `{"status":"FAILURE","error":{"code":1404,"message":"HIP not mapped to a hospital"}}`

Retries with the same `requestId` return the same token (idempotent), so the bridge can safely retry on timeouts.

## 3. Answer the gateway (bridge → ABDM)
Build `/v1.0/patients/profile/on-share` from the response:
```json
{
  "requestId": "<new uuid>",
  "timestamp": "<ISO-8601 UTC>",
  "acknowledgement": { "status": "SUCCESS", "healthId": "<healthId>", "tokenNumber": "<tokenNumber>" },
  "resp": { "requestId": "<requestId of the incoming share>" }
}
```
On CareKiosk failure, send `acknowledgement.status: "FAILURE"` with an `error` object so the app shows a message instead of spinning.

## 4. Mapping
* **Hospital** ← HFR HIP ID. Set in CareKiosk console → hospital → *ABDM Scan & Share*.
* **Kiosk** ← counter ID (`metaData.context`). Set by the hospital admin → *Kiosks* → *ABHA Scan & Share*, together with the counter QR link from the HFR portal. The kiosk displays that QR and picks up shares for its counter.
* Shares for a counter with no kiosk still register and appear in the front-desk queue with an **ABHA** badge — the patient can go straight to the counter with the token from the ABHA app.