OVPAY-1438 - Added cardreader YAML.
This commit is contained in:
parent
7c76658884
commit
937962401b
206
src/openapi/nfc_reader/servicedeskcardreader-api.yaml
Normal file
206
src/openapi/nfc_reader/servicedeskcardreader-api.yaml
Normal file
@ -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.
|
||||||
Loading…
Reference in New Issue
Block a user