openapi: 3.0.1 info: title: UKHO Shop Facade Service APIs description: | The UKHO Shop Facade Service APIs. contact: name: UKHO email: abzudeliveryteam@ukho.gov.uk version: 0.0.1 servers: - url: https://shop-facade-service-url description: TBC security: - jwtBearerAuth: [] paths: /v1/licences/{licenceId}/s100/permits: get: description: Returns a zip file containing all the S-100 permit file(s) of the requested licence. tags: - Licensing operationId: getS100Permits parameters: - $ref: "#/components/parameters/licenceId" responses: "200": description: OK - Returns a zip containing permit files. headers: X-Correlation-ID: $ref: '#/components/headers/correlationId' Content-Disposition: schema: type: string format: filename=permits.zip; filename*=UTF-8''Permits.zip content: application/zip: schema: title: Zip containing S-100 permit files. type: string format: binary "204": description: No Content - There are no S-100 permits for the requested licence. headers: X-Correlation-ID: $ref: '#/components/headers/correlationId' "400": description: Bad request - could be missing or invalid licenceId, it must be an integer and greater than zero. headers: X-Correlation-ID: $ref: '#/components/headers/correlationId' content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: licenceId description: Invalid licenceId "401": $ref: '#/components/responses/unauthorisedResponse' "403": $ref: '#/components/responses/forbiddenResponse' "404": description: Licence not found headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: licenceId description: Licence not found application/zip: schema: $ref: '#/components/schemas/errorDescription' "500": $ref: '#/components/responses/internalServerErrorResponse' /v1/licences/{licenceId}/s100/userPermits: get: description: Returns all S-100 User Permit Numbers (UPNs) associated with the requested licence. There can be one or more S-100 UPNs for a licence. tags: - Licensing operationId: getUserPermits parameters: - $ref: "#/components/parameters/licenceId" responses: "200": description: OK - Returns UPNs for the licence headers: X-Correlation-ID: $ref: '#/components/headers/correlationId' content: application/json: schema: type: array items: $ref: '#/components/schemas/userPermit' example: - title: "Port Radar" upn: "C23DAD797C966EC9F6A55B66ED98281599B3A231859868" - title: "Back up" upn: "AD1DAD797C966EC9F6A55B66ED98281599BA9B23859868" "204": description: No Content - There are no UPNs for the licence. headers: X-Correlation-ID: $ref: '#/components/headers/correlationId' "400": description: Bad request - could be missing or invalid licenceId, it must be an integer and greater than zero. headers: X-Correlation-ID: $ref: '#/components/headers/correlationId' content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: licenceId description: Invalid licenceId "401": $ref: '#/components/responses/unauthorisedResponse' "403": $ref: '#/components/responses/forbiddenResponse' "404": description: Licence not found. headers: X-Correlation-ID: $ref: '#/components/headers/correlationId' content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: licenceId description: Licence not found "500": $ref: '#/components/responses/internalServerErrorResponse' /v1/licences/{licenceId}/s100/holdings: get: description: Get holdings for the requested licence. operationId: getHoldings tags: - DRAFT parameters: - $ref: "#/components/parameters/licenceId" responses: "200": description: OK - Returns holdings available for the licence. content: application/json: schema: type: object properties: unitName: type: string description: unitName define the type of unit. example: "P1231" unitTitle: type: string description: unitTitle define the title of unit. example: "P1231" expiryDate: type: string description: expiryDate of the unit. example: "2026-01-31T23:59:00Z" datasets: type: array items: description: Object representing the details of cell. type: object properties: datasetName: type: string example: "101GB40079ABCDEFG.000" datasetTitle: type: string example: "101GB40079ABCDEFG" latestEditionNumber: type: integer example: 1 latestUpdateNumber: type: integer example: 11 headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string "204": description: No Content - There are no holdings for the given licenceId. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string "400": description: Bad request - could be missing or invalid licenceId, it must be an integer and greater than zero. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: licenceId description: Invalid licenceId application/zip: schema: $ref: '#/components/schemas/errorDescription' "401": description: Unauthorised - either you have not provided valid token, or your token is not recognised. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string "403": description: Forbidden - you have no permission to use this API. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string "404": description: Licence not found. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: licenceId description: Licence not found application/zip: schema: $ref: '#/components/schemas/errorDescription' "500": description: Internal Server Error. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/exceptionDescription' /v1/holdings/{licenceId}/{serviceType}: get: description: Gets the current holdings for a given product per supplied licence. operationId: getHolding tags: - DRAFT parameters: - $ref: "#/components/parameters/licenceId" - name: serviceType in: path description: The Service Type from the list of available service types. Can be name or number. required: true schema: type: string enum: - S100 - "100" responses: "200": description: OK - Holdings returned headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/getHoldingsResponse' "400": description: Product Type not recognised or does not exist for this licence. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: productType description: Product Type not recognised "401": description: Token Authentication Failed headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string "403": description: "Forbidden or Quota Exceeded.
This will either be because:\ \
- you have no permission to use this API (in which case the body\ \ will be empty)
- the quota has been exceeded" headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' "404": description: Licence ID not found headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: licenceId description: Licence not found "500": description: Internal Server Error. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/exceptionDescription' /v1/orders: post: description: Submit a new S100 product order for a specified licence. operationId: submitOrder tags: - DRAFT requestBody: description: An order represented as JSON. Please see schema for more information. content: application/json: schema: $ref: '#/components/schemas/orderRequest' required: true responses: "202": description: Accepted - Indicates that the S100 Order has been accepted and sent for processing. Please see response for the status of each ordered product. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/submitOrderResponse' example: orderStatus: - product: S101 status: Complete - product: S102 status: Pending accountId: 369 orderId: 123456 messages: - messageText: Duplicates of S104 - GB123 have been found in the order and will be removed "400": description: "Bad Request - The request is incomplete or fails validation: - Missing the JWT
- Incorrect or missing data, please see response\ \ message for more details
- Invalid Purchase Order Number (must\ \ be A-Z, a-z, 0-9 or _, and no more than 20 characters)" headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: token description: Missing JWT - source: LicenceType description: Licence not of type 'full' for ARCS. "401": description: Token Authentication Failed headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: {} "403": description: "Forbidden or Quota Exceeded.
This will either be because:\ \
- you have no permission to use this API (in which case the body\ \ will be empty)
- another distributor is responsible for a product\ \ you're trying to order on this licence
- the quota has been exceeded" headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: statusCode: 403 message: Out of call volume quota. Quota will be replenished in 00:00:40. "404": description: Licence not found or Licence ID not provided. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: licenceId description: Licence not found "409": description: Conflict. Your order reference conflicts with a previous order reference. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: {} "500": description: Internal Server Error. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/exceptionDescription' x-codegen-request-body-name: orderRequest /v1/orders/{orderId}/{publicationType}: get: description: "Get the current status of a publication type in an order, using\ \ the Order ID" operationId: getOrder tags: - DRAFT parameters: - name: orderId in: path description: The Order ID of the Order. required: true schema: type: integer - name: publicationType in: path description: The Publication Type from the list of available publication types. Can be name or number. required: true schema: type: string enum: - S100 - "100" responses: "200": description: OK - Order returned headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/getOrderResponse' "400": description: Publication Type invalid. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: publicationType description: Publication Type not recognised "401": description: Token Authentication Failed headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: {} "403": description: "Forbidden or Quota Exceeded.
This will either be because:\ \
- you have no permission to use this API (in which case the body\ \ will be empty)
- the quota has been exceeded" headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' "404": description: "Order ID not found. This will either be because:
- The\ \ order does not exist
- The selected product type is not present\ \ in the order
- You do not have permission to view the order" headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: OrderId description: Order ID 948213 not found or you do not have permissions to access this order. "500": description: Internal Server Error. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/exceptionDescription' /v1/catalogues/{catalogueId}: get: description: Gets the catalogue for the specified product for the current week operationId: getCatalogue tags: - DRAFT parameters: - name: If-Modified-Since in: header description: Allows a 304 Not Modified to be returned if content is unchanged. schema: type: string format: RCF1123 - name: catalogueId in: path description: |- This can either be an INT32 or the catalogue name as specified in the table below. Strings are case insensitive but need to be fully URL encoded. Int ID - String ID 100 - S100 required: true schema: type: string responses: "200": description: OK - Catalogue returned headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string Last-Modified: description: The last modified date for the requested catalogue schema: type: string format: RFC1123 content: {} "304": description: Not modified - Catalogue hasn't changed since the If-Modified-Since date headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: {} "401": description: Token Authentication Failed headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: {} "403": description: "Forbidden or Quota Exceeded.
This will either be because:\ \
- you have no permission to use this API (in which case the body\ \ will be empty)
- the quota has been exceeded" headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' "404": description: Catalogue ID not found headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/errorDescription' example: correlationId: 6c254109-8a0f-4446-8649-721775ba9de2 errors: - source: catalogueId description: Catalogue ID not found "500": description: Internal Server Error. headers: X-Correlation-ID: description: GUID for the request for logging/tracing schema: type: string content: application/json: schema: $ref: '#/components/schemas/exceptionDescription' components: schemas: exceptionDescription: type: object properties: correlationId: type: string errorDescription: type: object properties: correlationId: type: string errors: type: array items: $ref: '#/components/schemas/fieldError' apiManagementError: type: object properties: statusCode: type: string message: type: string fieldError: type: object properties: source: type: string description: type: string userPermit: type: object properties: title: type: string upn: type: string orderRequest: required: - deliveryMethod - licenceId - orderItems type: object properties: purchaseOrderNumber: maxLength: 20 type: string description: Not Required. A reference given to an order by the Distributor. licenceId: type: integer description: Required. The unique Licence ID given to each Vessel by the UKHO. ARCSRenewType: type: string description: Required if the ARCS licence is within the last month before renewal. The type of order required if ordering ARCS products. enum: - New - Add - Renew ADPRenewType: type: string description: Required if the ADP licence is within the last month before renewal. The type of order required if ordering ADP products. "Renew" -- Add ADP products to current licence and renew licence. enum: - New - Add - Renew deliveryFromDate: type: string description: "Not required on \"digital\" only orders. Optional on orders\ \ including \"paper\" products. The required delivery from date (earliest\ \ delivery date), must be today's date or later. (Note: The time element\ \ is stored but not displayed in e-Navigator). Format: UTC YYYY-MM-DDThh:mm:ss\ \ E.g. 2012-1102T14:28:37.6613351+00:00 (Time and offset optional)." format: date-time deliveryToDate: type: string description: "Not required on \"digital\" only orders. Optional on orders\ \ including \"paper\" products. The required delivery to date (latest\ \ delivery date), must be today's date or later. (Note: The time element\ \ is stored but not displayed in e-Navigator). Format: UTC YYYY-MM-DDThh:mm:ss\ \ E.g. 2012-1102T14:28:37.6613351+00:00 (Time and offset optional)." format: date-time deliveryMethod: type: string description: "Required. Permits and/or activation keys are provided either\ \ as downloads through GetOrder service or by email. The possible values:\ \ Email, Download, or Both." enum: - Email - Download - Both deliveryAddress: maxLength: 255 type: string description: Not required on "digital" only orders. Optional on orders including "paper" products. A delivery address of an order. orderItems: type: array description: Required. The items in the order. items: $ref: '#/components/schemas/orderItems' orderItems: required: - productId - productType type: object properties: productType: type: string description: Required. The product type of the product to be ordered. enum: - S101 - S102 - S104 - S111 productId: type: string description: "Required. The product ID of the product to be ordered from\ \ the current S100 catalogue, of the relevant product type. NOTE:\ \ this is case sensitive." productPeriod: type: integer description: "Required for S100 Charts. The period the product is required\ \ for in months. Accepts only: 3, 6, 9, or 12." quantity: type: integer description: Required for "paper" products. Not required for other products. The quantity of product required. submitOrderResponse: type: object properties: orderId: type: integer accountId: type: integer messages: type: array items: $ref: '#/components/schemas/responseMessage' orderStatus: type: array items: $ref: '#/components/schemas/orderItemStatus' orderItemStatus: type: object properties: product: type: string status: type: string responseMessage: type: string getHoldingsResponse: type: array items: $ref: '#/components/schemas/holding' holding: type: object properties: productCode: type: string title: type: string productType: type: string enum: - S101 - S102 - S104 - S111 - S122 expiryDate: type: string format: date-time getOrderResponse: type: object properties: orderId: type: integer licenceId: type: integer orderStatus: type: string enum: - Error - Created - ExpectsShipCoApproval - ExpectsDistributorApproval - ExpectsUkhoApproval - ExternalProcessing - Completed - Rejected - FulfillmentInProgress parameters: licenceId: name: licenceId in: path description: Licence Id. It must be an integer value and greater than zero. required: true schema: type: integer example: 12345678 responses: unauthorisedResponse: description: Unauthorised - either you have not provided valid token, or your token is not recognised. headers: X-Correlation-ID: $ref: '#/components/headers/correlationId' forbiddenResponse: description: Forbidden - you have no permission to use this API. headers: X-Correlation-ID: $ref: '#/components/headers/correlationId' internalServerErrorResponse: description: Internal Server Error. headers: X-Correlation-ID: $ref: '#/components/headers/correlationId' content: application/json: schema: $ref: '#/components/schemas/exceptionDescription' headers: correlationId: description: GUID for the request for logging/tracing schema: type: string securitySchemes: jwtBearerAuth: # arbitrary name for the security scheme type: http scheme: bearer bearerFormat: JWT