Patrons account lines endpoint RFC

= 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
= 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).
Category:RFCs