[RAA-9685]-[RK]-[OAS Document SPC/SPCA support for A015 Retrieve Appointment

CHANGELOG.md

@@ -1,4 +1,7 @@
 # Changelog
-
-## {{ ansible_date_time.date }}
-* Initial commit
+## 15/09/2026
+* A015 (Retrieve Appointment Slots): documented support for `SERVICE_PROVIDER_CLINICIAN` and `SERVICE_PROVIDER_CLINICIAN_ADMIN` roles.
+* A015 - Enhanced ErrorOutcome.yaml with comprehensive error code documentation for retrieveAppointmentSlots
+  - Documented error conditions for referral state validation (NOT_BOOKED, TRIAGE service checks)
+  - Added response headers: X-Correlation-ID, X-Request-ID, Content-Type
+  - Configured FHIR JSON error response schema with STU3-OperationOutcome reference

sandbox/src/routes/stu3/retrieveAppointmentSlots.js

@@ -10,7 +10,7 @@ module.exports = [
     path: '/FHIR/STU3/Slot',
     handler: (request, h) => {
 
-      const allowedBusinessFunctions = ["REFERRING_CLINICIAN", "REFERRING_CLINICIAN_ADMIN"]
+      const allowedBusinessFunctions = ["REFERRING_CLINICIAN", "REFERRING_CLINICIAN_ADMIN", "SERVICE_PROVIDER_CLINICIAN", "SERVICE_PROVIDER_CLINICIAN_ADMIN"]
 
       const validationResult = validationUtils.validateBusinessFunction(request, h, allowedBusinessFunctions)
       if (validationResult) {

specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml

@@ -4,16 +4,28 @@ description: |
   ## Overview
   Use this endpoint to retrieve available appointment slots for a service.
 
+  Service provider clinicians can also use this endpoint, but only to retrieve slots for the purpose of redirecting a referral to another directly bookable service. This is only permitted when all of the following conditions are met:
+    - the referral's current holding service is of type `TRIAGE`
+    - the referral is in the `NOT_BOOKED` state
+    - the requested service is of type `APPOINTMENT`
+    - the user has a Legitimate Relationship with the referral
+
   ## Supported security patterns
   - Healthcare worker, user-restricted access
 
   ## Pre-requisites
   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`
+
+  If using the `SERVICE_PROVIDER_CLINICIAN` or `SERVICE_PROVIDER_CLINICIAN_ADMIN` role, this endpoint is only usable under the narrow conditions described in the Overview above (referral redirection from a `TRIAGE` holding service, referral in `NOT_BOOKED` state, requested service of type `APPOINTMENT`, and an existing Legitimate Relationship with the referral). Outside of these conditions, calls from these roles will be rejected.
 
   You need to have identified a directly bookable `service` that is on the current referral shortlist. You can do this by using [[HYPERLINK_A005]].
 
+  The `NHSD-eRS-Business-Function` header must be set to a role that is permitted to call this endpoint - `REFERRING_CLINICIAN`, `REFERRING_CLINICIAN_ADMIN`, `SERVICE_PROVIDER_CLINICIAN`, or `SERVICE_PROVIDER_CLINICIAN_ADMIN` are all now accepted, subject to the conditions above for the service provider roles.
+
   ## Use case
 
   As an authenticated user
@@ -22,6 +34,12 @@ description: |
 
   So that I can offer them to the patient for booking.
 
+  As a service provider clinician (`SERVICE_PROVIDER_CLINICIAN`/`SERVICE_PROVIDER_CLINICIAN_ADMIN`)
+
+  I need to retrieve a list of available appointment slots for a service while a referral is held in `TRIAGE` and not yet booked
+
+  So that I can redirect the referral to a suitable directly bookable service and book an appointment via [[HYPERLINK_A016]].
+
   ## Important note
   You need to provide the 'commissioning rule organisation' when calling [[HYPERLINK_A015]] to ensure only suitable slots are returned. You can obtain the 'commissioning rule organisation' from [[HYPERLINK_A005]].
 
@@ -38,6 +56,8 @@ description: |
     - when trying to book an appointment into a service, the slot advertised is no longer available
     - when trying to book an appointment into a service, no response is received within message timeout period (currently 2 minutes)
 
+  Service provider clinicians (`SERVICE_PROVIDER_CLINICIAN`/`SERVICE_PROVIDER_CLINICIAN_ADMIN`) use [[HYPERLINK_A015]] as part of the referral redirection workflow: retrieving slots for a suitable service before booking the redirected referral using [[HYPERLINK_A016]].
+
   ## Known Issues
   This endpoint is using the :Practitioner search parameter. The "schedule.actor" search parameter is incorrectly using the ":Practitioner" modifier. As per the [FHIR standard](https://hl7.org/fhir/R4/) the ":identifier" modifier should be used when searching to indicate that an Identifer is used rather than a literal, relative, internal or absolute reference. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
 
@@ -65,6 +85,7 @@ parameters:
   - $ref: '../headers/request/BusinessFunction.yaml'
   - $ref: '../headers/request/CorrelationID.yaml'
   - $ref: '../headers/request/ErsCommRuleOrg.yaml'
+  - $ref: '../headers/request/OnBehalfOfUserID.yaml'
   - $ref: '../queryParameters/ServiceId.yaml'
   - $ref: '../queryParameters/Priority.yaml'
   - $ref: '../queryParameters/Status.yaml'

specification/components/stu3/schemas/responses/retrieveAppointmentSlots/ErrorOutcome.yaml

@@ -9,7 +9,7 @@ description: |
   | INVALID_CODE                       | The input provided for a field is not one of the defined legal values. |
   | MISSING_PARAMETER                  | Indicates missing mandatory FHIR search parameter. |
   | MISSING_HEADER                     | Indicates missing mandatory HTTP header. |
-  | INVALID_STATE                      | Indicates that the referenced item is not in the correct state for the request to be processed. |
+  | INVALID_STATE                      | Indicates that the referenced item is not in the correct state for the request to be processed. This applies when: <br> - the referral is not in the `NOT_BOOKED` state; <br> - (`SERVICE_PROVIDER_CLINICIAN`/`SERVICE_PROVIDER_CLINICIAN_ADMIN` only) the referral's current holding service is not of type `TRIAGE`. |
   | SERVICE_UNAVAILABLE                | Indicates that a service is no longer available. |
 headers:
   X-Correlation-ID:

tests/sandbox/stu3/test_a015_get_appointment_slots.py

@@ -14,6 +14,8 @@ class TestGetAdviceAndGuidanceConversation(SandboxTest):
     allowed_business_function_data = [
         "REFERRING_CLINICIAN",
         "REFERRING_CLINICIAN_ADMIN",
+        "SERVICE_PROVIDER_CLINICIAN",
+        "SERVICE_PROVIDER_CLINICIAN_ADMIN",
     ]
 
     authorised_actor_data = Actor.all(