openapi: 3.2.0
info:
  title: Folio Ecs Loans API
  version: v1
  description: 'Operations tagged ecsLoans across 2 of this provider''s published API definitions: folio-mod-tlr-ecs-loans-openapi.json, folio-mod-tlr-ecs-loans-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: ecsLoans
paths:
  /tlr/loans/check-out-by-barcode:
    post:
      operationId: checkOutByBarcode
      description: Checks item out by barcode
      tags:
      - ecsLoans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/check-out-request'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/checkOutResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '422':
          $ref: '#/components/responses/unprocessableEntityResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Check out by barcode
      x-summary-source: derived
  /tlr/loans/declare-item-lost:
    post:
      operationId: declareItemLost
      tags:
      - ecsLoans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/declare-item-lost-request'
        required: true
      responses:
        '204':
          description: Item successfully declared lost
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '422':
          $ref: '#/components/responses/unprocessableEntityResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Declare item lost
      x-summary-source: derived
  /tlr/loans/claim-item-returned:
    post:
      operationId: claimItemReturned
      tags:
      - ecsLoans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/claim-item-returned-request'
        required: true
      responses:
        '204':
          description: Item successfully claimed returned
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '422':
          $ref: '#/components/responses/unprocessableEntityResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Claim item returned
      x-summary-source: derived
  /tlr/loans/declare-claimed-returned-item-as-missing:
    post:
      operationId: declareClaimedReturnedItemAsMissing
      tags:
      - ecsLoans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/declare-claimed-returned-item-as-missing-request'
        required: true
      responses:
        '204':
          description: Item successfully claimed missing
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '422':
          $ref: '#/components/responses/unprocessableEntityResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Declare claimed returned item as missing
      x-summary-source: derived
