General overview
This RFC proposes several endpoints:
Account lines
- /account/lines: for dealing with account lines (listing and making them void).
Patron's balance
- /patrons/{patron_id}/account: for fetching the patron's balance information.
Patron's credits and debits
- GET /patrons/{patron_id}/account/credits: for listing a patrons credits
- POST /patrons/{patron_id}/account/credits: for creating credit-based account lines (both against account lines and fixed amounts).
- GET /patrons/{patron_id}/account/debits: for listing a patrons debits
- POST /patrons/{patron_id}/account/debits: for creating debit-based account lines (both against account lines and fixed amounts).
Account lines
Routes and actions
| Description
|
Action
|
Proposed path
|
| List account lines
|
GET
|
/account/lines
|
| Get a single account line
|
GET
|
/account/lines/{account_line_id}
|
| Void a credit
|
DELETE
|
/account/lines/{account_line_id}
|
| Partially update an account line (only description fields)
|
PATCH
|
/account/lines/{account_line_id}
|
Making credits void
Bug 20703 introduces a way to void any kind of credit. This spec is based on that capability.
This action only applies to credits, so trying to void a debit will result in a bad request code.
Object definition
Bug 20777 removes the accountlines.dispute column, this spec is based on it.
| DB schema
|
API
|
Description
|
| accountlines_id
|
account_line_id
|
Internal account line identifier
|
| issue_id
|
checkout_id
|
Internal ID for the checkout the account line is related to
|
| borrowernumber
|
patron_id
|
Internal identifier for the patron the account line belongs to
|
| accountno
|
REMOVED
|
No longer required.
|
| dispute
|
REMOVED
|
No longer required.
|
| itemnumber
|
item_id
|
Internal identifier for the item the account line is related to (fines?)
|
| date
|
date
|
Date the account line was created
|
| amount
|
amount
|
Account line amount
|
| description
|
description
|
Description
|
| accounttype
|
account_type (Payment, Writeoff, Fine TODO: track use cases)
|
Type of account line
|
| payment_type
|
payment_type (optional, see PAYMENT_TYPE usage on the codebase)
|
Payment type (only applies if account_type related to some kind of payment)
|
| amountoutstanding
|
amount_outstanding
|
Outstanding amount
|
| lastincrement
|
last_increment
|
The amount the fine was updated on the last update
|
| timestamp
|
timestamp (what about date?)
|
Timestamp for the latest update
|
| note
|
internal_note
|
Internal note
|
| manager_id
|
user_id
|
Internal patron identifier for the staff member that introduced the account line
|
Query parameters
Use the existing objects.search method of adding query facilities
Patron's balance
Routes and actions
| Description
|
Action
|
Proposed path
|
| Fetch patron's balance
|
GET
|
/patrons/{patron_id}/account
|
Object definition
| Attribute
|
Description
|
| balance
|
A signed integer, from $patron->account->balance.
|
| outstanding_credits
|
An object representing the total outstanding credits, and the corresponding account line objects
|
| outstanding_debits
|
An object representing the total outstanding debits, and the corresponding account line objects
|
Discussion
Does negative value mean the patron owes the library? It does sound more reasonable than the opposite, but the UI clearly does it the other way around, plus using colors to denote credits/debits.
Patron's credits
Routes and actions
| Description |
Action |
Proposed path
|
| Add a credit |
POST |
/patrons/{patron_id}/account/credits
|
Object definition
| Attribute
|
Description
|
| credit_type
|
Type of credit ('payment', 'writeoff', values of PAYMENT_TYPE )
|
| amount
|
Credit amount
|
| [ acount_line_ids ]
|
List of account line ids the credit goes against (Optional)
|
| date
|
Date the credit was recorded
|
| description
|
Description of the credit
|
| note
|
Note
|
Patron's debits
Routes and actions
| Description |
Action |
Proposed path
|
| Add a debit |
POST |
/patrons/{patron_id}/account/debits
|
Object definition
| Attribute
|
Description
|
| debit_type
|
Type of debit ('lost_item', 'fine', 'account_management_fee', 'new_card', 'sundry', values of MANUAL_INV )
|
| amount
|
Debit amount
|
| date
|
Date the debit was recorded
|
| description
|
Description of the debit
|
| note
|
Note
|
Maybe we could use staff_id or user_id instead of manager_id. I think this might be the only spot in Koha where we refere to a manager.
--Kfischer 16:08, 23 May 2018 (EDT)
Discussion (tcohen)
Specialized endpoints
We could have specialized endpoints for payments, writeoffs, fees and fines if found useful:
- /patrons/{patron_id}/account/payments: for creating payment-based account lines (both against account lines and fixed amounts).
- /patrons/{patron_id}/account/writeoffs: for creating writeoff-based account lines (both against account lines and fixed amounts).
- /patrons/{patron_id}/account/fees: for creating fee-based account lines.
- /patrons/{patron_id}/account/fines: for creating fine-based account lines.
Account types and negative values
The current DB schema includes:
- accountlines: each credit and debit operation is recorded here. The original value ('amount') is stored, and there's also 'amountstanding' which keeps the outstanding amount.
- account_offsets: this table records how credits and debits interact with each other (e.g. a payment is recorded as an account line, but affects existing lines that are debits, each 'decrese' action on those debits outstanding amounts is recorded as an offset).