# Hospital External Provider API

Base path: `/api/v1/hospital`

Authentication for all three endpoints:

```http
Authorization: Bearer {HOSPITAL_INTEGRATION_TOKEN}
Accept: application/json
```

Configure the shared secret in the server `.env` as `HOSPITAL_INTEGRATION_TOKEN`. Use a randomly generated value of at least 32 bytes and transfer it to the provider through a secure channel.

## Endpoints

| Method | Endpoint | Result |
|---|---|---|
| GET | `/radiology-requests` | Radiology requests with a `tests` array |
| GET | `/laboratory-requests` | Laboratory requests with a `tests` array |
| GET | `/pharmacy-requests` | Pharmacy requests with a `products` array and quantity per product |

## Optional query parameters

| Parameter | Example | Purpose |
|---|---|---|
| `from` | `2026-07-02T09:00:00+05:00` | Records at or after this date/time |
| `to` | `2026-07-02T18:00:00+05:00` | Records at or before this date/time |
| `date` | `2026-07-02` | Records on one date |
| `request_number` | `RAD-MOB-0001` | Retrieve one exact mobile request |
| `user_id` | UUID | Requests for one mobile user |
| `page` | `1` | Page number |
| `per_page` | `50` | Results per page, maximum 200 |

Results are newest first. Dates are returned in ISO 8601 format.

`user_id` is the permanent South City mobile-system identifier and is always
returned. `mr_number` contains the hospital MR number when the patient has one;
otherwise it is `null`. Patient name, gender, contact number, and date of birth
are returned for both MR and non-MR patients when those values are available.

## Radiology response example

```json
{
  "status": "success",
  "data": {
    "records": [{
      "user_id": "c576e0d8-2b72-46a8-b01b-c87d724b456a",
      "mr_number": "MR-1001",
      "radiology_request_number": "RAD-MOB-0001",
      "name": "Ahmed Khan",
      "gender": "male",
      "contact_number": "03001234567",
      "date_of_birth": "1988-04-12",
      "requested_at": "2026-07-02T10:30:00+05:00",
      "tests": [
        {"test_name": "Chest X-Ray", "test_code": "XR-CHEST"},
        {"test_name": "CT Brain", "test_code": "CT-BRAIN"}
      ]
    }],
    "pagination": {"current_page": 1, "per_page": 50, "total": 1, "last_page": 1}
  },
  "message": "Requests retrieved successfully.",
  "error_code": ""
}
```

For a patient who does not yet have a hospital MR number, the same fields are
returned with the South City identifier and a nullable MR number:

```json
{
  "user_id": "8ef89da4-7187-49f3-91d2-9a5b668bc233",
  "mr_number": null,
  "name": "Walk-in Patient",
  "gender": "female",
  "contact_number": "03000000005",
  "date_of_birth": "1995-09-21"
}
```

Laboratory has the same structure using `laboratory_request_number`. Pharmacy uses `pharmacy_request_number` and:

```json
"products": [
  {"medicine_name": "Medicine A", "medicine_code": "SKU-001", "quantity": 2},
  {"medicine_name": "Medicine B", "medicine_code": "SKU-002", "quantity": 1}
]
```

## Radiology UAT scenarios

The repeatable UAT loader creates the following records after verifying one to
three MR profiles through HIMS:

| Request number | Patient type | Scenario |
|---|---|---|
| `RAD-UAT-0001` | MR | One request with one test |
| `RAD-UAT-0002` | MR | One request with multiple tests |
| `RAD-UAT-0003` | MR | Third MR patient, or a second request for the first MR patient |
| `RAD-UAT-0004` | Non-MR | `mr_number` is null and the patient is identified by `user_id` |
| `RAD-UAT-0005` | Non-MR | Multiple tests with a null MR number |

Run the loader with one to three unique HIMS patients. When one MR is supplied,
the same verified patient is used to exercise multiple request patterns:

```bash
php artisan hospital:seed-radiology-uat \
  --mr='FIRST/MR' \
  --mr='SECOND/MR'
```

The command aborts before writing if an MR is invalid, required demographics
are missing, or two supplied profiles share the same normalized contact number.
It is safe to rerun: the five UAT request numbers and their test items are
updated rather than duplicated.

## Status codes

- `200`: success
- `401`: missing or invalid token
- `422`: invalid query parameter
- `429`: rate limit exceeded
- `503`: integration token is not configured on the server