Check in and out

What you can build

Borrowing at a self-service machine, at the staff desk or on the patron's own phone, by RFID or barcode. When a loan has conditions, such as a lending fee, the patron accepts them in the same flow. A machine can keep lending while the library system is out of reach and register the loans afterwards.

Typical flow

1. The patron is identified, either by logging in (2.2.1) or by their card number and, where required, a password.
2. The item is scanned, and the client calls Checkout with the item's ID, the patron, the branch and the time the patron acted.
3. If status is needs_acknowledgement, the client shows every entry in acknowledgement.conditions to the patron.
4. When the patron accepts, the client sends the same checkout again with acknowledgement.code.
5. If status is completed, checkout holds the loan, including dueDate. If it is failed, reason says why.

What the API provides

• The client must find circulation.checkout.isEnabled set to true in GetConfiguration before it calls Checkout.
• When the request is understood, the answer is 200. The outcome is in status: completed, needs_acknowledgement or failed. An unknown item is failed with item_not_found, not a 404.
• A condition is a lending_fee (with amount and currency), previously_checked_out (the patron has had the title before), or a message to accept. One code covers them all. It can be used once and expires at expiresAt.
• Reasons for failed include item_not_lendable, item_on_loan, item_reserved_for_other_patron, patron_blocked, patron_owes_fees, patron_loan_limit_reached, patron_expired and acknowledgement_rejected. Treat an unknown reason as unknown and show message.
• A patron identified by card number gets patron_authentication_failed for any problem with the identity, so nobody can find out which card numbers exist.
• Sending the same checkout again is safe. If the patron already has the item, the answer is completed with that loan.
• Offline: with circulation.checkout.offline.isAllowed, a machine can send checkout.offline with the dueDate it gave the patron. It must identify the patron by card number, and defaultLoanPeriodDays gives the loan period to use.
• message.text is shown to the patron. Send ui_language to choose its language.

What you can build

Returns at a self-service machine, a sorter or the staff desk. The answer tells where the item belongs and whether a person needs to look at it, so a sorter can route it straight away.

Typical flow

1. The item is scanned, and the client calls Checkin with the item's ID, the branch and the time it was returned.
2. If status is completed, checkin holds the result. If it is failed, reason says why.
3. The item is routed by permanentLocation, sortingCode and needsStaff.

What the API provides

• The client must find circulation.checkin.isEnabled set to true in GetConfiguration before it calls Checkin.
• When the request is understood, the answer is 200. The known reasons for failed are item_not_found, item_not_on_loan, item_belongs_to_other_library and unknown. Treat any other reason as unknown and show message.
• permanentLocation is where the item is normally kept: an item that belongs to another branch goes there. needsStaff is true when a person has to look at the item, for example when it is damaged.
• sortingCode carries the provider's own bin value, agreed between the library, the provider and the sorter supplier.
• fees lists fees the checkin created, for example an overdue fine.
• Sending the same checkin again is safe: item_not_on_loan on a retry means the item is already back.
• Offline: with circulation.checkin.offline.isAllowed, a machine can send checkin.offline set to true for a return it has already taken in.
• securityTags.isDisabled in GetConfiguration tells whether the library uses security tags. If not, the client should not arm them at checkin.