dcb_transaction.yaml

openapi: 3.0.3
info:
  title: mod DCB FOLIO API
  description: mod DCB FOLIO API
  version: 1.0.0
paths:
  /transactions/{dcbTransactionId}:
    description: DCB Circulation Transaction endpoint
    post:
      description: Create circulation request
      operationId: createCirculationRequest
      tags:
        - transactions
      parameters:
        - $ref: '#/components/parameters/dcbTransactionId'
      requestBody:
        $ref: "#/components/requestBodies/DCBTransaction"
      responses:
        '201':
          $ref: '#/components/responses/TransactionStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      description: Update the details of a transaction
      operationId: updateTransactionDetails
      tags:
        - transactions
      parameters:
        - $ref: '#/components/parameters/dcbTransactionId'
      requestBody:
        $ref: "#/components/requestBodies/DcbUpdateTransaction"
      responses:
        '204':
          description: 'Transaction updated successfully'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /transactions/{dcbTransactionId}/status:
    parameters:
      - $ref: '#/components/parameters/dcbTransactionId'
    get:
      description: Get transaction status across circulation institutions
      operationId: getTransactionStatusById
      tags:
        - transactions
      responses:
        '200':
          $ref: '#/components/responses/TransactionStatusResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      description: Update transaction status across circulation institutions
      operationId: updateTransactionStatus
      tags:
        - transactions
      requestBody:
        $ref: '#/components/requestBodies/TransactionStatusBody'
      responses:
        '200':
          $ref: '#/components/responses/TransactionStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /transactions/status:
    parameters:
      - $ref: '#/components/parameters/fromDate'
      - $ref: '#/components/parameters/toDate'
      - $ref: '#/components/parameters/pageNumber'
      - $ref: '#/components/parameters/pageSize'
    get:
      description: Get a list of updated transactions between from date and to date with optional filtering and pagination
      operationId: getTransactionStatusList
      tags:
        - transactions
      responses:
        '200':
          $ref: '#/components/responses/TransactionStatusResponseCollection'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /ecs-request-transactions/{ecsRequestTransactionId}:
    description: ECS TLR Transaction endpoint
    post:
      description: Create transaction for existing circulation TLR
      operationId: createEcsRequestTransactions
      tags:
        - ecs-request-transactions
      parameters:
        - $ref: '#/components/parameters/ecsRequestTransactionId'
      requestBody:
        $ref: "#/components/requestBodies/DCBTransaction"
      responses:
        '201':
          $ref: '#/components/responses/TransactionStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      description: Update ECS request transaction
      operationId: updateEcsRequestTransaction
      tags:
        - ecs-request-transactions
      parameters:
        - $ref: '#/components/parameters/ecsRequestTransactionId'
      requestBody:
        $ref: "#/components/requestBodies/DCBTransaction"
      responses:
        '200':
          $ref: '#/components/responses/TransactionStatusResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /transactions/{dcbTransactionId}/renew:
    parameters:
      - $ref: '#/components/parameters/dcbTransactionId'
    put:
      description: Increment the renew loan count and returned transaction status with renewal details
      operationId: renewItemLoanByTransactionId
      tags:
        - transactions
      responses:
        '200':
          $ref: '#/components/responses/TransactionStatusResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /transactions/{dcbTransactionId}/block-renewal:
    parameters:
      - $ref: '#/components/parameters/dcbTransactionId'
    put:
      description: Set the renewal count for the item in DCB transaction to maximum allowed renewals
      operationId: blockItemRenewalByTransactionId
      tags:
        - transactions
      responses:
        '204':
          description: Block renewal for the item in dcb transaction
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /transactions/{dcbTransactionId}/unblock-renewal:
    parameters:
      - $ref: '#/components/parameters/dcbTransactionId'
    put:
      description: Set the renewal count for the item in DCB transaction to zero
      operationId: unblockItemRenewalByTransactionId
      tags:
        - transactions
      responses:
        '204':
          description: Unblock renewal for the item in DCB transaction
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /dcb/shadow-locations/refresh:
    description: dcb hub shadow location refresh endpoint
    post:
      requestBody:
        $ref: "#/components/requestBodies/ShadowLocationRefreshBody"
      tags:
        - RefreshShadowLocations
      description: Refresh shadow location
      operationId: refreshShadowLocation
      responses:
        '201':
          $ref: '#/components/responses/RefreshShadowLocationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /dcb/settings:
    description: DCB settings endpoint
    get:
      description: Search DCB settings by CQL query with pagination
      operationId: findDcbSettings
      tags:
        - setting
      parameters:
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: List of DCB settings matching the query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsCollection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      description: Create DCB setting
      operationId: createDcbSetting
      tags:
        - setting
      requestBody:
        description: DCB setting to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Setting'
      responses:
        '201':
          description: created DCB setting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Setting'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /dcb/settings/{id}:
    get:
      description: Get DCB setting by id
      operationId: getDcbSettingById
      tags:
        - setting
      parameters:
        - $ref: '#/components/parameters/pathId'
      responses:
        '200':
          description: DCB setting with the given id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Setting'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      description: Update DCB setting by id
      operationId: updateDcbSettingById
      tags:
        - setting
      requestBody:
        description: DCB setting to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Setting'
      parameters:
        - $ref: '#/components/parameters/pathId'
      responses:
        '204':
            description: DCB setting updated successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      description: Delete DCB setting by id
      operationId: deleteDcbSettingById
      tags:
        - setting
      parameters:
        - $ref: '#/components/parameters/pathId'
      responses:
        '204':
          description: DCB setting deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  requestBodies:
    TransactionStatusBody:
      description: TransactionStatus object
      content:
        application/json:
          schema:
            $ref: "schemas/transactionStatus.yaml#/TransactionStatus"
    DCBTransaction:
      description: DCB transaction object
      required: true
      content:
        application/json:
          schema:
            $ref: "schemas/dcbTransaction.yaml#/DcbTransaction"
    DcbUpdateTransaction:
      description: DCB transaction update object
      required: true
      content:
        application/json:
          schema:
            $ref: "schemas/dcbUpdateTransaction.yaml#/DcbUpdateTransaction"
    ShadowLocationRefreshBody:
      description: DCB hub shadow location refresh request body
      required: true
      content:
        application/json:
          schema:
            $ref: 'schemas/ShadowLocationRefreshBody.yaml#/ShadowLocationRefreshBody'
  responses:
    TransactionStatus:
      description: Transaction Status object
      content:
        application/json:
          schema:
            $ref: "schemas/transactionStatus.yaml#/TransactionStatus"
    TransactionStatusResponse:
      description: TransactionStatusResponse object
      content:
        application/json:
          schema:
            $ref: "schemas/transactionStatusResponse.yaml#/TransactionStatusResponse"
    TransactionStatusResponseCollection:
      description: List of TransactionResponse object
      content:
        application/json:
          schema:
            $ref: "schemas/transactionStatusResponse.yaml#/TransactionStatusResponseCollection"
    RefreshShadowLocationResponse:
      description: DCB hub shadow location refresh response
      content:
        application/json:
          schema:
            $ref: "schemas/refreshShadowLocationResponse.yaml#/RefreshShadowLocationResponse"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "schemas/common.yaml#/Error"
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: "schemas/common.yaml#/Error"
    Conflict:
      description: Validation errors
      content:
        application/json:
          schema:
            $ref: "schemas/common.yaml#/Errors"
    Unauthorized:
      description: Not authorized to perform requested action
      content:
        text/plain:
          example: unable to perform action -- unauthorized
    UnprocessableEntity:
      description: Validation errors
      content:
        application/json:
          schema:
            $ref: 'schemas/common.yaml#/Errors'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "schemas/common.yaml#/Error"
  parameters:
    dcbTransactionId:
      in: path
      name: dcbTransactionId
      schema:
        type: string
      required: true
    ecsRequestTransactionId:
      in: path
      name: ecsRequestTransactionId
      schema:
        type: string
      required: true
    fromDate:
      in: query
      name: fromDate
      description: Start date for filtering transactions
      schema:
        type: string
        format: date-time
      required: true
    toDate:
      in: query
      name: toDate
      description: End date for filtering transactions
      schema:
        type: string
        format: date-time
      required: true
    pageNumber:
      in: query
      name: pageNumber
      description: Page number for pagination (optional)
      schema:
        type: integer
        default: 0
        minimum: 0
        maximum: 2147483647
      required: false
    pageSize:
      in: query
      name: pageSize
      description: Number of items per page (optional)
      schema:
        type: integer
        default: 1000
        minimum: 1
        maximum: 2147483647
      required: false
    query:
      in: query
      name: query
      description: A query string to filter records based on matching criteria in fields.
      required: false
      schema:
        type: string
        default: cql.allRecords=1
      example: role
    limit:
      in: query
      name: limit
      description: Limit the number of elements returned in the response.
      required: false
      schema:
        type: integer
        default: 50
        minimum: 0
      example: 100
    offset:
      in: query
      name: offset
      description: Skip over a number of elements by specifying an offset value for the query.
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
      example: 0
    pathId:
      in: path
      required: true
      name: id
      description: Record identifier
      schema:
        type: string
        format: uuid
      example: 1e111e76-1111-401c-ad8e-0d121a11111e
  schemas:
    RenewByIdRequest:
      $ref: 'schemas/RenewByIdRequest.yaml#/RenewByIdRequest'
    RenewByIdResponse:
      $ref: 'schemas/RenewByIdResponse.yaml#/RenewByIdResponse'
    InventoryItem:
      $ref: 'schemas/InventoryItem.yaml#/InventoryItem'
    InventoryHolding:
      $ref: 'schemas/InventoryHolding.yaml#/InventoryHolding'
    UserGroupCollection:
      $ref: 'schemas/UserGroup.yaml#/UserGroupCollection'
    UserCollection:
      $ref: 'schemas/User.yaml#/UserCollection'
    LoanCollection:
      $ref: 'schemas/Loan.yaml#/LoanCollection'
    LoanPolicyCollection:
      $ref: 'schemas/LoanPolicy.yaml#/LoanPolicyCollection'
    CirculationRequest:
      $ref: 'schemas/CirculationRequest.yaml#/CirculationRequest'
    CheckInRequest:
      $ref: 'schemas/CheckInRequest.yaml#/CheckInRequest'
    ClaimedReturnedResolution:
      $ref: 'schemas/claimedReturnedResolution.yaml#/ClaimedReturnedResolution'
    CheckOutRequest:
      $ref: 'schemas/checkOutRequest.yaml#/CheckOutRequest'
    ServicePointRequest:
      $ref: 'schemas/ServicePointRequest.yaml#/ServicePointRequest'
    CirculationItemCollection:
      $ref: 'schemas/CirculationItem.yaml#/CirculationItemCollection'
    MaterialTypeCollection:
      $ref: 'schemas/MaterialType.yaml#/MaterialTypeCollection'
    CalendarCollection:
      $ref: 'schemas/Calendar.yaml#/CalendarCollection'
    Setting:
      $ref: 'schemas/setting.yaml#/Setting'
    SettingsCollection:
      $ref: 'schemas/setting.yaml#/SettingsCollection'