From 8a3fd76c7df7c2feff2271d844414a6476aa2843 Mon Sep 17 00:00:00 2001 From: David Wass Date: Tue, 7 Oct 2025 11:28:38 +0100 Subject: [PATCH 1/4] Initial Descriptions and ptl config --- scripts/config/markdownlint.yaml | 3 + .../documentation/APIDescription.md | 88 +++++++++++++++++++ .../api/components/documentation/createMI.md | 3 + .../api/components/documentation/getDataId.md | 3 + .../documentation/getLetterStatus.md | 20 +++++ .../components/documentation/headDataId.md | 3 + .../components/documentation/listLetters.md | 3 + .../components/documentation/patchLetters.md | 3 + .../components/documentation/postLetters.md | 3 + .../api/components/endpoints/createMI.yml | 2 + .../api/components/endpoints/getDataId.yml | 2 + .../components/endpoints/getLetterStatus.yml | 20 +---- .../api/components/endpoints/headDataId.yml | 2 + .../api/components/endpoints/listLetters.yml | 3 +- .../api/components/endpoints/patchLetter.yml | 2 + .../api/components/endpoints/postLetters.yml | 2 + .../api/components/security/security-int.yml | 1 + .../api/components/security/security-prod.yml | 1 + .../api/components/security/security-ref.yml | 1 + .../api/components/security/security.yml | 2 +- .../api/components/x-nhsd-apim/access-int.yml | 3 + .../components/x-nhsd-apim/access-prod.yml | 3 + .../api/components/x-nhsd-apim/access-ref.yml | 3 + .../api/components/x-nhsd-apim/access.yml | 2 +- .../api/components/x-nhsd-apim/target-int.yml | 6 ++ .../components/x-nhsd-apim/target-prod.yml | 6 ++ .../api/components/x-nhsd-apim/target-ref.yml | 6 ++ .../api/components/x-nhsd-apim/target.yml | 2 +- specification/api/notify-supplier-phase1.yml | 7 +- 29 files changed, 178 insertions(+), 27 deletions(-) create mode 100644 specification/api/components/documentation/APIDescription.md create mode 100644 specification/api/components/documentation/createMI.md create mode 100644 specification/api/components/documentation/getDataId.md create mode 100644 specification/api/components/documentation/getLetterStatus.md create mode 100644 specification/api/components/documentation/headDataId.md create mode 100644 specification/api/components/documentation/listLetters.md create mode 100644 specification/api/components/documentation/patchLetters.md create mode 100644 specification/api/components/documentation/postLetters.md create mode 100644 specification/api/components/security/security-int.yml create mode 100644 specification/api/components/security/security-prod.yml create mode 100644 specification/api/components/security/security-ref.yml create mode 100644 specification/api/components/x-nhsd-apim/access-int.yml create mode 100644 specification/api/components/x-nhsd-apim/access-prod.yml create mode 100644 specification/api/components/x-nhsd-apim/access-ref.yml create mode 100644 specification/api/components/x-nhsd-apim/target-int.yml create mode 100644 specification/api/components/x-nhsd-apim/target-prod.yml create mode 100644 specification/api/components/x-nhsd-apim/target-ref.yml diff --git a/scripts/config/markdownlint.yaml b/scripts/config/markdownlint.yaml index 554ab554b..9f92b8daf 100644 --- a/scripts/config/markdownlint.yaml +++ b/scripts/config/markdownlint.yaml @@ -9,3 +9,6 @@ MD024: # https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md MD033: false + +MD041: + level: 2 diff --git a/specification/api/components/documentation/APIDescription.md b/specification/api/components/documentation/APIDescription.md new file mode 100644 index 000000000..4727434bb --- /dev/null +++ b/specification/api/components/documentation/APIDescription.md @@ -0,0 +1,88 @@ +## Overview + +API for communication suppliers to integrate with NHS Notify. + +This specification represents the in-development 'next' version of the API schema +and should be treated as unstable + +Use this API to retrieve letters to be printed + +## Who can use this API + +The NHS Notify Supplier service is intended for suppliers of print services to the [NHS Notify](https://digital.nhs.uk/services/nhs-notify) service + +## Related APIs + +The [NHS Notify API](https://digital.nhs.uk/developer/api-catalogue/nhs-notify) is used to send messages to citizens via NHS App, email, text message or letter. + +## API status and roadmap + +This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses) meaning: + +* it is available for testing in the integration environment +* we expect to make breaking changes based on developer feedback + +## Service Level + +TBD + +For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels). + +## Technology + +This API is a [REST-based](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest) API. + +We follow the [JSON:API](https://jsonapi.org/) standard for our request and response schemas. + +### Response content types + +This API can generate responses in the following formats: + +* `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction) + +## Network access + +This API is available on the internet and, indirectly on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network). + +For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis). + +## Security and authorisation + +This API is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate the calling application but not the end user. + +Authentication and authorisation of end users is the responsibility of your application. + +To access this API, use the following security pattern: + +* [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) + +## Environments and testing + +| Environment | Base URL | +|------------ | -------- | +| Sandbox | `https://sandbox.api.service.nhs.uk/comms` | +| Integration test | `https://int.api.service.nhs.uk/comms` | +| Production | `https://api.service.nhs.uk/comms` | + +### Sandbox testing + +Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing): + +* is for early developer testing +* only covers a limited set of scenarios +* is stateless, so does not actually persist any updates +* is open access, so does not allow you to test authorisation + +For details of sandbox test scenarios, or to try out sandbox using our 'Try this API' feature, see the documentation for each endpoint. + +### Integration testing + +Our integration test environment: + +* is for formal integration sandbox-testing +* is stateful, so persists updates +* includes authorisation via [signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) + +You need to get your software approved by us before it can go live with this API. + +You will also need to follow our steps to - TBD diff --git a/specification/api/components/documentation/createMI.md b/specification/api/components/documentation/createMI.md new file mode 100644 index 000000000..614953daa --- /dev/null +++ b/specification/api/components/documentation/createMI.md @@ -0,0 +1,3 @@ +## Overview + +Use this endpoint to create management information diff --git a/specification/api/components/documentation/getDataId.md b/specification/api/components/documentation/getDataId.md new file mode 100644 index 000000000..5d6cd7fe2 --- /dev/null +++ b/specification/api/components/documentation/getDataId.md @@ -0,0 +1,3 @@ +## Overview + +Use this endpoint to get letter data diff --git a/specification/api/components/documentation/getLetterStatus.md b/specification/api/components/documentation/getLetterStatus.md new file mode 100644 index 000000000..86a264aa1 --- /dev/null +++ b/specification/api/components/documentation/getLetterStatus.md @@ -0,0 +1,20 @@ +## Overview + +Use this endpoint to get details the status of a letter. + +## Sandbox test scenarios + +You can test the following scenarios in our sandbox environment + +| Scenario | Letter Id | +| ----------------------------------------| ---------------------------- | +| Retrieve a PENDING letter status | `24L5eYSWGzCHlGmzNxuqVusPxDg`| +| Retrieve a ACCEPTED letter status | `2AL5eYSWGzCHlGmzNxuqVusPxDg`| +| Retrieve a PRINTED letter status | `2BL5eYSWGzCHlGmzNxuqVusPxDg`| +| Retrieve a ENCLOSED letter status | `2CL5eYSWGzCHlGmzNxuqVusPxDg`| +| Retrieve a DISPATCHED letter status | `2DL5eYSWGzCHlGmzNxuqVusPxDg`| +| Retrieve a DELIVERED letter status | `2EL5eYSWGzCHlGmzNxuqVusPxDg`| +| Retrieve a REJECTED letter status | `2WL5eYSWGzCHlGmzNxuqVusPxDg`| +| Retrieve a CANCELLED letter status | `2XL5eYSWGzCHlGmzNxuqVusPxDg`| +| Retrieve a FAILED letter status | `2YL5eYSWGzCHlGmzNxuqVusPxDg`| +| Retrieve a RETURNED letter status | `2ZL5eYSWGzCHlGmzNxuqVusPxDg`| diff --git a/specification/api/components/documentation/headDataId.md b/specification/api/components/documentation/headDataId.md new file mode 100644 index 000000000..04223d874 --- /dev/null +++ b/specification/api/components/documentation/headDataId.md @@ -0,0 +1,3 @@ +## Overview + +Use this endpoint to check for the existence of letter data diff --git a/specification/api/components/documentation/listLetters.md b/specification/api/components/documentation/listLetters.md new file mode 100644 index 000000000..08a1bb10c --- /dev/null +++ b/specification/api/components/documentation/listLetters.md @@ -0,0 +1,3 @@ +## Overview + +The key use of this endpoint is to query letters which are ready to be printed diff --git a/specification/api/components/documentation/patchLetters.md b/specification/api/components/documentation/patchLetters.md new file mode 100644 index 000000000..9ee589266 --- /dev/null +++ b/specification/api/components/documentation/patchLetters.md @@ -0,0 +1,3 @@ +## Overview + +Update the status of a letter by providing the new status in the request body. diff --git a/specification/api/components/documentation/postLetters.md b/specification/api/components/documentation/postLetters.md new file mode 100644 index 000000000..d0172633b --- /dev/null +++ b/specification/api/components/documentation/postLetters.md @@ -0,0 +1,3 @@ +## Overview + +Update the status of multiple letters by providing the new statuses in the request body. diff --git a/specification/api/components/endpoints/createMI.yml b/specification/api/components/endpoints/createMI.yml index edfead9b7..277870f72 100644 --- a/specification/api/components/endpoints/createMI.yml +++ b/specification/api/components/endpoints/createMI.yml @@ -1,4 +1,6 @@ summary: Create a new MI record +description: + $ref: '../documentation/createMI.md' operationId: createMI tags: - mi diff --git a/specification/api/components/endpoints/getDataId.yml b/specification/api/components/endpoints/getDataId.yml index db949b23e..c7574df40 100644 --- a/specification/api/components/endpoints/getDataId.yml +++ b/specification/api/components/endpoints/getDataId.yml @@ -1,4 +1,6 @@ summary: Fetch a data file +description: + $ref: '../documentation/getDataId.md' operationId: getDataId tags: - data diff --git a/specification/api/components/endpoints/getLetterStatus.yml b/specification/api/components/endpoints/getLetterStatus.yml index eed23ab02..bee57b469 100644 --- a/specification/api/components/endpoints/getLetterStatus.yml +++ b/specification/api/components/endpoints/getLetterStatus.yml @@ -1,22 +1,6 @@ summary: Retrieve the status of a letter -description: | - ## Get details the status of a letter. - - ## Sandbox test scenarios - You can test the following scenarios in our sandbox environment - - | Scenario | Letter Id | - | ----------------------------------------| ---------------------------- | - | Retrieve a PENDING letter status | `24L5eYSWGzCHlGmzNxuqVusPxDg`| - | Retrieve a ACCEPTED letter status | `2AL5eYSWGzCHlGmzNxuqVusPxDg`| - | Retrieve a PRINTED letter status | `2BL5eYSWGzCHlGmzNxuqVusPxDg`| - | Retrieve a ENCLOSED letter status | `2CL5eYSWGzCHlGmzNxuqVusPxDg`| - | Retrieve a DISPATCHED letter status | `2DL5eYSWGzCHlGmzNxuqVusPxDg`| - | Retrieve a DELIVERED letter status | `2EL5eYSWGzCHlGmzNxuqVusPxDg`| - | Retrieve a REJECTED letter status | `2WL5eYSWGzCHlGmzNxuqVusPxDg`| - | Retrieve a CANCELLED letter status | `2XL5eYSWGzCHlGmzNxuqVusPxDg`| - | Retrieve a FAILED letter status | `2YL5eYSWGzCHlGmzNxuqVusPxDg`| - | Retrieve a RETURNED letter status | `2ZL5eYSWGzCHlGmzNxuqVusPxDg`| +description: + $ref: '../documentation/getLetterStatus.md' operationId: getLetterStatus responses: "200": diff --git a/specification/api/components/endpoints/headDataId.yml b/specification/api/components/endpoints/headDataId.yml index 7c09cf5e1..ce692737c 100644 --- a/specification/api/components/endpoints/headDataId.yml +++ b/specification/api/components/endpoints/headDataId.yml @@ -1,4 +1,6 @@ summary: Check for the existence of a data file +description: + $ref: '../documentation/headDataId.md' tags: - data responses: diff --git a/specification/api/components/endpoints/listLetters.yml b/specification/api/components/endpoints/listLetters.yml index 9d5898c8d..ab877e52f 100644 --- a/specification/api/components/endpoints/listLetters.yml +++ b/specification/api/components/endpoints/listLetters.yml @@ -7,7 +7,8 @@ parameters: # - $ref: "../parameters/letterStatus.yml" # - $ref: "../parameters/pageNumber.yml" - $ref: "../parameters/limit.yml" -description: The key use of this endpoint is to query letters which are ready to be printed +description: + $ref: '../documentation/listLetters.md' responses: '200': $ref: "../responses/getLetters200.yml" diff --git a/specification/api/components/endpoints/patchLetter.yml b/specification/api/components/endpoints/patchLetter.yml index 411d1b64e..58065cebc 100644 --- a/specification/api/components/endpoints/patchLetter.yml +++ b/specification/api/components/endpoints/patchLetter.yml @@ -1,6 +1,8 @@ summary: Update the status of a letter description: Update the status of a letter by providing the new status in the request body. operationId: patchLetter +description: + $ref: '../documentation/patchLetters.md' requestBody: $ref: "../requests/patchLetterRequest.yml" responses: diff --git a/specification/api/components/endpoints/postLetters.yml b/specification/api/components/endpoints/postLetters.yml index b49fd2d44..54c5fabaf 100644 --- a/specification/api/components/endpoints/postLetters.yml +++ b/specification/api/components/endpoints/postLetters.yml @@ -1,4 +1,6 @@ summary: Update the status of multiple letters +description: + $ref: '../documentation/postLetters.md' operationId: postLetters tags: - letter diff --git a/specification/api/components/security/security-int.yml b/specification/api/components/security/security-int.yml new file mode 100644 index 000000000..878d7f275 --- /dev/null +++ b/specification/api/components/security/security-int.yml @@ -0,0 +1 @@ +app-level3: [ ] diff --git a/specification/api/components/security/security-prod.yml b/specification/api/components/security/security-prod.yml new file mode 100644 index 000000000..878d7f275 --- /dev/null +++ b/specification/api/components/security/security-prod.yml @@ -0,0 +1 @@ +app-level3: [ ] diff --git a/specification/api/components/security/security-ref.yml b/specification/api/components/security/security-ref.yml new file mode 100644 index 000000000..878d7f275 --- /dev/null +++ b/specification/api/components/security/security-ref.yml @@ -0,0 +1 @@ +app-level3: [ ] diff --git a/specification/api/components/security/security.yml b/specification/api/components/security/security.yml index 58151922d..393524ce3 100644 --- a/specification/api/components/security/security.yml +++ b/specification/api/components/security/security.yml @@ -1 +1 @@ -$ref: security-sandbox.yml +$ref: security-prod.yml diff --git a/specification/api/components/x-nhsd-apim/access-int.yml b/specification/api/components/x-nhsd-apim/access-int.yml new file mode 100644 index 000000000..de21d5dc5 --- /dev/null +++ b/specification/api/components/x-nhsd-apim/access-int.yml @@ -0,0 +1,3 @@ +- title: Application Restricted + grants: + app-level3: [] diff --git a/specification/api/components/x-nhsd-apim/access-prod.yml b/specification/api/components/x-nhsd-apim/access-prod.yml new file mode 100644 index 000000000..de21d5dc5 --- /dev/null +++ b/specification/api/components/x-nhsd-apim/access-prod.yml @@ -0,0 +1,3 @@ +- title: Application Restricted + grants: + app-level3: [] diff --git a/specification/api/components/x-nhsd-apim/access-ref.yml b/specification/api/components/x-nhsd-apim/access-ref.yml new file mode 100644 index 000000000..de21d5dc5 --- /dev/null +++ b/specification/api/components/x-nhsd-apim/access-ref.yml @@ -0,0 +1,3 @@ +- title: Application Restricted + grants: + app-level3: [] diff --git a/specification/api/components/x-nhsd-apim/access.yml b/specification/api/components/x-nhsd-apim/access.yml index 95f5f0b94..c69c222d1 100644 --- a/specification/api/components/x-nhsd-apim/access.yml +++ b/specification/api/components/x-nhsd-apim/access.yml @@ -1 +1 @@ -$ref: access-sandbox.yml +$ref: access-prod.yml diff --git a/specification/api/components/x-nhsd-apim/target-int.yml b/specification/api/components/x-nhsd-apim/target-int.yml new file mode 100644 index 000000000..040d1228c --- /dev/null +++ b/specification/api/components/x-nhsd-apim/target-int.yml @@ -0,0 +1,6 @@ +type: external +healthcheck: /_status +url: https://suppliers.int.nhsnotify.national.nhs.uk +security: + type: mtls + secret: nhs-notify-supplier-mtls-int diff --git a/specification/api/components/x-nhsd-apim/target-prod.yml b/specification/api/components/x-nhsd-apim/target-prod.yml new file mode 100644 index 000000000..70f523ca2 --- /dev/null +++ b/specification/api/components/x-nhsd-apim/target-prod.yml @@ -0,0 +1,6 @@ +type: external +healthcheck: /_status +url: https://suppliers.prod.nhsnotify.national.nhs.uk +security: + type: mtls + secret: nhs-notify-supplier-mtls-prod diff --git a/specification/api/components/x-nhsd-apim/target-ref.yml b/specification/api/components/x-nhsd-apim/target-ref.yml new file mode 100644 index 000000000..8ace3f78e --- /dev/null +++ b/specification/api/components/x-nhsd-apim/target-ref.yml @@ -0,0 +1,6 @@ +type: external +healthcheck: /_status +url: https://suppliers.ref.nhsnotify.national.nhs.uk +security: + type: mtls + secret: nhs-notify-supplier-mtls-ref diff --git a/specification/api/components/x-nhsd-apim/target.yml b/specification/api/components/x-nhsd-apim/target.yml index b24b21da4..a0f578ca7 100644 --- a/specification/api/components/x-nhsd-apim/target.yml +++ b/specification/api/components/x-nhsd-apim/target.yml @@ -1 +1 @@ -$ref: target-sandbox.yml +$ref: target-prod.yml diff --git a/specification/api/notify-supplier-phase1.yml b/specification/api/notify-supplier-phase1.yml index 4a588b025..9b7672ada 100644 --- a/specification/api/notify-supplier-phase1.yml +++ b/specification/api/notify-supplier-phase1.yml @@ -2,11 +2,8 @@ openapi: 3.0.3 info: version: next title: NHS Notify Supplier API - description: | - API for communication suppliers to integrate with NHS Notify. - - This specification represents the in-development 'next' version of the API schema - and should be treated as unstable. + description: + $ref: 'components/documentation/APIDescription.md' security: - $ref: 'components/security/security.yml' paths: From 050d6f5b6f2a4791bd7c657e045af888798c3386 Mon Sep 17 00:00:00 2001 From: David Wass Date: Tue, 7 Oct 2025 15:15:51 +0100 Subject: [PATCH 2/4] Fix location of oas file for artifact upload --- .github/actions/build-sdk/action.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/actions/build-sdk/action.yml b/.github/actions/build-sdk/action.yml index 95da5b22f..0443d76c6 100644 --- a/.github/actions/build-sdk/action.yml +++ b/.github/actions/build-sdk/action.yml @@ -53,7 +53,7 @@ runs: - name: Upload API OAS specification artifact uses: actions/upload-artifact@v4 with: - path: "specification/api" + path: "build" name: api-oas-specification-${{ inputs.version }} - name: Upload html artifact From 0375c3ef0d66456ac321d13ebcdbd4a69ae08998 Mon Sep 17 00:00:00 2001 From: David Wass Date: Tue, 7 Oct 2025 15:29:58 +0100 Subject: [PATCH 3/4] Updated reason code to string --- ...getLetter-2WL5eYSWGzCHlGmzNxuqVusPxDg.json | 2 +- ...getLetter-2XL5eYSWGzCHlGmzNxuqVusPxDg.json | 2 +- ...getLetter-2YL5eYSWGzCHlGmzNxuqVusPxDg.json | 2 +- ...getLetter-2ZL5eYSWGzCHlGmzNxuqVusPxDg.json | 2 +- .../requests/patchLetter_CANCELLED.json | 2 +- .../requests/patchLetter_FAILED.json | 2 +- .../requests/patchLetter_REJECTED.json | 2 +- .../requests/patchLetter_RETURNED.json | 2 +- .../responses/patchLetter_CANCELLED.json | 2 +- .../responses/patchLetter_FAILED.json | 2 +- .../responses/patchLetter_REJECTED.json | 2 +- .../responses/patchLetter_RETURNED.json | 2 +- .../postLetter/requests/postLetters.json | 8 +++--- .../api/components/documentation/createMI.md | 16 ++++++++++- .../api/components/documentation/getDataId.md | 13 ++++++++- .../documentation/getLetterStatus.md | 4 ++- .../components/documentation/headDataId.md | 11 +++++++- .../components/documentation/listLetters.md | 7 ++++- .../components/documentation/patchLetter.md | 27 +++++++++++++++++++ .../components/documentation/patchLetters.md | 3 --- .../components/documentation/postLetters.md | 26 +++++++++++++++++- .../api/components/endpoints/createMI.yml | 2 ++ .../api/components/endpoints/patchLetter.yml | 3 +-- .../api/components/schemas/letterItem.yml | 8 ++---- .../components/schemas/letterUpdateItem.yml | 8 ++---- .../api/components/schemas/reasonCode.yml | 3 +++ .../api/components/schemas/reasonText.yml | 3 +++ 27 files changed, 127 insertions(+), 39 deletions(-) create mode 100644 specification/api/components/documentation/patchLetter.md delete mode 100644 specification/api/components/documentation/patchLetters.md create mode 100644 specification/api/components/schemas/reasonCode.yml create mode 100644 specification/api/components/schemas/reasonText.yml diff --git a/sandbox/data/examples/getLetter/responses/getLetter-2WL5eYSWGzCHlGmzNxuqVusPxDg.json b/sandbox/data/examples/getLetter/responses/getLetter-2WL5eYSWGzCHlGmzNxuqVusPxDg.json index c0b542175..ec685a98b 100644 --- a/sandbox/data/examples/getLetter/responses/getLetter-2WL5eYSWGzCHlGmzNxuqVusPxDg.json +++ b/sandbox/data/examples/getLetter/responses/getLetter-2WL5eYSWGzCHlGmzNxuqVusPxDg.json @@ -2,7 +2,7 @@ "data": { "attributes": { "groupId": "c5d93f917f5546d08beccf770a915d96", - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg", "status": "REJECTED" diff --git a/sandbox/data/examples/getLetter/responses/getLetter-2XL5eYSWGzCHlGmzNxuqVusPxDg.json b/sandbox/data/examples/getLetter/responses/getLetter-2XL5eYSWGzCHlGmzNxuqVusPxDg.json index ff627ba76..d37729d62 100644 --- a/sandbox/data/examples/getLetter/responses/getLetter-2XL5eYSWGzCHlGmzNxuqVusPxDg.json +++ b/sandbox/data/examples/getLetter/responses/getLetter-2XL5eYSWGzCHlGmzNxuqVusPxDg.json @@ -2,7 +2,7 @@ "data": { "attributes": { "groupId": "c5d93f917f5546d08beccf770a915d96", - "reasonCode": 100, + "reasonCode": "R01", "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg", "status": "CANCELLED" }, diff --git a/sandbox/data/examples/getLetter/responses/getLetter-2YL5eYSWGzCHlGmzNxuqVusPxDg.json b/sandbox/data/examples/getLetter/responses/getLetter-2YL5eYSWGzCHlGmzNxuqVusPxDg.json index d9112401d..945e8270b 100644 --- a/sandbox/data/examples/getLetter/responses/getLetter-2YL5eYSWGzCHlGmzNxuqVusPxDg.json +++ b/sandbox/data/examples/getLetter/responses/getLetter-2YL5eYSWGzCHlGmzNxuqVusPxDg.json @@ -2,7 +2,7 @@ "data": { "attributes": { "groupId": "c5d93f917f5546d08beccf770a915d96", - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg", "status": "FAILED" diff --git a/sandbox/data/examples/getLetter/responses/getLetter-2ZL5eYSWGzCHlGmzNxuqVusPxDg.json b/sandbox/data/examples/getLetter/responses/getLetter-2ZL5eYSWGzCHlGmzNxuqVusPxDg.json index 7e471a474..fff8bf1dd 100644 --- a/sandbox/data/examples/getLetter/responses/getLetter-2ZL5eYSWGzCHlGmzNxuqVusPxDg.json +++ b/sandbox/data/examples/getLetter/responses/getLetter-2ZL5eYSWGzCHlGmzNxuqVusPxDg.json @@ -2,7 +2,7 @@ "data": { "attributes": { "groupId": "c5d93f917f5546d08beccf770a915d96", - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg", "status": "RETURNED" diff --git a/sandbox/data/examples/patchLetter/requests/patchLetter_CANCELLED.json b/sandbox/data/examples/patchLetter/requests/patchLetter_CANCELLED.json index fd6e5e9ff..7106a2f53 100644 --- a/sandbox/data/examples/patchLetter/requests/patchLetter_CANCELLED.json +++ b/sandbox/data/examples/patchLetter/requests/patchLetter_CANCELLED.json @@ -1,7 +1,7 @@ { "data": { "attributes": { - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "status": "CANCELLED" }, diff --git a/sandbox/data/examples/patchLetter/requests/patchLetter_FAILED.json b/sandbox/data/examples/patchLetter/requests/patchLetter_FAILED.json index 4398da84b..359d9bc3d 100644 --- a/sandbox/data/examples/patchLetter/requests/patchLetter_FAILED.json +++ b/sandbox/data/examples/patchLetter/requests/patchLetter_FAILED.json @@ -1,7 +1,7 @@ { "data": { "attributes": { - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "status": "FAILED" }, diff --git a/sandbox/data/examples/patchLetter/requests/patchLetter_REJECTED.json b/sandbox/data/examples/patchLetter/requests/patchLetter_REJECTED.json index 5b54d3fb7..c44c0558e 100644 --- a/sandbox/data/examples/patchLetter/requests/patchLetter_REJECTED.json +++ b/sandbox/data/examples/patchLetter/requests/patchLetter_REJECTED.json @@ -1,7 +1,7 @@ { "data": { "attributes": { - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "status": "REJECTED" }, diff --git a/sandbox/data/examples/patchLetter/requests/patchLetter_RETURNED.json b/sandbox/data/examples/patchLetter/requests/patchLetter_RETURNED.json index 5b54d3fb7..c44c0558e 100644 --- a/sandbox/data/examples/patchLetter/requests/patchLetter_RETURNED.json +++ b/sandbox/data/examples/patchLetter/requests/patchLetter_RETURNED.json @@ -1,7 +1,7 @@ { "data": { "attributes": { - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "status": "REJECTED" }, diff --git a/sandbox/data/examples/patchLetter/responses/patchLetter_CANCELLED.json b/sandbox/data/examples/patchLetter/responses/patchLetter_CANCELLED.json index c73ad66b5..a05095196 100644 --- a/sandbox/data/examples/patchLetter/responses/patchLetter_CANCELLED.json +++ b/sandbox/data/examples/patchLetter/responses/patchLetter_CANCELLED.json @@ -1,7 +1,7 @@ { "data": { "attributes": { - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg", "status": "CANCELLED" diff --git a/sandbox/data/examples/patchLetter/responses/patchLetter_FAILED.json b/sandbox/data/examples/patchLetter/responses/patchLetter_FAILED.json index c5b2c5a96..b2c2f9025 100644 --- a/sandbox/data/examples/patchLetter/responses/patchLetter_FAILED.json +++ b/sandbox/data/examples/patchLetter/responses/patchLetter_FAILED.json @@ -1,7 +1,7 @@ { "data": { "attributes": { - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg", "status": "FAILED" diff --git a/sandbox/data/examples/patchLetter/responses/patchLetter_REJECTED.json b/sandbox/data/examples/patchLetter/responses/patchLetter_REJECTED.json index 706b8df85..98a205e55 100644 --- a/sandbox/data/examples/patchLetter/responses/patchLetter_REJECTED.json +++ b/sandbox/data/examples/patchLetter/responses/patchLetter_REJECTED.json @@ -1,7 +1,7 @@ { "data": { "attributes": { - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg", "status": "REJECTED" diff --git a/sandbox/data/examples/patchLetter/responses/patchLetter_RETURNED.json b/sandbox/data/examples/patchLetter/responses/patchLetter_RETURNED.json index 0c80fcc58..eb3a70a07 100644 --- a/sandbox/data/examples/patchLetter/responses/patchLetter_RETURNED.json +++ b/sandbox/data/examples/patchLetter/responses/patchLetter_RETURNED.json @@ -1,7 +1,7 @@ { "data": { "attributes": { - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg", "status": "RETURNED" diff --git a/sandbox/data/examples/postLetter/requests/postLetters.json b/sandbox/data/examples/postLetter/requests/postLetters.json index c5d605981..1b42413dc 100644 --- a/sandbox/data/examples/postLetter/requests/postLetters.json +++ b/sandbox/data/examples/postLetter/requests/postLetters.json @@ -44,7 +44,7 @@ }, { "attributes": { - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "status": "RETURNED" }, @@ -53,7 +53,7 @@ }, { "attributes": { - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "status": "CANCELLED" }, @@ -62,7 +62,7 @@ }, { "attributes": { - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "status": "FAILED" }, @@ -71,7 +71,7 @@ }, { "attributes": { - "reasonCode": 100, + "reasonCode": "R01", "reasonText": "failed validation", "status": "RETURNED" }, diff --git a/specification/api/components/documentation/createMI.md b/specification/api/components/documentation/createMI.md index 614953daa..3b5777445 100644 --- a/specification/api/components/documentation/createMI.md +++ b/specification/api/components/documentation/createMI.md @@ -1,3 +1,17 @@ ## Overview -Use this endpoint to create management information +Submit a Management Information (MI) record for your activity (counts and costs for letters). + +When you submit a create management information request, the endpoint will respond with a created(201) response code along with the created data including a unique id for the record or an unsuccessful (4xx/%xx) response + +Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later + +## Sandbox test scenarios + +You can test the following scenarios in our sandbox environment. + +|Scenario|Request|Response| +|--------|-------|--------| +|Success|Request for successful MI record Creation| 201 (Created) with the created management information in the response| +|Invalid Request|Invalid Request for MI record Creation| 400 (Bad Request) with the error details in the body| +|Unknown specification|Request for MI record Creation for unknown spec|404 (Not Found) with the error details in the body| diff --git a/specification/api/components/documentation/getDataId.md b/specification/api/components/documentation/getDataId.md index 5d6cd7fe2..a2506f80c 100644 --- a/specification/api/components/documentation/getDataId.md +++ b/specification/api/components/documentation/getDataId.md @@ -1,3 +1,14 @@ ## Overview -Use this endpoint to get letter data +Download the data file for a letter via a redirect to a signed URL. + +Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later + +## Sandbox test scenarios + +You can test the following scenarios in our sandbox environment. + +|Scenario|Request ID|Response| +|--------|-------|--------| +|Success | 2AL5eYSWGzCHlGmzNxuqVusPxDg | Returns 303 (See Other) and URL to [http://example.com](http://example.com) in the Location header | +|Not Found |2WL5eYSWGzCHlGmzNxuqVusPxDg | Returns 404 Not found and error details in the response | diff --git a/specification/api/components/documentation/getLetterStatus.md b/specification/api/components/documentation/getLetterStatus.md index 86a264aa1..b8542d780 100644 --- a/specification/api/components/documentation/getLetterStatus.md +++ b/specification/api/components/documentation/getLetterStatus.md @@ -1,6 +1,8 @@ ## Overview -Use this endpoint to get details the status of a letter. +Get the current status of a single letter by its ID. + +Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later ## Sandbox test scenarios diff --git a/specification/api/components/documentation/headDataId.md b/specification/api/components/documentation/headDataId.md index 04223d874..c3755877c 100644 --- a/specification/api/components/documentation/headDataId.md +++ b/specification/api/components/documentation/headDataId.md @@ -1,3 +1,12 @@ ## Overview -Use this endpoint to check for the existence of letter data +Check whether a data file exists for a letter without downloading it. + +## Sandbox test scenarios + +You can test the following scenarios in our sandbox environment. + +|Scenario|Request ID|Response| +|--------|-------|--------| +|Success | 2AL5eYSWGzCHlGmzNxuqVusPxDg | Returns 200 (OK)| +|Not Found |2WL5eYSWGzCHlGmzNxuqVusPxDg | Returns 404 (Not found) | diff --git a/specification/api/components/documentation/listLetters.md b/specification/api/components/documentation/listLetters.md index 08a1bb10c..5d148c1cd 100644 --- a/specification/api/components/documentation/listLetters.md +++ b/specification/api/components/documentation/listLetters.md @@ -1,3 +1,8 @@ ## Overview -The key use of this endpoint is to query letters which are ready to be printed +Get a LIST of **PENDING** letters that are ready to print . + +Returns letters whose `status` is **PENDING**. +Use `limit` to control list size (max 2500). + +Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later diff --git a/specification/api/components/documentation/patchLetter.md b/specification/api/components/documentation/patchLetter.md new file mode 100644 index 000000000..ecc598a6c --- /dev/null +++ b/specification/api/components/documentation/patchLetter.md @@ -0,0 +1,27 @@ +## Overview + +Update the status of a single letter by its ID, optionally providing a reason code and text. + +When you make a PATCH request with your application, the endpoint will respond with a successful (200) response code, along with the updated patient resource or an unsuccessful (4xx/5xx) response. + +Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later. + +### Statuses + +Allowed `status` values that can be used to are: + +- `ACCEPTED` +- `CANCELLED` +- `DELIVERED` +- `DESTROYED` +- `DISPATCHED` +- `ENCLOSED` +- `FAILED` +- `FORWARDED` +- `PRINTED` +- `REJECTED` +- `RETURNED` + +It is not possible to update a letter to status of `PENDING`. + +Optionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body. diff --git a/specification/api/components/documentation/patchLetters.md b/specification/api/components/documentation/patchLetters.md deleted file mode 100644 index 9ee589266..000000000 --- a/specification/api/components/documentation/patchLetters.md +++ /dev/null @@ -1,3 +0,0 @@ -## Overview - -Update the status of a letter by providing the new status in the request body. diff --git a/specification/api/components/documentation/postLetters.md b/specification/api/components/documentation/postLetters.md index d0172633b..6c6f3492d 100644 --- a/specification/api/components/documentation/postLetters.md +++ b/specification/api/components/documentation/postLetters.md @@ -1,3 +1,27 @@ ## Overview -Update the status of multiple letters by providing the new statuses in the request body. +Update the status for (example, PRINTED, DISPATCHED, DELIVERED) of multiple letters by providing the new statuses in the request body, optionally including reason codes and text. + +When you make a POST update request with, the endpoint will respond with a successful (202) response code or an unsuccessful (4xx/5xx) response. + +Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later. + +### Statuses + +Allowed `status` values that can be used to are: + +- `ACCEPTED` +- `CANCELLED` +- `DELIVERED` +- `DESTROYED` +- `DISPATCHED` +- `ENCLOSED` +- `FAILED` +- `FORWARDED` +- `PRINTED` +- `REJECTED` +- `RETURNED` + +It is not possible to update a letter to status of `PENDING`. + +Optionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body for each update. diff --git a/specification/api/components/endpoints/createMI.yml b/specification/api/components/endpoints/createMI.yml index 277870f72..09d0ebce6 100644 --- a/specification/api/components/endpoints/createMI.yml +++ b/specification/api/components/endpoints/createMI.yml @@ -9,6 +9,8 @@ requestBody: responses: '201': $ref: "../responses/postMI201.yml" + '400': + $ref: "../responses/errors/badRequest.yml" '404': $ref: "../responses/errors/resourceNotFound.yml" '429': diff --git a/specification/api/components/endpoints/patchLetter.yml b/specification/api/components/endpoints/patchLetter.yml index 58065cebc..a6e9cff5f 100644 --- a/specification/api/components/endpoints/patchLetter.yml +++ b/specification/api/components/endpoints/patchLetter.yml @@ -1,8 +1,7 @@ summary: Update the status of a letter -description: Update the status of a letter by providing the new status in the request body. operationId: patchLetter description: - $ref: '../documentation/patchLetters.md' + $ref: '../documentation/patchLetter.md' requestBody: $ref: "../requests/patchLetterRequest.yml" responses: diff --git a/specification/api/components/schemas/letterItem.yml b/specification/api/components/schemas/letterItem.yml index ee6d53187..a62bd6fdb 100644 --- a/specification/api/components/schemas/letterItem.yml +++ b/specification/api/components/schemas/letterItem.yml @@ -21,10 +21,6 @@ properties: status: $ref: "./letterStatus.yml" reasonCode: - type: number - description: Reason code for the given status - example: 100 + $ref: "./reasonCode.yml" reasonText: - type: string - description: Reason text for the given status - example: failed validation + $ref: "./reasonText.yml" diff --git a/specification/api/components/schemas/letterUpdateItem.yml b/specification/api/components/schemas/letterUpdateItem.yml index ea23bbb44..f85545411 100644 --- a/specification/api/components/schemas/letterUpdateItem.yml +++ b/specification/api/components/schemas/letterUpdateItem.yml @@ -18,10 +18,6 @@ properties: status: $ref: "./letterStatus.yml" reasonCode: - type: number - description: Reason code for the given status - example: 100 + $ref: "./reasonCode.yml" reasonText: - type: string - description: Reason text for the given status - example: failed validation + $ref: "./reasonText.yml" diff --git a/specification/api/components/schemas/reasonCode.yml b/specification/api/components/schemas/reasonCode.yml new file mode 100644 index 000000000..2ed2fcff3 --- /dev/null +++ b/specification/api/components/schemas/reasonCode.yml @@ -0,0 +1,3 @@ +type: string +description: Reason code for the given status +example: "R01" diff --git a/specification/api/components/schemas/reasonText.yml b/specification/api/components/schemas/reasonText.yml new file mode 100644 index 000000000..796f633be --- /dev/null +++ b/specification/api/components/schemas/reasonText.yml @@ -0,0 +1,3 @@ +type: string +description: Reason text for the given status +example: failed validation From 829f60057be8b483397bf3deec386115801eb5c0 Mon Sep 17 00:00:00 2001 From: David Wass Date: Tue, 14 Oct 2025 13:48:03 +0100 Subject: [PATCH 4/4] Review Comments --- .../config/vocabularies/words/accept.txt | 2 +- .../documentation/APIDescription.md | 54 +++++++++++++++---- .../api/components/documentation/createMI.md | 4 +- .../api/components/documentation/getDataId.md | 2 +- .../documentation/getLetterStatus.md | 2 +- .../components/documentation/headDataId.md | 2 +- .../components/documentation/listLetters.md | 2 +- .../components/documentation/patchLetter.md | 2 +- .../components/documentation/postLetters.md | 4 +- specification/api/notify-supplier-phase1.yml | 6 +-- 10 files changed, 57 insertions(+), 23 deletions(-) diff --git a/scripts/config/vale/styles/config/vocabularies/words/accept.txt b/scripts/config/vale/styles/config/vocabularies/words/accept.txt index df23489fc..cf5b436d2 100644 --- a/scripts/config/vale/styles/config/vocabularies/words/accept.txt +++ b/scripts/config/vale/styles/config/vocabularies/words/accept.txt @@ -20,7 +20,7 @@ Jira Makefile OAuth Octokit -onboarding +[Oo]nboarding Podman pre Python diff --git a/specification/api/components/documentation/APIDescription.md b/specification/api/components/documentation/APIDescription.md index 4727434bb..9a2db4488 100644 --- a/specification/api/components/documentation/APIDescription.md +++ b/specification/api/components/documentation/APIDescription.md @@ -1,6 +1,13 @@ ## Overview -API for communication suppliers to integrate with NHS Notify. +API for letter suppliers to integrate with NHS Notify. + +This API lets you: + +* Get lists of letters allocated to you +* Download letter PDFs and metadata +* Update and manage letter statuses +* Submit and retrieve management information (MI) This specification represents the in-development 'next' version of the API schema and should be treated as unstable @@ -9,7 +16,7 @@ Use this API to retrieve letters to be printed ## Who can use this API -The NHS Notify Supplier service is intended for suppliers of print services to the [NHS Notify](https://digital.nhs.uk/services/nhs-notify) service + The NHS Notify Supplier API is designed for approved print service suppliers who support the delivery of physical letters through the [NHS Notify](https://digital.nhs.uk/services/nhs-notify) platform. ## Related APIs @@ -17,15 +24,13 @@ The [NHS Notify API](https://digital.nhs.uk/developer/api-catalogue/nhs-notify) ## API status and roadmap -This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses) meaning: +This API is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). We are onboarding partners to use it. -* it is available for testing in the integration environment -* we expect to make breaking changes based on developer feedback +We may make additive non-breaking changes to the API without notice, for example the addition of fields to a response or callback, or new optional fields to a request. ## Service Level -TBD - +This service is a [silver](https://digital.nhs.uk/services/reference-guide#service-levels) service, meaning it is available 24 hours a day, 365 days a year and supported from 8am to 6pm, Monday to Friday excluding bank holidays. For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels). ## Technology @@ -36,9 +41,20 @@ We follow the [JSON:API](https://jsonapi.org/) standard for our request and resp ### Response content types -This API can generate responses in the following formats: +This API can generate responses in the following format: + +* `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction) + +### Request content types + +This API will accept request payloads of the following types: * `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction) +* `application/json` + +The `Content-Type` header may optionally include a `charset` attribute. If included, it **must** be set to `charset=utf-8` Any other `charset` value will result in a `406` error response. If omitted then `utf-8` is assumed. + +If you attempt to send a payload without the `Content-Type` header set to either of these values then the API will respond with a `415 Unsupported Media Type` response. ## Network access @@ -60,9 +76,9 @@ To access this API, use the following security pattern: | Environment | Base URL | |------------ | -------- | -| Sandbox | `https://sandbox.api.service.nhs.uk/comms` | -| Integration test | `https://int.api.service.nhs.uk/comms` | -| Production | `https://api.service.nhs.uk/comms` | +| Sandbox | `https://sandbox.api.service.nhs.uk/nhs-notify-supplier` | +| Integration test | `https://int.api.service.nhs.uk/nhs-notify-supplier` | +| Production | `https://api.service.nhs.uk/nhs-notify-supplier` | ### Sandbox testing @@ -75,6 +91,10 @@ Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentat For details of sandbox test scenarios, or to try out sandbox using our 'Try this API' feature, see the documentation for each endpoint. +Alternatively, you can try out the sandbox using our Postman collection + +You can find our postman collection source in our [public repository on github](https://github.com/NHSDigital/nhs-notify-supplier-api/tree/main/postman). + ### Integration testing Our integration test environment: @@ -86,3 +106,15 @@ Our integration test environment: You need to get your software approved by us before it can go live with this API. You will also need to follow our steps to - TBD + +### Production smoke testing + +Before go-live, you must complete a smoke test in the NHS Notify production environment. +The smoke test confirms that your live credentials, connectivity, and print workflow operate correctly end-to-end. It will be carried out in coordination with the NHS Notify Supplier API team. +You will retrieve and print one or more live test letters through the production API, send the printed output to the address provided, and submit a Management Information (MI) update for verification. +The NHS Notify team will configure your production access, review your results, and confirm that your output meets NHS Notify print specifications. + +### Onboarding + +You need to get your software approved by us before it can go live with this API. +You will also need to be an approved NHS letter supplier under the framework agreement (ADD link) and nominate your technical and operational contacts diff --git a/specification/api/components/documentation/createMI.md b/specification/api/components/documentation/createMI.md index 3b5777445..17aff50ee 100644 --- a/specification/api/components/documentation/createMI.md +++ b/specification/api/components/documentation/createMI.md @@ -1,8 +1,8 @@ ## Overview -Submit a Management Information (MI) record for your activity (counts and costs for letters). +Use this endpoint to send management or operational metrics relating to letter processing and print fulfilment -When you submit a create management information request, the endpoint will respond with a created(201) response code along with the created data including a unique id for the record or an unsuccessful (4xx/%xx) response +When you submit a create management information request, the endpoint will respond with a c201 (Created) response code along with the created data including a unique id for the record or an unsuccessful (4xx/5xx) response Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later diff --git a/specification/api/components/documentation/getDataId.md b/specification/api/components/documentation/getDataId.md index a2506f80c..81e742e15 100644 --- a/specification/api/components/documentation/getDataId.md +++ b/specification/api/components/documentation/getDataId.md @@ -1,6 +1,6 @@ ## Overview -Download the data file for a letter via a redirect to a signed URL. +Use this endpoint to get letter data, including downloading the letter's print-ready PDF file. Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later diff --git a/specification/api/components/documentation/getLetterStatus.md b/specification/api/components/documentation/getLetterStatus.md index b8542d780..257d4d7d2 100644 --- a/specification/api/components/documentation/getLetterStatus.md +++ b/specification/api/components/documentation/getLetterStatus.md @@ -1,6 +1,6 @@ ## Overview -Get the current status of a single letter by its ID. +Use this endpoint to get the current status of a single letter by its ID. Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later diff --git a/specification/api/components/documentation/headDataId.md b/specification/api/components/documentation/headDataId.md index c3755877c..66e98407f 100644 --- a/specification/api/components/documentation/headDataId.md +++ b/specification/api/components/documentation/headDataId.md @@ -1,6 +1,6 @@ ## Overview -Check whether a data file exists for a letter without downloading it. +Use this endpoint to check for the existence of letter data. This is useful for verifying readiness before performing retrieval or print operations. ## Sandbox test scenarios diff --git a/specification/api/components/documentation/listLetters.md b/specification/api/components/documentation/listLetters.md index 5d148c1cd..337033c73 100644 --- a/specification/api/components/documentation/listLetters.md +++ b/specification/api/components/documentation/listLetters.md @@ -1,6 +1,6 @@ ## Overview -Get a LIST of **PENDING** letters that are ready to print . +Use this endpoint to poll letters which are ready to be printed. Returns letters whose `status` is **PENDING**. Use `limit` to control list size (max 2500). diff --git a/specification/api/components/documentation/patchLetter.md b/specification/api/components/documentation/patchLetter.md index ecc598a6c..f577051e2 100644 --- a/specification/api/components/documentation/patchLetter.md +++ b/specification/api/components/documentation/patchLetter.md @@ -1,6 +1,6 @@ ## Overview -Update the status of a single letter by its ID, optionally providing a reason code and text. +Use this endpoint to update the status of a letter by submitting the new status in the request body, optionally providing a reason code and text. When you make a PATCH request with your application, the endpoint will respond with a successful (200) response code, along with the updated patient resource or an unsuccessful (4xx/5xx) response. diff --git a/specification/api/components/documentation/postLetters.md b/specification/api/components/documentation/postLetters.md index 6c6f3492d..b2ebee69d 100644 --- a/specification/api/components/documentation/postLetters.md +++ b/specification/api/components/documentation/postLetters.md @@ -1,6 +1,8 @@ ## Overview -Update the status for (example, PRINTED, DISPATCHED, DELIVERED) of multiple letters by providing the new statuses in the request body, optionally including reason codes and text. +Use this endpoint to update the status for (example, PRINTED, DISPATCHED, DELIVERED) of multiple letters by providing the new statuses in the request body, optionally including reason codes and text. + +Use this endpoint when you need to report status changes for several letters at once. When you make a POST update request with, the endpoint will respond with a successful (202) response code or an unsuccessful (4xx/5xx) response. diff --git a/specification/api/notify-supplier-phase1.yml b/specification/api/notify-supplier-phase1.yml index 9b7672ada..bccf356ef 100644 --- a/specification/api/notify-supplier-phase1.yml +++ b/specification/api/notify-supplier-phase1.yml @@ -62,12 +62,12 @@ tags: - name: data description: '' servers: + - url: 'https://internal-dev-sandbox.api.service.nhs.uk/nhs-notify-supplier' + description: Public sandbox - url: 'http://127.0.0.1:9000' description: Local development server - - url: 'https://sandbox-server.nhs.uk/nhs-notify-supplier-api' - description: Public sandbox x-nhsd-apim: - temporary: true + temporary: false monitoring: false access: $ref: ./components/x-nhsd-apim/access.yml