Bug 20944: Add route to add credits to a patron's account
[koha.git] / Koha / REST / V1 / Patrons / Account.pm
1 package Koha::REST::V1::Patrons::Account;
2
3 # This file is part of Koha.
4 #
5 # Koha is free software; you can redistribute it and/or modify it under the
6 # terms of the GNU General Public License as published by the Free Software
7 # Foundation; either version 3 of the License, or (at your option) any later
8 # version.
9 #
10 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
11 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
12 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
13 #
14 # You should have received a copy of the GNU General Public License along
15 # with Koha; if not, write to the Free Software Foundation, Inc.,
16 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
17
18 use Modern::Perl;
19
20 use Mojo::Base 'Mojolicious::Controller';
21
22 use Koha::Patrons;
23
24 use Scalar::Util qw(blessed);
25 use Try::Tiny;
26
27 =head1 NAME
28
29 Koha::REST::V1::Patrons::Account
30
31 =head1 API
32
33 =head2 Methods
34
35 =head3 get
36
37 Controller function that handles retrieving a patron's account balance
38
39 =cut
40
41 sub get {
42     my $c = shift->openapi->valid_input or return;
43
44     my $patron_id = $c->validation->param('patron_id');
45     my $patron    = Koha::Patrons->find($patron_id);
46
47     unless ($patron) {
48         return $c->render( status => 404, openapi => { error => "Patron not found." } );
49     }
50
51     my $account = $patron->account;
52     my $balance;
53
54     $balance->{balance} = $account->balance;
55
56     # get outstanding debits and credits
57     my $debits  = $account->outstanding_debits;
58     my $credits = $account->outstanding_credits;
59
60     my @debit_lines = map { _to_api( $_->TO_JSON ) } @{ $debits->as_list };
61     $balance->{outstanding_debits} = {
62         total => $debits->total_outstanding,
63         lines => \@debit_lines
64     };
65
66     my @credit_lines = map { _to_api( $_->TO_JSON ) } @{ $credits->as_list };
67     $balance->{outstanding_credits} = {
68         total => $credits->total_outstanding,
69         lines => \@credit_lines
70     };
71
72     return $c->render( status => 200, openapi => $balance );
73 }
74
75 =head3 add_credit
76
77 Controller function that handles adding a credit to a patron's account
78
79 =cut
80
81 sub add_credit {
82     my $c = shift->openapi->valid_input or return;
83
84     my $patron_id = $c->validation->param('patron_id');
85     my $patron    = Koha::Patrons->find($patron_id);
86     my $user      = $c->stash('koha.user');
87
88
89     unless ($patron) {
90         return $c->render( status => 404, openapi => { error => "Patron not found." } );
91     }
92
93     my $account = $patron->account;
94     my $body    = $c->validation->param('body');
95
96     return try {
97         my $credit_type = $body->{credit_type} || 'payment';    # default to 'payment'
98         my $amount = $body->{amount};                           # mandatory, validated by openapi
99
100         unless ( $amount > 0 ) {  # until we support newer JSON::Validator and thus minimumExclusive
101             Koha::Exceptions::BadParameter->throw( { parameter => 'amount' } );
102         }
103
104         # read the rest of the params
105         my $payment_type = $body->{payment_type};
106         my $description  = $body->{description};
107         my $note         = $body->{note};
108
109         my $credit = $account->add_credit(
110             {   amount       => $amount,
111                 credit_type  => $credit_type,
112                 payment_type => $payment_type,
113                 description  => $description,
114                 note         => $note,
115                 user_id      => $user->id
116             }
117         );
118         $credit->discard_changes;
119
120         my $date = $body->{date};
121         $credit->date( $date )->store
122             if $date;
123
124         my $debits_ids = $body->{account_lines_ids};
125         my $debits = Koha::Account::Lines->search({ accountlines_id => { -in => $debits_ids } })
126             if $debits_ids;
127
128         my $outstanding_credit = $credit->amountoutstanding;
129         if ($debits) {
130             # pay them!
131             $outstanding_credit = $credit->apply({ debits => $debits, offset_type => 'payment' });
132         }
133
134         if ($outstanding_credit) {
135             my $outstanding_debits = $account->outstanding_debits;
136             $credit->apply({ debits => $outstanding_debits, offset_type => 'payment' });
137         }
138
139         return $c->render( status => 200, openapi => { account_line_id => $credit->id } );
140     }
141     catch {
142         if ( blessed $_ && $_->can('rethrow') ) {
143             return $c->render(
144                 status  => 400,
145                 openapi => { error => "$_" }
146             );
147         }
148         else {
149             # Exception, rely on the stringified exception
150             return $c->render(
151                 status  => 500,
152                 openapi => { error => "Something went wrong, check the logs" }
153             );
154         }
155     };
156 }
157
158
159 =head3 _to_api
160
161 Helper function that maps unblessed Koha::Account::Line objects
162 into REST API attribute names.
163
164 =cut
165
166 sub _to_api {
167     my $account_line = shift;
168
169     # Rename attributes
170     foreach my $column ( keys %{ $Koha::REST::V1::Patrons::Account::to_api_mapping } ) {
171         my $mapped_column = $Koha::REST::V1::Patrons::Account::to_api_mapping->{$column};
172         if (    exists $account_line->{ $column }
173              && defined $mapped_column )
174         {
175             # key != undef
176             $account_line->{ $mapped_column } = delete $account_line->{ $column };
177         }
178         elsif (    exists $account_line->{ $column }
179                 && !defined $mapped_column )
180         {
181             # key == undef
182             delete $account_line->{ $column };
183         }
184     }
185
186     return $account_line;
187 }
188
189 =head3 _to_model
190
191 Helper function that maps REST API objects into Koha::Account::Line
192 attribute names.
193
194 =cut
195
196 sub _to_model {
197     my $account_line = shift;
198
199     foreach my $attribute ( keys %{ $Koha::REST::V1::Patrons::Account::to_model_mapping } ) {
200         my $mapped_attribute = $Koha::REST::V1::Patrons::Account::to_model_mapping->{$attribute};
201         if (    exists $account_line->{ $attribute }
202              && defined $mapped_attribute )
203         {
204             # key => !undef
205             $account_line->{ $mapped_attribute } = delete $account_line->{ $attribute };
206         }
207         elsif (    exists $account_line->{ $attribute }
208                 && !defined $mapped_attribute )
209         {
210             # key => undef / to be deleted
211             delete $account_line->{ $attribute };
212         }
213     }
214
215     return $account_line;
216 }
217
218 =head2 Global variables
219
220 =head3 $to_api_mapping
221
222 =cut
223
224 our $to_api_mapping = {
225     accountlines_id   => 'account_line_id',
226     accountno         => undef,                  # removed
227     accounttype       => 'account_type',
228     amountoutstanding => 'amount_outstanding',
229     borrowernumber    => 'patron_id',
230     dispute           => undef,
231     issue_id          => 'checkout_id',
232     itemnumber        => 'item_id',
233     manager_id        => 'user_id',
234     note              => 'internal_note',
235 };
236
237 =head3 $to_model_mapping
238
239 =cut
240
241 our $to_model_mapping = {
242     account_line_id    => 'accountlines_id',
243     account_type       => 'accounttype',
244     amount_outstanding => 'amountoutstanding',
245     checkout_id        => 'issue_id',
246     internal_note      => 'note',
247     item_id            => 'itemnumber',
248     patron_id          => 'borrowernumber',
249     user_id            => 'manager_id'
250 };
251
252 1;