Patrons account lines endpoint RFC

From Koha Wiki

Jump to: navigation, search

Contents

General overview

WARNING: This is WIP

This RFC proposes several endpoints:

Account lines

  • /account/lines: for dealing with account lines (listing and making them void).

Could this (and some of the other endpoints below) have start/end date ranges parameters? This could be 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

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

Discussion

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 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.
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  ?  ?
timestamp timestamp (what about date?)  ?
note note Note
manager_id manager_id Internal patron identifier for the staff member that introduced the account line

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

Patron's credits and debits

Routes and actions

Description Action Proposed path
Add a credit
 POST
 /patrons/{patron_id}/account/credits
Add a debit
 POST
 /patrons/{patron_id}/account/debits

Object definition

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)