RAA-9623 OAS Document SPC/SPCA support for A016 Book or Defer Appoint…

CHANGELOG.md

@@ -1,4 +1,6 @@
 # Changelog
+2026-08-27
+A016 (Book or Defer Appointment): documented support for `SERVICE_PROVIDER_CLINICIAN` and `SERVICE_PROVIDER_CLINICIAN_ADMIN` roles, including the "Triaged - Provider To Action" state precondition for these roles (RAA-9623)
 
 ## {{ ansible_date_time.date }}
 * Initial commit

specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml

@@ -13,12 +13,18 @@ description: |
   In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles:
     - `REFERRING_CLINICIAN`
     - `REFERRING_CLINICIAN_ADMIN`
+    - `SERVICE_PROVIDER_CLINICIAN`
+    - `SERVICE_PROVIDER_CLINICIAN_ADMIN`
 
   You need to check if the service is directly bookable, indirectly bookable, or triage by either using [[HYPERLINK_A033]] or [[HYPERLINK_A035]]. You can then offer appropriate actions to authenticated users, i.e. the ability to book an appointment into a directly bookable service if an appointment slot is available, defer the booking responsibility to a directly bookable service if no appointment slot is available, refer a patient into a triage service.
 
   If the service is directly bookable, you need to retrieve available appointment slots for the service using [[HYPERLINK_A015]].
 
-  You need to use the Unique Booking Reference Number (UBRN) of a referral request in order to use this endpoint. 
+  You need to use the Unique Booking Reference Number (UBRN) of a referral request in order to use this endpoint.
+
+  If `businessFunction` is `SERVICE_PROVIDER_CLINICIAN` or `SERVICE_PROVIDER_CLINICIAN_ADMIN`, the referral must be in the 'Not Booked' state (i.e. it has been redirected to a directly bookable or triage service and is awaiting a booking, deferral, or triage decision). Calling this endpoint as a Service Provider Clinician when the referral is not in this state will return a `422` error with error code `INVALID_REQUEST_STATE`.
+
+  Where a `SERVICE_PROVIDER_CLINICIAN_ADMIN` (SPCA) is acting on behalf of a `SERVICE_PROVIDER_CLINICIAN` (SPC), the on behalf of user ID must be that of an appropriate SPC. You can use endpoint [[HYPERLINK_A040]] to determine which e-RS users a `SERVICE_PROVIDER_CLINICIAN_ADMIN` is allowed to work "on-behalf-of".
 
   ## Important note when deferring to provider
 
@@ -64,6 +70,7 @@ parameters:
   - $ref: '../headers/request/OdsCode.yaml'
   - $ref: '../headers/request/BusinessFunction.yaml'
   - $ref: '../headers/request/CorrelationID.yaml'
+  - $ref: '../headers/request/OnBehalfOfUserID.yaml'
 requestBody:
   required: true
   content: