# 07 — Appointments

← [Back to index](README.md)

---

## `GET /appointments?from=<iso>&to=<iso>`
Appointments overlapping the half-open range `[from, to)`. Powers the calendar.

**Response `200`** — array of **Appointment**:
```json
[
  {
    "id": "a1",
    "patientId": "p1",
    "patientName": "محمد علي حسن",
    "doctorId": "u_123",
    "doctorName": "د. أحمد",
    "scheduledAt": "2026-05-22T10:15:00Z",
    "durationMinutes": 30,
    "visitType": "firstVisit",
    "status": "scheduled",
    "notes": null,
    "arrivedAt": null
  }
]
```
- `visitType`: [VisitType](11-enums.md) enum. `status`: [AppointmentStatus](11-enums.md).
- `patientName` / `doctorName` denormalized for fast calendar rendering.

> **Time-slot availability is computed client-side** from this range query + working hours.
> You don't need a "free slots" endpoint — just return appointments accurately. (Today the
> app hardcodes the working window; once [working hours](02-tenant-settings.md) are served,
> we wire it in.)

## `GET /appointments/{id}` → single Appointment.

---

## `POST /appointments`
**Request**
```json
{
  "patientId": "p1",
  "patientName": "محمد علي حسن",
  "scheduledAt": "2026-05-22T10:15:00Z",
  "durationMinutes": 30,
  "visitType": "firstVisit",
  "notes": null
}
```
- **No double-booking:** reject overlapping slots for the same doctor with `409`. Blocking
  statuses: `scheduled`, `arrived`, `inProgress`, `completed`; `cancelled`/`noShow` don't block.
- `status` starts `scheduled`; server sets `doctorId`/`doctorName` from the auth context.
**Response `201`** — the created Appointment.

> **Invoice on booking:** after a successful booking the app issues a **separate**
> [`POST /invoices`](10-billing.md) for the visit fee (paid/pending per a UI toggle). Default:
> the app creates it; don't auto-create server-side unless we coordinate.

---

## `PATCH /appointments/{id}/status`
**Request** `{ "status": "arrived" }` — an [AppointmentStatus](11-enums.md). Enforce valid
transitions (`scheduled→arrived→inProgress→completed`, or →`cancelled`/`noShow`). Set
`arrivedAt` on `arrived`. **Response `200`** — updated Appointment.

## `PATCH /appointments/{id}/reschedule`
**Request** `{ "scheduledAt": "<iso>", "durationMinutes": 30 }`. No-double-booking applies.
Does **not** create a new invoice. **Response `200`** — updated Appointment.

## `PATCH /appointments/{id}/cancel`
**Request** `{ "reason": "optional text" }`. Soft-cancel (keep the row for audit).
**Response `200`** — Appointment with `status: cancelled`.

---

## `GET /appointments/visit-type-options`
Selectable options for the booking screen (fee + duration + kind + label).
```json
[
  { "id": "vt_1", "kind": "firstVisit", "label": "كشف أول", "feePiastres": 30000, "durationMinutes": 30 }
]
```
- `kind`: [VisitType](11-enums.md). Derive from the tenant's configured
  [visit types](02-tenant-settings.md); map each to a `kind`.
- If unset, return the default catalogue: `firstVisit` 300 EGP/30m, `followUp` 150 EGP/20m,
  `consultation` 250 EGP/30m, `procedure` 500 EGP/45m. (Fees in piastres: 30000/15000/25000/50000.)

---

## Field contracts

### `Appointment`
`id`, `patientId`, `patientName`, `doctorId`, `doctorName`, `scheduledAt` (datetime),
`durationMinutes` (int), `visitType` ([VisitType](11-enums.md)),
`status` ([AppointmentStatus](11-enums.md)), `notes?`, `arrivedAt?` (datetime).

### `VisitTypeOption` (booking)
`id`, `kind` ([VisitType](11-enums.md)), `label` (string), `feePiastres` (int),
`durationMinutes` (int).