components:
  schemas:
    parameter:
      description: List of key/value parameters of an error
      type: object
      properties:
        key:
          description: Parameter key
          type: string
        value:
          description: Parameter value
          type: string
      additionalProperties: false
      required:
      - key
    declare-claimed-returned-item-as-missing-request:
      allOf:
      - $ref: '#/components/schemas/circulation-declare-claimed-returned-item-as-missing-request'
      - type: object
        properties:
          loanId:
            description: ID of the loan created for the missing item
            type: string
            format: uuid
          itemId:
            description: ID of the missing item
            type: string
            format: uuid
          userId:
            description: ID of the user who claimed the item missing
            type: string
            format: uuid
    circulation-declare-claimed-returned-item-as-missing-request:
      type: object
      description: Request body schema for for resolving claim as missing API
      properties:
        comment:
          description: Comment explaining why the item is claimed missing
          type: string
      additionalProperties: false
      required:
      - comment
    circulation-claim-item-returned-request:
      type: object
      description: Request body schema for claim item returned API
      properties:
        itemClaimedReturnedDateTime:
          description: The date and time when the item is to be claimed returned
          type: string
          format: date-time
        comment:
          description: Comment explaining why the item has been claimed returned
          type: string
      additionalProperties: false
      required:
      - itemClaimedReturnedDateTime
    check-out-response:
      type: object
      description: Check-out response
      properties:
        id:
          description: Unique ID (generated UUID) of the loan
          type: string
        userId:
          description: ID of the patron the item was lent to. Required for open loans, not required for closed loans (for anonymization).
          type: string
        borrower:
          description: Additional information about the borrower of the item, taken from the user referred to by the userId
          type: object
          properties:
            firstName:
              description: First name of the borrower (read-only, defined by the server)
              type: string
            lastName:
              description: Last name of the borrower (read-only, defined by the server)
              type: string
            middleName:
              description: Middle name of the borrower (read-only, defined by the server)
              type: string
            barcode:
              description: Barcode used to identify the borrower (read-only, defined by the server)
              type: string
            preferredFirstName:
              description: Preferred first name of the borrower (read-only, defined by the server)
              type: string
            patronGroup:
              description: Current patron group of the borrower (read-only, defined by the server)
              type: string
          additionalProperties: true
        proxyUserId:
          description: ID of the user representing a proxy for the patron
          type: string
        itemId:
          description: ID of the item lent to the patron
          type: string
        loanPolicyId:
          description: ID of last policy used in relation to this loan
          type: string
        loanPolicy:
          description: Additional information about the loan policy of the item, taken from the loanPolicyId
          type: object
          properties:
            name:
              description: Name of last policy used in relation to this loan (read-only, defined by the server)
              type: string
          additionalProperties: true
        overdueFinePolicyId:
          description: ID of last overdue fine policy used in relation to this loan
          type: string
        overdueFinePolicy:
          description: Additional information about the overdue fine policy of the item
          type: object
          properties:
            name:
              description: Name of last overdue fine policy used (read-only, defined by the server)
              type: string
          additionalProperties: true
        lostItemPolicyId:
          description: ID of last lost item policy used in relation to this loan
          type: string
        lostItemPolicy:
          description: Additional information about the lost item policy
          type: object
          properties:
            name:
              description: Name of last lost item policy used (read-only, defined by the server)
              type: string
          additionalProperties: true
        item:
          description: Additional information about the item
          type: object
          properties:
            id:
              description: ID of the item
              type: string
            title:
              description: The title of the item lent to the patron
              type: string
            barcode:
              description: The barcode of the item
              type: string
            status:
              description: Overall status of the item
              type: object
              properties:
                name:
                  description: Name of the item status
                  type: string
                date:
                  description: Date time when status was last changed
                  type: string
                  format: date-time
              additionalProperties: true
          additionalProperties: true
        loanDate:
          description: Date and time when the loan began
          type: string
          format: date-time
        dueDate:
          description: Date and time when the item is due to be returned
          type: string
          format: date-time
        returnDate:
          description: Date and time when the item was returned
          type: string
          format: date-time
        action:
          description: Last action performed on a loan (e.g., checkedout, checkedin)
          type: string
        renewalCount:
          description: Count of how many times a loan has been renewed
          type: integer
          minimum: 0
        feesAndFines:
          description: Fees and fines associated with loans
          type: object
          properties:
            amountRemainingToPay:
              description: Total remaining amount due on fees and fines for the loan (read-only, defined by the server)
              type: number
          additionalProperties: true
        metadata:
          description: Metadata about creation and changes to loan, provided by the server (client should not provide)
          type: object
      additionalProperties: true
    claim-item-returned-request:
      allOf:
      - $ref: '#/components/schemas/circulation-claim-item-returned-request'
      - type: object
        properties:
          loanId:
            description: ID of the loan created for the item claimed returned
            type: string
            format: uuid
          itemId:
            description: ID of the item claimed returned
            type: string
            format: uuid
          userId:
            description: ID of the user who had claimed item returned
            type: string
            format: uuid
    error:
      description: An error
      type: object
      properties:
        message:
          type: string
          description: Error message text
        type:
          type: string
          description: Error message type
        code:
          type: string
          description: Error message code
        parameters:
          type: object
          description: Error message parameters
          $ref: '#/components/schemas/parameters'
      additionalProperties: false
      required:
      - message
    errors:
      description: A set of errors
      type: object
      properties:
        errors:
          description: List of errors
          id: errors
          type: array
          items:
            type: object
            $ref: '#/components/schemas/error'
        total_records:
          description: Total number of errors
          type: integer
      additionalProperties: false
    parameters:
      description: List of key/value parameters of an error
      type: array
      items:
        type: object
        $ref: '#/components/schemas/parameter'
      additionalProperties: false
    check-out-request:
      type: object
      description: Check-out request
      properties:
        itemBarcode:
          description: Barcode of the item to be lent to the patron
          type: string
        userBarcode:
          description: Barcode of the user (representing the patron) the item is to be lent to
          type: string
        proxyUserBarcode:
          description: Barcode of the user representing a proxy for the patron
          type: string
        loanDate:
          description: When the loan is to begin, defaults to current date and time
          type: string
          format: date-time
        servicePointId:
          description: Service point where the item has been checked out
          type: string
          format: uuid
        forceLoanPolicyId:
          description: Force loan policy ID
          type: string
          format: uuid
        overrideBlocks:
          x-class-extra-annotation: '@com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.ALWAYS)'
          description: Blocks to override
          type: object
          properties:
            itemNotLoanableBlock:
              description: '''Item not loanable'' block'
              type: object
              properties:
                dueDate:
                  description: Due date for a new loan
                  type: string
                  format: date-time
              required:
              - dueDate
            patronBlock:
              description: Automated patron block
              type: object
            itemLimitBlock:
              description: Item limit block
              type: object
            renewalBlock:
              description: Renewal block
              type: object
            renewalDueDateRequiredBlock:
              description: Override renewal block which requires due date field
              type: object
              properties:
                dueDate:
                  description: Due date for a new loan
                  type: string
                  format: date-time
              required:
              - dueDate
            comment:
              description: Reason for override
              type: string
      required:
      - itemBarcode
      - userBarcode
      - servicePointId
    declare-item-lost-request:
      allOf:
      - $ref: '#/components/schemas/circulation-declare-item-lost-request'
      - type: object
        properties:
          loanId:
            description: ID of the loan created for the lost item
            type: string
            format: uuid
          itemId:
            description: ID of the lost item
            type: string
            format: uuid
          userId:
            description: ID of the user who had lost item on loan
            type: string
            format: uuid
    circulation-declare-item-lost-request:
      type: object
      description: Declare item lost request
      properties:
        servicePointId:
          description: ID of the service point where item is declared lost
          type: string
          format: uuid
        declaredLostDateTime:
          description: Date and time of the item loss
          type: string
          format: date-time
        comment:
          description: Additional information about item loss
          type: string
      required:
      - servicePointId
  responses:
    internalServerErrorResponse:
      description: When unhandled exception occurred during code execution, e.g. NullPointerException
      content:
        application/json:
          example:
            errors:
            - message: Unexpected error
            total_records: 1
          schema:
            $ref: '#/components/schemas/errors'
    badRequestResponse:
      description: Validation errors
      content:
        application/json:
          example:
            errors:
            - message: Request is invalid
            total_records: 1
          schema:
            $ref: '#/components/schemas/errors'
    notFoundResponse:
      description: Not found
      content:
        application/json:
          example:
            errors:
            - message: Request not found
            total_records: 1
          schema:
            $ref: '#/components/schemas/errors'
    unprocessableEntityResponse:
      description: Validation errors
      content:
        application/json:
          example:
            errors:
            - message: Request is invalid
            total_records: 1
          schema:
            $ref: '#/components/schemas/errors'
    checkOutResponse:
      description: Check out response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/check-out-response'
x-refined-from:
- folio-mod-tlr-ecs-loans-openapi.json
- folio-mod-tlr-ecs-loans-openapi.yml