{
  "openapi": "3.1.0",
  "info": {
    "title": "MORRU Booking API",
    "version": "1.0.0",
    "summary": "Take appointment requests on a clinic's own website, straight into MORRU HIS.",
    "description": "Server-to-server API for clinic websites. Services, providers, free times and approval rules are the same as MORRU's hosted booking page.\n\n- **Auth:** `Authorization: Bearer mbk_…` — create keys in HIS › Branch management › Web booking page › API. Keys work for every bookable branch of the account.\n- **Server only:** requests that carry an `Origin` header are rejected (403 `server_only`). Never put the key in a web page.\n- **Rate limits per key:** reads 300/min · writes (`POST`) 60/min → 429.\n- **Times:** `date`, `time` and `appointmentAt` are the clinic's local time without a zone; `createdAt`, `decidedAt` and `holdUntil` are UTC.\n- **Plans:** Starter and up.\n\nFull guide (Thai/English): https://www.morru.com/developers/booking",
    "contact": {
      "name": "MORRU",
      "url": "https://www.morru.com/developers/booking"
    }
  },
  "servers": [
    {
      "url": "https://api2.morru.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bookingKey": []
    }
  ],
  "tags": [
    {
      "name": "Catalog",
      "description": "Branches, services, providers and free times"
    },
    {
      "name": "Verification",
      "description": "Optional OTP sent by MORRU on the clinic's behalf"
    },
    {
      "name": "Requests",
      "description": "Create, read and cancel booking requests"
    }
  ],
  "paths": {
    "/v1/booking/config": {
      "get": {
        "tags": [
          "Catalog"
        ],
        "operationId": "getConfig",
        "summary": "Clinic look, bookable branches and verification methods",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Config"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ServerOnly"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/booking/services": {
      "get": {
        "tags": [
          "Catalog"
        ],
        "operationId": "listServices",
        "summary": "Bookable services",
        "description": "With `branch` (or a single-branch clinic): the services of that branch. Without `branch` on a multi-branch clinic: services grouped across branches by Thai name, each with `branches[]` telling the per-branch service id and booking mode.",
        "parameters": [
          {
            "name": "branch",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9]{12}$"
            },
            "description": "Branch id from `GET /config` (`branches[].id`). Optional when the clinic has one bookable branch."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Service"
                      }
                    },
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ServiceGroup"
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ServerOnly"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/booking/staff": {
      "get": {
        "tags": [
          "Catalog"
        ],
        "operationId": "listStaff",
        "summary": "Providers who offer a service",
        "description": "`slot` and `day` services have no provider step and return `{ allowAny: true, staff: [] }`.",
        "parameters": [
          {
            "name": "branch",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9]{12}$"
            },
            "description": "Branch id from `GET /config` (`branches[].id`). Optional when the clinic has one bookable branch."
          },
          {
            "name": "service",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Service id for this branch (`id`, or `branches[].serviceId` of a grouped service)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StaffList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ServerOnly"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/booking/slots": {
      "get": {
        "tags": [
          "Catalog"
        ],
        "operationId": "getSlots",
        "summary": "Free times for a day, or available days in a month",
        "description": "Send `date` for the times of one day, or `month` (without `date`) for the days that still have room — for greying out a calendar. Days are limited to today … today + `maxDaysAhead` of the branch.",
        "parameters": [
          {
            "name": "branch",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9]{12}$"
            },
            "description": "Branch id from `GET /config` (`branches[].id`). Optional when the clinic has one bookable branch."
          },
          {
            "name": "service",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Service id for this branch (`id`, or `branches[].serviceId` of a grouped service)."
          },
          {
            "name": "staff",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Provider id from `GET /staff`. `0` or omitted = any provider. Must be `0` for `slot` and `day` services."
          },
          {
            "name": "date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Day to list (yyyy-MM-dd)."
          },
          {
            "name": "month",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}$"
            },
            "description": "Month to scan (yyyy-MM). Ignored when `date` is sent."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/DaySlots"
                    },
                    {
                      "$ref": "#/components/schemas/DaySpan"
                    },
                    {
                      "$ref": "#/components/schemas/MonthAvailability"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`date` outside the bookable window, or an invalid `month`. Body: `{ message }`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ServerOnly"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/booking/otp": {
      "post": {
        "tags": [
          "Verification"
        ],
        "operationId": "requestOtp",
        "summary": "Send a 6-digit code to the patient",
        "description": "Optional. Use when the clinic does not verify the patient itself. Only channels listed in the branch's `verify` work (`email`, `sms`). Codes expire after 10 minutes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OtpRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Code sent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OtpSent"
                }
              }
            }
          },
          "400": {
            "description": "Invalid phone or email",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OtpError"
                }
              }
            }
          },
          "429": {
            "description": "`wait` (just sent; retry in a minute), `too_many` (too many codes for this phone/email), `branch_limit` (daily limit of the branch) or `sms_quota` (the clinic's SMS quota is used up; use email)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OtpError"
                }
              }
            }
          },
          "502": {
            "description": "`send_failed` — the code could not be delivered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OtpError"
                }
              }
            }
          },
          "503": {
            "description": "`unavailable`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OtpError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ServerOnly"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/booking/otp/verify": {
      "post": {
        "tags": [
          "Verification"
        ],
        "operationId": "verifyOtp",
        "summary": "Check the code and get a proof for the request",
        "description": "Returns a `proof` valid for 30 minutes and usable once. Send it in `verify` when creating the request. Five wrong attempts expire the code.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OtpVerifyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verified",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OtpVerified"
                }
              }
            }
          },
          "400": {
            "description": "`invalid` (not 6 digits), `wrong` (with `attemptsLeft`) or `expired`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OtpVerifyError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ServerOnly"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/booking/requests": {
      "post": {
        "tags": [
          "Requests"
        ],
        "operationId": "createRequest",
        "summary": "Send a booking request",
        "description": "The request goes into the branch's request inbox in HIS (or is approved automatically, by branch setting) exactly like the hosted booking page. The slot is held until `holdUntil`.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{8,64}$"
            },
            "description": "Retry-safe key. The same key returns the original request with HTTP 200 instead of creating a new one."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestStatus"
                }
              }
            }
          },
          "200": {
            "description": "Replayed — same Idempotency-Key, the original request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestStatus"
                }
              }
            }
          },
          "400": {
            "description": "`invalid` (see `field`) or `verify_expired` (the OTP proof expired or was used)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`taken` (time or day just filled), `staff_service` (provider no longer offers the service) or `too_soon` (too close for the clinic to approve)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`unavailable` — retry with the same Idempotency-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ServerOnly"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/booking/requests/{reference}": {
      "get": {
        "tags": [
          "Requests"
        ],
        "operationId": "getRequest",
        "summary": "Request status",
        "description": "Works for requests from this API and from MORRU's hosted booking page of the same account (webhooks carry both).",
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9]{12}$"
            },
            "description": "Request reference (`ref`)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestStatus"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ServerOnly"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/booking/requests/{reference}/cancel": {
      "post": {
        "tags": [
          "Requests"
        ],
        "operationId": "cancelRequest",
        "summary": "Cancel for the patient",
        "description": "A pending request is cancelled at once. An approved appointment follows the same rules as LINE self-cancel (unpaid, not checked in, and early enough for the branch setting); otherwise the result is `asked` — the clinic is asked to call the patient and the appointment stays.",
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9]{12}$"
            },
            "description": "Request reference (`ref`)."
          }
        ],
        "responses": {
          "200": {
            "description": "Done",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelResult"
                }
              }
            }
          },
          "409": {
            "description": "`changed` (status just changed; fetch it again), `busy` (the clinic is confirming it right now) or `closed` (can no longer be cancelled)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`unavailable`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ServerOnly"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "webhooks": {
    "bookingEvent": {
      "post": {
        "summary": "Request status changed",
        "description": "Sent to the HTTPS URL set in HIS (port 443, public domain, redirects are not followed). Reply 2xx within 10 seconds. Otherwise it is retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h, then dropped. Events may arrive twice or out of order — dedupe on `id` and fetch `GET /v1/booking/requests/{ref}` when in doubt.\n\nVerify `Morru-Signature: t={unix},v1={hex}` where `v1 = HMAC-SHA256(secret, t + \".\" + rawBody)` with the `whsec_…` secret from HIS; reject `t` more than 5 minutes off. Test vector: secret `whsec_test`, t `1700000000`, body `{\"a\":1}` → `t=1700000000,v1=38877139021993b830af32feea6e18a8da83eb2f6e49ee50bd9e4cf4ca4d3789`.",
        "parameters": [
          {
            "name": "Morru-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Morru-Event-Id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "User-Agent",
            "in": "header",
            "schema": {
              "type": "string",
              "example": "MORRU-Webhooks/1.0"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the event"
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bookingKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "mbk_{12}_{40}",
        "description": "API key from HIS, e.g. `mbk_ab12cd34ef56_…`. Shown once when created; revoke and create a new one if lost."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "`unauthorized` — wrong or revoked key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerOnly": {
        "description": "`server_only` — called from a browser (an `Origin` header was sent)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "`booking_off` — web booking is not turned on. An unknown branch, service, provider or reference also returns 404 (possibly with an empty body).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests for this key (reads 300/min, writes 60/min). Wait and retry."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "reason"
        ],
        "properties": {
          "reason": {
            "type": "string",
            "description": "Machine-readable code"
          },
          "message": {
            "type": "string",
            "description": "Thai message, safe to show"
          },
          "field": {
            "type": "string",
            "description": "Input field at fault, for `invalid`"
          }
        }
      },
      "Window": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "pattern": "^\\d{2}:\\d{2}$"
          },
          "to": {
            "type": "string",
            "pattern": "^\\d{2}:\\d{2}$"
          }
        }
      },
      "Mode": {
        "type": "string",
        "enum": [
          "doctor",
          "slot",
          "day"
        ],
        "description": "`doctor` = pick a provider and a time · `slot` = fixed rounds of the service with a capacity · `day` = come any time within the day's window (no time)"
      },
      "Config": {
        "type": "object",
        "properties": {
          "stepOrder": {
            "type": [
              "string",
              "null"
            ],
            "description": "Step order of MORRU's hosted page, e.g. `branch_first` (informational)"
          },
          "fixedBranch": {
            "type": [
              "string",
              "null"
            ]
          },
          "clinic": {
            "type": "object",
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "nameEn": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "logoUrl": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "themeColor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "accent": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "coverUrl": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "welcome": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "welcomeEn": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "notice": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "noticeEn": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "cancelPolicy": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "cancelPolicyEn": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "branches": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Branch"
            }
          },
          "consentVersion": {
            "type": "string"
          }
        }
      },
      "Branch": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z0-9]{12}$"
          },
          "name": {
            "type": "string"
          },
          "nameEn": {
            "type": [
              "string",
              "null"
            ]
          },
          "address": {
            "type": "string"
          },
          "addressEn": {
            "type": [
              "string",
              "null"
            ]
          },
          "tel": {
            "type": "string"
          },
          "lat": {
            "type": [
              "number",
              "null"
            ]
          },
          "lng": {
            "type": [
              "number",
              "null"
            ]
          },
          "hoursToday": {
            "type": "string"
          },
          "verify": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "line",
                "email",
                "sms"
              ]
            },
            "description": "Verification channels of MORRU's hosted page. For this API use `email`/`sms` via /otp, or verify yourself (`method: clinic`)."
          },
          "approveMode": {
            "type": "string",
            "enum": [
              "manual",
              "auto"
            ]
          },
          "maxDaysAhead": {
            "type": "integer"
          },
          "photos": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "mapUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "noteEn": {
            "type": [
              "string",
              "null"
            ]
          },
          "currency": {
            "type": "string"
          }
        }
      },
      "Service": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "nameEn": {
            "type": "string"
          },
          "icon": {
            "type": [
              "string",
              "null"
            ]
          },
          "imageUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "descriptionEn": {
            "type": [
              "string",
              "null"
            ]
          },
          "durationMinutes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Starting price when the clinic shows prices, else null"
          },
          "prep": {
            "type": [
              "string",
              "null"
            ]
          },
          "prepEn": {
            "type": [
              "string",
              "null"
            ]
          },
          "mode": {
            "$ref": "#/components/schemas/Mode"
          },
          "window": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Window"
              },
              {
                "type": "null"
              }
            ],
            "description": "Hours for `slot`/`day` services when set; null = branch opening hours"
          },
          "slotMinutes": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "ServiceGroup": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Service"
          },
          {
            "type": "object",
            "properties": {
              "branches": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "branch": {
                      "type": "string"
                    },
                    "serviceId": {
                      "type": "integer"
                    },
                    "mode": {
                      "$ref": "#/components/schemas/Mode"
                    }
                  }
                }
              }
            }
          }
        ],
        "description": "A service grouped across branches by Thai name. It has no `id` — book with `branches[].serviceId` of the chosen branch."
      },
      "StaffList": {
        "type": "object",
        "properties": {
          "allowAny": {
            "type": "boolean",
            "description": "`staff = 0` (any provider) can be booked"
          },
          "staff": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                },
                "nameEn": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "pictureUrl": {
                  "type": "string"
                },
                "specialty": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "specialtyEn": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "languages": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "bio": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "bioEn": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          }
        }
      },
      "DaySlots": {
        "type": "object",
        "description": "`doctor` and `slot` services",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "times": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}$"
            }
          }
        }
      },
      "DaySpan": {
        "type": "object",
        "description": "`day` services — `times` is always empty; `day` is null when the day is closed or full",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "times": {
            "type": "array",
            "maxItems": 0,
            "items": {
              "type": "string"
            }
          },
          "day": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Window"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "MonthAvailability": {
        "type": "object",
        "properties": {
          "month": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}$"
          },
          "available": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date"
            }
          }
        }
      },
      "OtpRequest": {
        "type": "object",
        "required": [
          "channel",
          "target"
        ],
        "properties": {
          "branch": {
            "type": "string"
          },
          "channel": {
            "type": "string",
            "enum": [
              "email",
              "sms"
            ]
          },
          "target": {
            "type": "string",
            "description": "Mobile number (Thai, 0xxxxxxxxx) or email"
          }
        }
      },
      "OtpSent": {
        "type": "object",
        "properties": {
          "sent": {
            "const": true
          },
          "expiresIn": {
            "type": "integer",
            "description": "Seconds (600)"
          },
          "resendIn": {
            "type": "integer",
            "description": "Seconds (60)"
          }
        }
      },
      "OtpError": {
        "type": "object",
        "properties": {
          "sent": {
            "const": false
          },
          "reason": {
            "type": "string",
            "enum": [
              "invalid",
              "wait",
              "too_many",
              "branch_limit",
              "sms_quota",
              "send_failed",
              "unavailable"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      },
      "OtpVerifyRequest": {
        "type": "object",
        "required": [
          "channel",
          "target",
          "code"
        ],
        "properties": {
          "branch": {
            "type": "string"
          },
          "channel": {
            "type": "string",
            "enum": [
              "email",
              "sms"
            ]
          },
          "target": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "pattern": "^\\d{6}$"
          }
        }
      },
      "OtpVerified": {
        "type": "object",
        "properties": {
          "verified": {
            "const": true
          },
          "proof": {
            "type": "string"
          },
          "proofExpiresIn": {
            "type": "integer",
            "description": "Seconds (1800)"
          }
        }
      },
      "OtpVerifyError": {
        "type": "object",
        "properties": {
          "verified": {
            "const": false
          },
          "reason": {
            "type": "string",
            "enum": [
              "invalid",
              "wrong",
              "expired"
            ]
          },
          "attemptsLeft": {
            "type": "integer"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Verify": {
        "type": "object",
        "required": [
          "method"
        ],
        "properties": {
          "method": {
            "type": "string",
            "enum": [
              "clinic",
              "email",
              "sms"
            ],
            "description": "`clinic` = the clinic verified the patient itself"
          },
          "target": {
            "type": "string",
            "description": "Same phone/email as the request (OTP methods)"
          },
          "proof": {
            "type": "string",
            "description": "From /otp/verify (OTP methods)"
          }
        }
      },
      "CreateRequest": {
        "type": "object",
        "required": [
          "serviceId",
          "date",
          "firstName",
          "phone",
          "consent",
          "verify"
        ],
        "properties": {
          "branch": {
            "type": "string"
          },
          "serviceId": {
            "type": "integer"
          },
          "staffId": {
            "type": "integer",
            "default": 0,
            "description": "0 = any provider; must be 0 for slot/day services"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "time": {
            "type": "string",
            "pattern": "^\\d{2}:\\d{2}$",
            "description": "Required for doctor/slot services; omit for day services"
          },
          "firstName": {
            "type": "string",
            "maxLength": 100
          },
          "lastName": {
            "type": "string",
            "maxLength": 100
          },
          "phone": {
            "type": "string",
            "description": "Thai mobile number"
          },
          "email": {
            "type": "string",
            "maxLength": 200
          },
          "note": {
            "type": "string",
            "maxLength": 500
          },
          "consent": {
            "type": "boolean",
            "description": "Must be true: the patient accepted the data-use terms on your site"
          },
          "externalRef": {
            "type": "string",
            "maxLength": 100,
            "description": "Your own id; returned in status and webhooks"
          },
          "verify": {
            "$ref": "#/components/schemas/Verify"
          }
        }
      },
      "RequestStatus": {
        "type": "object",
        "properties": {
          "ref": {
            "type": "string"
          },
          "externalRef": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "api",
              "web"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected",
              "expired",
              "cancelled"
            ]
          },
          "approveMode": {
            "type": "string",
            "enum": [
              "manual",
              "auto"
            ]
          },
          "branch": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "service": {
            "type": "object",
            "properties": {
              "id": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "name": {
                "type": "string"
              },
              "nameEn": {
                "type": "string"
              }
            }
          },
          "staff": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer"
                  },
                  "name": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "appointmentAt": {
            "type": "string",
            "description": "Clinic local time, yyyy-MM-ddTHH:mm"
          },
          "durationMinutes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "mode": {
            "$ref": "#/components/schemas/Mode"
          },
          "dayFrom": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{2}:\\d{2}$",
            "description": "`day` mode: start of the window (HH:mm); null otherwise"
          },
          "dayTo": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{2}:\\d{2}$",
            "description": "`day` mode: end of the window (HH:mm); null otherwise"
          },
          "patient": {
            "type": "object",
            "properties": {
              "firstName": {
                "type": "string"
              },
              "lastName": {
                "type": "string"
              },
              "phone": {
                "type": "string"
              },
              "email": {
                "type": "string"
              },
              "note": {
                "type": "string"
              },
              "verifiedBy": {
                "type": "string",
                "enum": [
                  "clinic",
                  "email",
                  "sms",
                  "line"
                ]
              }
            }
          },
          "holdUntil": {
            "type": "string",
            "description": "UTC; only while pending, else empty"
          },
          "createdAt": {
            "type": "string",
            "description": "UTC"
          },
          "decidedAt": {
            "type": "string",
            "description": "UTC or empty"
          },
          "appointmentId": {
            "type": [
              "integer",
              "null"
            ]
          },
          "hn": {
            "type": "string"
          },
          "rejectReason": {
            "type": "string"
          }
        }
      },
      "CancelResult": {
        "type": "object",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "cancelled",
              "asked"
            ]
          },
          "minHours": {
            "type": "integer",
            "description": "With `asked`: hours before the appointment needed for self-cancel"
          }
        }
      },
      "WebhookEvent": {
        "type": "object",
        "required": [
          "id",
          "type",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "evt_… — same as Morru-Event-Id"
          },
          "type": {
            "type": "string",
            "enum": [
              "request.created",
              "request.approved",
              "request.rejected",
              "request.expired",
              "request.cancelled",
              "ping"
            ]
          },
          "createdAt": {
            "type": "string",
            "description": "UTC"
          },
          "data": {
            "oneOf": [
              {
                "type": "object",
                "description": "No patient name or contact details — fetch GET /v1/booking/requests/{ref}",
                "properties": {
                  "ref": {
                    "type": "string"
                  },
                  "externalRef": {
                    "type": "string"
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "api",
                      "web"
                    ]
                  },
                  "status": {
                    "type": "string"
                  },
                  "branch": {
                    "type": "string"
                  },
                  "appointmentAt": {
                    "type": "string"
                  },
                  "appointmentId": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "hn": {
                    "type": "string"
                  },
                  "rejectReason": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "null",
                "description": "`ping` (test button in HIS)"
              }
            ]
          }
        }
      }
    }
  }
}
