Patrons account lines endpoint RFC

From Koha Wiki

Jump to: navigation, search

Contents

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

  • /patrons/{patron_id}/account/credits: for creating credit-based account lines (both against account lines and fixed amounts).
  • /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, to 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

It should accept filtering by dates, useful on large installations with thousands of patrons. Maybe something like:

  GET /account/lines?startDate=2016-03-22&endDate=2017-07-01


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

Comments

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).