From 937962401bd6aa287d38168872e35b28c487027a Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Mon, 12 May 2025 12:19:22 +0200 Subject: [PATCH] OVPAY-1438 - Added cardreader YAML. --- .../nfc_reader/servicedeskcardreader-api.yaml | 206 ++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 src/openapi/nfc_reader/servicedeskcardreader-api.yaml diff --git a/src/openapi/nfc_reader/servicedeskcardreader-api.yaml b/src/openapi/nfc_reader/servicedeskcardreader-api.yaml new file mode 100644 index 0000000..722bde1 --- /dev/null +++ b/src/openapi/nfc_reader/servicedeskcardreader-api.yaml @@ -0,0 +1,206 @@ +openapi: 3.0.3 +info: + title: Service Desk Card Reader API + version: 0.9.0 + description: |- + This API enables that external systems (such as SOS) can operate on information from service desk card readers. + + ### 0.9.0 + - First draft version +servers: + - url: /v1 +paths: + /card-reader/token: + post: + tags: + - CardReader + summary: Register a token from the card + operationId: registerToken + description: | + Register a token from the card to the external system. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/TokenRegisterRequest" + responses: + "202": + description: Accepted + "400": + description: |- + Bad Request. Occurs when the readerId is unknown to the external system. A call to `/card-reader/registrations`, + followed by a `/card-reader/register` is needed in order to restore reader registrations. + /card-reader/register: + post: + tags: + - CardReader + summary: Register a reader that is connected to the Card Reader Interface + operationId: registerReader + description: | + Register a reader to the external system to receive a newly generated readerID. + + **N.B.**: After the last reader has been registered, an initial `/card-reader/registrations` call must be sent. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ReaderRegisterRequest" + responses: + "200": + description: Registration was successful + content: + application/json: + schema: + $ref: "#/components/schemas/ReaderRegisterResponse" + "400": + description: Bad Request + + /card-reader/unregister: + post: + tags: + - CardReader + summary: Unregister a reader from the external system + operationId: unregisterReader + description: | + Unregister a reader from the external system. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ReaderUnregisterRequest" + responses: + "204": + description: Unregistration was successful + "400": + description: Bad Request + /card-reader/registrations: + post: + tags: + - CardReader + summary: Send a list of readers that should currently be registered + operationId: sendReaderRegistrations + description: | + Send a list of readers of which the Card Reader Interface believes are registered. This must be done periodically. + The period is determined by the timeout duration in the response. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/RegistrationsRequest" + responses: + "200": + description: Reader registrations successfully received + content: + application/json: + schema: + $ref: "#/components/schemas/RegistrationsResponse" + +components: + schemas: + TokenRegisterRequest: + description: Request containing token information read using the card reader + type: object + properties: + readerId: + $ref: "#/components/schemas/ReaderId" + xBot: + type: string + format: uuid + description: The unique identifier of the token. + required: + - readerId + - xBot + + ReaderRegisterRequest: + description: Request containing card reader information for one or more readers to be be registered + type: object + properties: + readerIdQuantity: + type: integer + default: 1 + minimum: 1 + cardReaderInterfaceId: + $ref: "#/components/schemas/cardReaderInterfaceId" + locationName: + $ref: "#/components/schemas/LocationName" + required: + - cardReaderInterfaceId + - locationName + - readerIdQuantity + ReaderRegisterResponse: + description: Response containing one or more readerIds for the registered reader(s) + type: object + properties: + readerIds: + type: array + items: + $ref: "#/components/schemas/ReaderId" + required: + - readerIds + + ReaderUnregisterRequest: + description: Request containing the readerId to unregister + type: object + properties: + cardReaderInterfaceId: + $ref: "#/components/schemas/cardReaderInterfaceId" + locationName: + $ref: "#/components/schemas/LocationName" + readerId: + $ref: "#/components/schemas/ReaderId" + required: + - readerId + + RegistrationsRequest: + description: Request containing a list of readerId of which the Card Reader Interface believes are registered. + type: object + properties: + cardReaderInterfaceId: + $ref: "#/components/schemas/cardReaderInterfaceId" + locationName: + $ref: "#/components/schemas/LocationName" + readerIds: + type: array + items: + $ref: "#/components/schemas/ReaderId" + required: + - cardReaderInterfaceId + - locationName + - readerIds + RegistrationsResponse: + description: Response with actionable information for the Card Reader Interface. + type: object + properties: + nextCallTimeout: + + type: integer + description: | + Timeout duration in seconds BEFORE which the next `/card-reader/registrations` call should happen. + Failure to send a call before this timeout will result in automatic unregistration of all readers associated to this Card Read Interface. + + The external systems must maintain a grace period on reception of the next call. + The Card Read Interface must start sending the next call on or before the timeout (grace period not needed). + readerIds: + type: array + items: + $ref: "#/components/schemas/ReaderId" + description: | + A list of readerIds that are registered to the external system. This mean all readerIds that readers with + readerIds missing from this list must be reregistered using `/card-reader/register`. + required: + - nextCallTimeout + - readerIds + + cardReaderInterfaceId: + type: string + description: Each Card Reader Interface has a unique cardReaderInterfaceId. Identifier for the Card Reader Interface to which one or more readers are connected. + LocationName: + type: string + description: Name of the location of the reader. A location can have one ore more Card Reader Interfaces (cardReaderInterfaceIds) + ReaderId: + type: string + description: Unique identifier generated by the external system. Should be displayed on the screen of the reader.