# 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.

## 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",
      "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": ""
}
```

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}
]
```

## 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