Wiki source code of 4. Invoice

Last modified by David Persson on 2024/06/25 14:12
Show last authors
1 (% class="jumbotron" %)
2 (((
3 (% class="container" %)
4 (((
5 Integrate to **PayEx Invoice API **
6 )))
7 )))
8
9 (% id="HRoutesegments" %)
10 == Introduction ==
11
12 (% class="lead" %)
13 This api is used to retrieve information related to the customer's invoices.
14
15 [[image:1670584338716-116.png||height="815" width="406"]]
16
17
18 PayEx supports HTTP headers for tracking that are used for troubleshooting purposes, implement according to [[specification>>https://developer.payex.com/xwiki/wiki/developer/view/Main/Invoicing/invoice-service/Technical%20reference/API/security/#HHTTPHeaders]]
19
20 Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below
21
22 The below route is an example of a route towards resource3Id, to operate on this resource you must also include the ids of its parentresources in the route.
23 //lf-api.payex.com/ledger/**{Subdomain}**/v1/**{LedgerNumber}**/resource1/**{resource1Id}**/resource2/**{resource2Id}**/resource3/**{resource3Id}**//
24
25 (% class="table-bordered table-striped" %)
26 |=(% style="width: 604px;" %)Route segment|=(% style="width: 2790px;" %)Description
27 |(% style="width:604px" %)Subdomain|(% style="width:2790px" %)In this part of the API it will be invoice
28 |(% style="width:604px" %)LedgerNumber|(% style="width:2790px" %)The ledger identifier/number at PayEx
29 |(% style="width:604px" %)resource1Id|(% style="width:2790px" %)Identifier of resource1
30 |(% style="width:604px" %)resource2Id|(% style="width:2790px" %)identifier of resource2, subresource to resource1
31 |(% style="width:604px" %)resource3Id|(% style="width:2790px" %)identifier of resource3, subresource to resource2
32
33 (% class="wikigeneratedid" %)
34 Routes that occurs in examples of this documentation will use the following identifiers
35
36 (% class="table-bordered table-striped" %)
37 |=(% style="width: 330px;" %)Resource|=(% style="width: 1517px;" %)Identifier
38 |(% style="width:330px" %)LedgerNumber|(% style="width:1517px" %)XXX
39 |(% style="width:330px" %)Invoices|(% style="width:1517px" %)NNN (invoiceNo)
40 |(% style="width:330px" %)Documents|(% style="width:1517px" %)YYY (type)
41
42 == Invoice ==
43
44 The **invoice **resource is located under **ledger/invoice/v1/ **api**. **This resource is used to get general information about existing invoices and its current state. Creation of new invoices is done through other resource.
45
46
47 ==== Get specific invoice ====
48
49 ==== ====
50
51 {{code language="http" title="**Request**"}}
52 GET /ledger/invoice/v1/XXX/invoices/NNN HTTP/1.1
53 Host: -
54 Authorization: Bearer <Token>
55 Content-Type: application/json
56 {{/code}}
57
58
59 {{code language="http" title="**Response**"}}
60 HTTP/1.1 200 OK
61 Content-Type: application/json
62
63 {
64 "@id" : "/ledger/invoice/v1/XXX/invoices/12345",
65 "created" : "2019-05-06T00:00:00",
66 "invoiceNo" : "12345",
67 "externalInvoiceId" : "987654321",
68 "status" : "pending|open|closed",
69 "claimLevel" : "Invoice|RestReminder|Reminder|SecondReminder|CollectionClaim|DebtCollection",
70 "currentDebt" : 463.42,
71 "originalAmount" : 354.10,
72 "currency" : "sek",
73 "invoiceDate" : "2018-10-01T00:00:00",
74 "dueDate" : "2018-10-01T00:00:00",
75 "seller" : {
76 "name" : "testshop",
77 "number" : "12345"
78 },
79 "debt" : {
80 "capital" : 354.10,
81 "remiderFee" : 20.00,
82 "collectionFee" : 80.00,
83 "penaltyInterest" : 8.00,
84 "calculatedPenaltyInterest" : 1.32
85 },
86 "penaltyInterestRate": 15.00,
87 "bankPayment": {
88 "bankAccountNo": "123",
89 "bankAccountType": "BGSE",
90 "bic": "123456",
91 "iban": "SE12345678945631",
92 "paymentReference": "54867165675646"
93 },
94 "customer" : "/ledger/customer/v1/customers/XYZABC",
95 "transactions" : "/ledger/invoice/v1/XXX/invoices/12345/transactions",
96 "activePaymentOrders": "/ledger/invoice/v1/XXX/invoices/NNN/active-payment-orders",
97 "journal" : "/ledger/invoice/v1/XXX/invoices/12345/journal",
98 "documents": "/ledger/invoice/v1/XXX/invoices/NNN/documents",
99 "operations": [
100 {
101 "rel": "generate-invoice-portal-link",
102 "method": "POST",
103 "href": "/ledger/invoice/v1/XXX/invoices/NNN/generate-invoice-portal-link"
104 },
105 {
106 "rel": "transfer-to-account",
107 "method": "POST",
108 "href": "/ledger/invoice/v1/XXX/invoices/NNN/transfer-to-account"
109 }
110 ],
111 }
112 {{/code}}
113
114 ==== Get specific customers invoices ====
115
116 Use the querystring parameter "customerNo" to list invoices for a specific customer.
117
118
119 {{code language="http" title="**Request**"}}
120 GET /ledger/invoice/v1/XXX/invoices?customerNo=XYZABC HTTP/1.1
121 Host: -
122 Authorization: Bearer <Token>
123 Content-Type: application/json
124 {{/code}}
125
126
127 {{code language="http" title="**Response**"}}
128 HTTP/1.1 200 OK
129 Content-Type: application/json
130
131 {
132 "items": [
133 {
134 "@id" : "/ledger/invoice/v1/XXX/invoices/12345",
135 "invoiceNo" : "12345",
136 "status" : "pending",
137 "claimLevel" : "Invoice",
138 "originalAmount" : 354.10,
139 "dueDate" : "2021-10-01T00:00:00",
140 "customerNo" : "XYZABC"
141 },
142 {
143 "@id" : "/ledger/invoice/v1/XXX/invoices/987654",
144 "invoiceNo" : "987654",
145 "status" : "open",
146 "claimLevel" : "Invoice",
147 "originalAmount" : 122.00,
148 "dueDate" : "2020-10-01T00:00:00",
149 "customerNo" : "XYZABC"
150 },
151 {
152 "@id" : "/ledger/invoice/v1/XXX/invoices/456321",
153 "invoiceNo" : "456321",
154 "status" : "closed",
155 "claimLevel" : "Invoice",
156 "originalAmount" : 846.50,
157 "dueDate" : "2020-08-01T00:00:00",
158 "customerNo" : "XYZABC"
159 }
160 ]
161 }
162 {{/code}}
163
164 (% class="box infomessage" %)
165 (((
166 Note! Response example below is an updated model which will be available in production on the **3rd of July 2024**. 'currency' and 'invoiceDate' has been added to the response when listing invoices for a specific customer.
167 )))
168
169 {{code language="http" title="**Response**"}}
170 HTTP/1.1 200 OK
171 Content-Type: application/json
172
173 {
174 "items": [
175 {
176 "@id" : "/ledger/invoice/v1/XXX/invoices/12345",
177 "invoiceNo" : "12345",
178 "status" : "pending",
179 "claimLevel" : "Invoice",
180 "originalAmount" : 354.10,
181 "currency" : "sek",
182 "invoiceDate" : "2021-09-15T00:00:00",
183 "dueDate" : "2021-10-01T00:00:00",
184 "customerNo" : "XYZABC"
185 },
186 {
187 "@id" : "/ledger/invoice/v1/XXX/invoices/987654",
188 "invoiceNo" : "987654",
189 "status" : "open",
190 "claimLevel" : "Invoice",
191 "originalAmount" : 122.00,
192 "currency" : "sek",
193 "invoiceDate" : "2021-09-15T00:00:00",
194 "dueDate" : "2020-10-01T00:00:00",
195 "customerNo" : "XYZABC"
196 },
197 {
198 "@id" : "/ledger/invoice/v1/XXX/invoices/456321",
199 "invoiceNo" : "456321",
200 "status" : "closed",
201 "claimLevel" : "Invoice",
202 "originalAmount" : 846.50,
203 "currency" : "sek",
204 "invoiceDate" : "2021-09-15T00:00:00",
205 "dueDate" : "2020-08-01T00:00:00",
206 "customerNo" : "XYZABC"
207 }
208 ]
209 }
210 {{/code}}
211
212 (% id="HAccountresourceproperties" %)
213 ==== Invoice resource properties ====
214
215
216 (% class="table-bordered table-striped" %)
217 |=Property|=Data type|=(% style="width: 117px;" %)Format|=Description
218 |@id |string|(% style="width:117px" %)Maxlength: |Uri of the specific account
219 |created|date|(% style="width:117px" %) |Date when the invoice was created in the system
220 |invoiceNo|string|(% style="width:117px" %)Maxlength: 50|The identifier of the account
221 |externalInvoiceId|string|(% style="width:117px" %)Maxlength: 50|External identifier of the invoice
222 |status|string|(% style="width:117px" %)Maxlength: 25|Status of the invoice(((
223 * **Pending**: the invoice has not been created yet, awaiting transactions
224 * **Open**: the invoice is open and active
225 * **Closed**: the invoice has been closed
226 )))
227 |claimLevel|string|Maxlength: 25|Current claim level of the invoice.(((
228 * **Invoice:** This is the first state the invoice get when it is created, it will have this state until due date is passed (and possibly later depending on companys claim process configuration)
229 * **RestReminder:** Reminder to pay remaining fees of the invoice (all capital has been payed) has been created/sent
230 * **Reminder:** First reminder to pay invoice that has been past due date has been creted/sent
231 * **SecondReminder:** Second reminder to pay invoice has been created/sent
232 * **CollectionClaim:** Debt collection claim has been created/sent to the customer
233 * **DebtCollection:** The invoice has been exported to other system for further handling of collection claims
234 )))
235 |currentDebt|decimal| |Total current debt of all balances (including capital / interest / fees, etc.). This value can be either positive or negative. (**positive value means it is a debt**)
236 |originalAmount|decimal|(% style="width:117px" %) |The original debt amount stated on the invoice.
237 |currency|string|(% style="width:117px" %)[[ISO 4217>>https://sv.wikipedia.org/wiki/ISO_4217]]|Currency of the invoice
238 |invoiceDate|date|(% style="width:117px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|Date when the invoice was created (printed on the invoice document)
239 |dueDate|date|(% style="width:117px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|Duedate of the invoice. This value does not exist for credit invoices
240 |seller.name|string|(% style="width:117px" %) |Name of the seller related to the invoice
241 |seller.number|string|(% style="width:117px" %) |The identifier of the seller
242 |debt|object|(% style="width:117px" %) |Current debt of the invoices separated in the different debt types
243 | debt.capital|decimal|(% style="width:117px" %) |This value only exists if there is any capital amount
244 | debt.reminderFee|decimal|(% style="width:117px" %) |This value only exists if there is any reminder fee //(also includes businessRemiderFee)//
245 | debt.collectionFee|decimal|(% style="width:117px" %) |This value only exists if there is any collection fee
246 | debt.penaltyInterest|decimal|(% style="width:117px" %) |This value only exists if there is any penalty interest
247 | debt.calculatedPenaltyInterest|decimal|(% style="width:117px" %) |Todays pending calculated penalty interest. Will be valid if a payment is made today.
248 This value only exists if there is any calculated penalty interest.
249 |penaltyInterestRate|decimal|(% style="width:117px" %)Percentage|yearly penalty interestrate (optional)
250 |bankPayment|object|(% style="width:117px" %) |optional. This object is only visible if the invoice is ready to be paid. Does not exists for invoices with status "closed", or for creditinvoices
251 | bankPayment.bankAccountNo|string|(% style="width:117px" %)Maxlength: 15|bankaccount for payment
252 | bankPayment.bankAccountType|string|(% style="width:117px" %)Maxlength: 10|BankAccountTypes:(((
253 * BKSE (swedish bank account)
254 * PKSE (swedish plusgiro)
255 * BGSE (swedish bankgiro)
256 * PGSE (swedish plusgiro OCR)
257 * BKNO (norwegian bank account)
258 * BKDK (danish bank account)
259 )))
260 | bankPayment.bic|string|(% style="width:117px" %)Maxlength: 11|Bank Identifier Code (BIC)
261 | bankPayment.iban|string|(% style="width:117px" %)Maxlength: 34|International Bank Account Number (IBAN)
262 | bankPayment.paymentReference|string|(% style="width:117px" %)Maxlength: 50|(((
263 reference to specify on the payment
264 )))
265 |customer|string|(% style="width:117px" %)Uri|Uri to the customer resource related to the invoice
266 |transactions|string|(% style="width:117px" %)Uri|List all transactions that has occured on the invoice
267 |activePaymentOrders|string|(% style="width:117px" %)Uri|View scheduled payment orders
268 |journal|string|(% style="width:117px" %)Uri|Lists events that has occured on the invoice
269 |documents|string|(% style="width:117px" %)Uri|View the actual invoice document (and other related documents), how it has been distributed etc.
270
271 (% id="HDocuments" %)
272 == Documents ==
273
274 The documents resources contains basic info of each invoice, reminder, letters etc. that has been produced related to the invoice. It also includes a url to download the actual document.
275
276
277 (% id="HListallbillsofanaccount" %)
278 ==== List all documents of an invoice ====
279
280 {{code language="http" title="**Request**"}}
281 GET /ledger/invoice/v1/XXX/invoices/NNN/documents HTTP/1.1
282 Host: -
283 Authorization: Bearer <Token>
284 Content-Type: application/json
285
286 {{/code}}
287
288
289 {{code language="http" title="**Response**"}}
290 HTTP/1.1 200 OK
291 Content-Type: application/json
292
293 {
294 "@id": "/ledger/invoice/v1/501/invoices/NNN/documents",
295 "items" : [
296 {
297 "@id": "/ledger/invoice/v1/XXX/invoices/NNN/documents/852147",
298 "date": "2018-11-15T00:00:00",
299 "type" : "invoice",
300 "distributionMethod" : "NotDistributed|Postal|Kivra|EInvoice|EMail",
301 "document": "/ledger/invoice/v1/XXX/invoices/NNN/documents/852147/document"
302 },
303 {
304 "@id": "/ledger/invoice/v1/XXX/invoices/NNN/documents/123654",
305 "date": "2018-11-15T00:00:00",
306 "type" : "reminder",
307 "distributionMethod" : "NotDistributed|Postal|Kivra|EInvoice|EMail",
308 "document": "/ledger/invoice/v1/XXX/invoices/NNN/documents/123654/document"
309 }
310 ]
311 }
312 {{/code}}
313
314 (% id="H-1" %)
315 ==== ====
316
317 (% id="HGetspecificbill" %)
318 ==== Get specific document ====
319
320 {{code language="http" title="**Request**"}}
321 GET /ledger/invoice/v1/XXX/invoices/NNN/documents/YYY HTTP/1.1
322 Host: -
323 Authorization: Bearer <Token>
324 Content-Type: application/json
325
326 {{/code}}
327
328
329 {{code language="http" title="**Response**"}}
330 HTTP/1.1 200 OK
331 Content-Type: application/json
332
333 {
334 "@id": "/ledger/invoice/v1/XXX/invoices/NNN/documents/123645",
335 "date": "2018-11-15T00:00:00",
336 "type" : "reminder",
337 "distributionMethod" : "NotDistributed|Postal|Kivra|EInvoice|EMail",
338 "document": "/ledger/invoice/v1/XXX/invoices/NNN/documents/123645/document"
339 }
340 {{/code}}
341
342 (% id="HBillresourceproperties" %)
343 ==== Document resource properties ====
344
345 (% class="table-bordered table-striped" %)
346 |=Property|=Data type|=Format|=Description
347 |@id|string|Uri|
348 |date|date|[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|Date when the document was created
349 |type|string| |(((
350 Currently available types of document
351
352 * **Invoice **- the actual invoice
353 * **Reminder **- reminder of the invoice
354 * **RestReminder **- reminder of rest amounts
355 * **Collection **- Collection claim of the invoice
356 * **CreditInvoice**
357 * **BillAttachmentTypeName**
358 ** **SA **(summary)
359 ** **SSA **(Consolidated Summary)
360 ** **SP **(Specification)
361 )))
362 |distributionMethod|string| |(((
363 * **NotDistributed **- the letter has been created but not distributed
364 * **Postal **- Distributed through usual post
365 * **Kivra **- Digitally distributed through Kivra
366 * **EInvoice **- Digitally distributed through EInvoice
367 * **EMail **- Digitally distributed through email
368 )))
369 |document|string|Uri|Uri to download the actual document, usually pdf (content type in response).
370
371 == Transactions ==
372
373 This resource lists all transactions that has occured on the invoice. The resource does not support "GET" on individual transactions, only listing of all transactions.
374 Property "typeName" is ment to be displayed directly "as is" in a customer portal, it is translated to a readable text in the language configured on the current company.
375
376
377 (% id="HListallbillsofanaccount" %)
378 ==== List all transactions that has occured on an invoice ====
379
380
381 {{code language="http" title="**Request**"}}
382 GET /ledger/invoice/v1/XXX/invoices/NNN/transactions HTTP/1.1
383 Host: -
384 Authorization: Bearer <Token>
385 Content-Type: application/json
386
387 {{/code}}
388
389
390 {{code language="http" title="**Response**"}}
391 HTTP/1.1 200 OK
392 Content-Type: application/json
393
394 {
395 "@id": "/ledger/invoice/v1/501/invoices/NNN/transactions",
396 "items" : [
397 {
398 "type": "disbursement",
399 "typeName": "Utbetalningsuppdrag skapat",
400 "reference": "",
401 "amount": 50.00,
402 "date": "2019-11-09T00:00:00"
403 },
404 {
405 "type": "payment",
406 "typeName": "Betalning",
407 "reference": "",
408 "amount": -100.00,
409 "date": "2019-11-09T00:00:00"
410 },
411 {
412 "type": "credit",
413 "typeName": "Kreditering",
414 "reference": "",
415 "amount": -100.00,
416 "date": "2019-11-02T00:00:00",
417 "cause" : {
418 "type": "bankruptcy",
419 "typeName": "Konkurs"
420 }
421 },
422 {
423 "type": "credit",
424 "typeName": "Kreditering",
425 "reference": "korrigering dröjsmålsränta",
426 "amount": -00.85,
427 "date": "2019-11-02T00:00:00",
428 "cause" : {
429 "type": "remission",
430 "typeName": "Efterskänkes"
431 }
432 },
433 {
434 "type": "credit",
435 "typeName": "Kreditering",
436 "reference": "reglering mot kreditfaktura NNN",
437 "amount": -100.00,
438 "date": "2019-11-02T00:00:00",
439 },
440 {
441 "type": "collectionFee",
442 "typeName": "Inkassoavgift",
443 "reference": "",
444 "amount": 180.00,
445 "date": "2019-11-02T00:00:00",
446 },
447 {
448 "type": "reminderFee",
449 "typeName": "Påminnelseavgift",
450 "reference": "",
451 "amount": 30.00,
452 "date": "2019-11-02T00:00:00",
453 },
454 {
455 "type": "interest",
456 "typeName": "ränta",
457 "reference": "",
458 "amount": 2.00,
459 "date": "2019-11-02T00:00:00",
460 },
461 {
462 "type": "invoice",
463 "typeName": "Faktura",
464 "reference": "butiksnamn, Orderref. 345",
465 "amount": 200.00,
466 "date": "2020-10-09T00:00:00"
467 }
468 ]
469 }
470 {{/code}}
471
472 (% id="H-1" %)
473 ==== ====
474
475 (% id="HGetspecificbill" %)
476 ==== Transaction resource properties ====
477
478 (% class="table-bordered table-striped" %)
479 |=(% style="width: 405px;" %)Property|=(% style="width: 129px;" %)Data type|=(% style="width: 1236px;" %)Description
480 |(% style="width:405px" %)@id|(% style="width:129px" %)string|(% style="width:1236px" %)
481 |(% style="width:405px" %)type|(% style="width:129px" %)string|(% style="width:1236px" %)Type of transaction
482 |(% style="width:405px" %)typeName|(% style="width:129px" %)string|(% style="width:1236px" %)(((
483 The type of transaction in form of a readable translated text (the local language of the current company)
484
485 The following types can occur on a invoice
486
487 * Invoice //(the transaction that is the basis for the invoice)//
488 * CreditInvoice// (the transaction that is the basis for the credit invoice)//
489 * Credit// (credited amount)//
490 * Interest
491 * Payment
492 * Disbursement //(If, for example, a surplus occur on the invoice, it can be paid out)//
493 * DisbursementReturned //(amount that failed to be paid out for any reason is returned on the invoice)//
494 * InvoiceFee
495 * ReminderFee
496 * CollectionFee
497 )))
498 |(% style="width:405px" %)reference|(% style="width:129px" %)string|(% style="width:1236px" %)Transaction reference
499 |(% style="width:405px" %)amount|(% style="width:129px" %)decimal|(% style="width:1236px" %)Amount ot the transaction
500 |(% style="width:405px" %)date|(% style="width:129px" %)date|(% style="width:1236px" %)Date when the transaction occured
501 |(% style="width:405px" %)cause|(% style="width:129px" %)object|(% style="width:1236px" %)This object is available when there is a specific cause to why the transaction has occured
502 |(% style="width:405px" %) cause.type|(% style="width:129px" %)string|(% style="width:1236px" %)Type of cause to why the transaction has occured
503 |(% style="width:405px" %) cause.typeName|(% style="width:129px" %)string|(% style="width:1236px" %)The type of cause in form of a readable translated text (in the local language of the current company)
504
505 == Active payment orders ==
506
507 This resource corresponds to an active / scheduled payment order placed against the specific account, the end-customer will be debited at the given executeDate.
508
509 (% id="HGetactivepaymentordersforanaccount" %)
510 ====
511 Get active payment orders for an account ====
512
513
514 {{code language="http" title="**Request**"}}
515 GET /ledger/invoice/v1/XXX/invoices/NNN/active-payment-orders/ HTTP/1.1
516 Host: -
517 Authorization: Bearer <Token>
518 Content-Type: application/json
519 {{/code}}
520
521
522 {{code language="http" title="**Response**"}}
523 HTTP/1.1 200 OK
524 Content-Type: application/json
525
526 {
527 "operations": null,
528 "items": [
529 {
530 "paymentMethod": "autogiro",
531 "executeDate": "2020-02-15",
532 "amount": 200.00
533 }
534 ]
535 }
536 {{/code}}
537
538 (% id="H-2" %)
539 ==== ====
540
541 (% id="HActive-payment-ordersresourceproperties" %)
542 ==== Active-payment-orders resource properties ====
543
544 (% class="table-bordered table-striped" %)
545 |=Property|=Data type|=Description
546 |paymentMethod|string|paymentMethods:(((
547 * autogiro
548 )))
549 |executeDate|Date|(((
550 The date when the customers bankaccount will be charged
551 )))
552 |amount|decimal|The amount that will be withdrawn from the bankaccount
553
554 (% id="HJournal" %)
555 == Journal ==
556
557 This resource lists all events that has occured on the invoice, in a sorted timeline.
558
559 (% id="HGetactivepaymentordersforanaccount" %)
560 ====
561 Get journal entries for the invoice ====
562
563
564 {{code language="http" title="**Request**"}}
565 GET /ledger/invoice/v1/XXX/invoices/NNN/journal/ HTTP/1.1
566 Host: -
567 Authorization: Bearer <Token>
568 Content-Type: application/json
569 {{/code}}
570
571
572 {{code language="http" title="**Response**"}}
573 HTTP/1.1 200 OK
574 Content-Type: application/json
575
576 {
577 "operations": null,
578 "items": [
579 {
580 "type": "ComplaintReceived",
581 "date" : "2020-09-01T00:00:00",
582 "description" : ""
583 },
584 {
585 "type": "SecondReminderSent",
586 "date" : "2020-09-01T00:00:00",
587 "description" : ""
588 },
589 {
590 "type": "ReminderSent",
591 "date" : "2020-09-01T00:00:00",
592 "description" : ""
593 }
594 ],
595 "view": {
596 "@id": "/ledger/invoice/v1/XXX/invoices/NNN/journal?$top=2&$skip=0",
597 "next": "/ledger/invoice/v1/XXX/invoices/NNN/journal?$top=2&$skip=2"
598 }
599 }
600 {{/code}}
601
602 (% id="H-2" %)
603 ==== ====
604
605 (% id="HActive-payment-ordersresourceproperties" %)
606 ==== Journal resource properties ====
607
608 (% class="table-bordered table-striped" %)
609 |=Property|=Data type|=Description
610 |type|string|type:(((
611 * **ReminderSent **//(an invoice reminder has been sent to the customer)//
612 * **SecondReminderSent **//(a second invoice reminder has been sent to the customer)//
613 * **CollectionClaimSent **//(a collection claim has been sent to the customer)//
614 * **RestReminderSent **//(a reminder including only interest and fees has been sent to the customer)//
615 * **DebtCollection **//(the invoice has been transferred to collection)//
616 * **Respite// //**//(the claim is stopped for further claimprocess steps until valid to data of respite or respite is removed)//
617 * **RespiteRemoved** //(respite has been removed fro claim)//
618 * **Stop// //**//(the claim is stopped for further claim process steps until stop is removed)//
619 * **StopRemoved **//(stop has been removed from claim)//
620 * **ComplaintReceived// //**//(complaint has been registered)//
621 * **ComplaintResolved **//(complaint has been resolved)//
622 * **InvoiceClosed **//(status of the invoice in the accounts receivable has been set to closed)//
623 * **PaymentOrderFailed **//(scheduled paymentorder failed to be executed)//
624 )))
625 |date|Date|(((
626 The date when the journal entry occured
627 )))
628 |description|string|detailed description of the entry (if available)
629
630 == Register direct payment ==
631
632 operation for registration of direct payments against invoices
633
634 {{code language="http" title="**Request**"}}
635 POST /ledger/invoice/v1/XXX/invoices/NNN/register-direct-payment HTTP/1.1
636 Host: -
637 Authorization: Bearer <Token>
638 Content-Type: application/json
639
640 {
641 "amount" : 100.00,
642 "paymentDate" : "2021-04-27",
643 "Cause" : "psp"
644 }
645 {{/code}}
646
647 (% id="HActive-payment-ordersresourceproperties" %)
648 ==== Register-direct-payment request properties ====
649
650 (% class="table-bordered table-striped" %)
651 |=Property|=Data type|=Required|=Description
652 |amount|decimal|Yes|The amount of the direct payment
653 |paymentDate|Date|Yes|(((
654 The date when the payment was made
655 )))
656 |cause|string|No|(((
657 * psp
658 )))
659
660 {{code language="http" title="**Response**"}}
661 HTTP/1.1 204 NO CONTENT
662 Content-Type: application/json
663
664 {{/code}}
665
666 == Settle-credit-invoice ==
667
668 operation to settle an existing credit invoice towards debit invoice. This operation is only be available/valid on credit-invoices
669
670 {{code language="http" title="**Request**"}}
671 POST /ledger/invoice/v1/XXX/invoices/NNN/settle-credit-invoice HTTP/1.1
672 Host: -
673 Authorization: Bearer <Token>
674 Content-Type: application/json
675
676 {
677 "debitInvoiceNo": "12345",
678 "creditAmount": 250.00,
679 "sendCopy": false
680 }
681 {{/code}}
682
683 (% id="HActive-payment-ordersresourceproperties" %)
684 ==== Settle-credit-invoice request properties ====
685
686 (% class="table-bordered table-striped" %)
687 |=Property|=Data type|=Required|=Description
688 |debitInvoiceNo|string|Yes|invoice number of the debit invoice that the credit invoice is to be settled against
689 |creditAmount|decimal|Yes|(((
690 Amount of the credit invoice to use
691 )))
692 |sendCopy|bool|No|Whether a new copy should be distributed to the end-customer with updated balances (after settlement has been executed)
693 Default false
694
695 {{code language="http" title="**Response**"}}
696 HTTP/1.1 204 NO CONTENT
697 Content-Type: application/json
698
699 {{/code}}
700
701 == Remission ==
702
703 operation to allow partialy remission of the debt. Usually used if there is a small debt left on the invoice after a payment hade been done, and the remaining amount should be offered.
704
705 {{code language="http" title="**Request**"}}
706 POST /ledger/invoice/v1/XXX/invoices/NNN/remission HTTP/1.1
707 Host: -
708 Authorization: Bearer <Token>
709 Content-Type: application/json
710
711 {
712 "balanceType": "CollectionFee",
713 "amount": 12.00
714 }
715 {{/code}}
716
717 (% id="HActive-payment-ordersresourceproperties" %)
718 ==== remission request properties ====
719
720 (% class="table-bordered table-striped" %)
721 |=Property|=Data type|=Required|=Description
722 |balanceType|string|Yes|(((
723 The balanceType to be affected
724
725 * capital
726 * reminderfee
727 * penaltyinterest
728 * collectionfee
729 )))
730 |amount|decimal|Yes|The amount of the specified balace type to exeute remission on
731
732 {{code language="http" title="**Response**"}}
733 HTTP/1.1 204 NO CONTENT
734 Content-Type: application/json
735
736 {{/code}}
737
738 == Write-down ==
739
740 operation to allow partialy or full write-down of the debt. the reason/cause of the write-down should be specified (affects accounting)
741
742 {{code language="http" title="**Request**"}}
743 POST /ledger/invoice/v1/XXX/invoices/NNN/write-down HTTP/1.1
744 Host: -
745 Authorization: Bearer <Token>
746 Content-Type: application/json
747
748 {
749 "balanceType": "CollectionFee",
750 "amount": 12.00,
751 "cause": "deceased",
752 "invoiceCurrentDebt": 462.10
753 }
754 {{/code}}
755
756 (% id="HActive-payment-ordersresourceproperties" %)
757 ==== Write-down request properties ====
758
759 (% class="table-bordered table-striped" %)
760 |=Property|=Data type|=Required|=Description
761 |balanceType|string|Yes|(((
762 The balanceType to be affected
763
764 * Capital
765 * ReminderFee
766 * PenaltyInterest
767 * CollectionFee
768 )))
769 |amount|decimal|Yes|The amount of the specified balace type to write-down
770 |cause|string|Yes|(((
771 The cause of the write-down
772
773 * Bankruptcy
774 * Settlement
775 * Deceased
776 * Fraud
777 * Dispute
778 * Unknown
779
780 If field is null, Then defaults to "Unknown". Case-Sensitive
781 )))
782 |{{{invoiceCurrentDebt}}}|decimal|Yes|The amount must match the current debt (**excl. Calculated interest**) on the invoice.
783 currentDebt - debt.calculatedPenaltyInterest
784
785 {{code language="http" title="**Response**"}}
786 HTTP/1.1 204 NO CONTENT
787 Content-Type: application/json
788
789 {{/code}}
790
791 == Respite ==
792
793 Resource to create or view respite
794
795 Get respite
796
797 {{code language="http" title="**Request**"}}
798 GET /ledger/invoice/v1/XXX/invoices/NNN/respite HTTP/1.1
799 Host: -
800 Authorization: Bearer <Token>
801 Content-Type: application/json
802
803 {{/code}}
804
805 {{code language="http" title="**Response**"}}
806 HTTP/1.1 200 OK
807 Content-Type: application/json
808
809 {
810 "validToDate": "2021-08-01",
811 "reason": "..."
812 }
813 {{/code}}
814
815 Create respite
816
817 {{code language="http" title="**Request**"}}
818 POST /ledger/invoice/v1/XXX/invoices/NNN/respite HTTP/1.1
819 Host: -
820 Authorization: Bearer <Token>
821 Content-Type: application/json
822
823 {
824 "validToDate": "2021-08-01",
825 "reason": "..."
826 }
827 {{/code}}
828
829 {{code language="http" title="**Response**"}}
830 HTTP/1.1 201 CREATED
831 Content-Type: application/json
832 {{/code}}
833
834 (% id="HActive-payment-ordersresourceproperties" %)
835 ==== Respite request properties ====
836
837 (% class="table-bordered table-striped" %)
838 |=Property|=Data type|=Required|=Description
839 |validToDate|Date|Yes|Respite is valid to this date
840 |reason|string|Yes|Reason for why the respite was created.
841
842 == Active-disbursement-orders ==
843
844 View or create disbursement orders, only available for credit-invoices
845
846 Get active-disbursement-orders
847
848 {{code language="http" title="**Request**"}}
849 GET /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
850 Host: -
851 Authorization: Bearer <Token>
852 Content-Type: application/json
853
854 {{/code}}
855
856 {{code language="http" title="**Response**"}}
857 HTTP/1.1 200 OK
858 Content-Type: application/json
859
860 {
861 "items" :
862 [
863 {
864 "@id" : "../ledger/v1/501/invoices/12345/active-disbursement-orders/456789",
865 "amount" : 10,
866 "norwegianBankAccount" : {
867 "accountNo" : "1234"
868 }
869 },
870 {
871 "@id" : "../ledger/v1/501/invoices/12345/active-disbursement-orders/456788",
872 "amount" : 10,
873 "international" : {
874 "iban" : "123456",
875 "bic" : "SWED..."
876 }
877 },
878 {
879 "@id" : "../ledger/v1/501/invoices/12345/active-disbursement-orders/456787",
880 "amount" : 10,
881 "swedishBankAccount" : {
882 "accountNo" : "123",
883 "accountType" : "BKSE | PGSE | BGSE"
884 }
885 },
886 {
887 "@id" : "../ledger/v1/501/invoices/12345/active-disbursement-orders/456786",
888 "amount" : 10,
889 "swedishSus" : {
890 "nationalIdentifier": {
891 "regNo" : "YYYYMMDD-NNNN",
892 "countryCode" : "SE"
893 },
894 "address" : {
895 "addressee" : "Kalle Axelstopp",
896 "streetAddress" : "Axelgatan 18",
897 "coAddress" : null,
898 "city" : "STOCKHOLM",
899 "zipCode" : "16872",
900 "countryCode" : "se"
901 }
902 }
903 }
904 ]
905 }
906 {{/code}}
907
908 Create disbursement order towards a norwegian bank account
909
910 {{code language="http" title="**Request**"}}
911 POST /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
912 Host: -
913 Authorization: Bearer <Token>
914 Content-Type: application/json
915
916 {
917 "amount" : 10,
918 "norwegianBankAccount" : {
919 "accountNo" : "1234"
920 }
921 }
922 {{/code}}
923
924 Create disbursement order towards a international bank account (IBAN)
925
926 {{code language="http" title="**Request**"}}
927 POST /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
928 Host: -
929 Authorization: Bearer <Token>
930 Content-Type: application/json
931
932 {
933 "amount" : 10,
934 "international" : {
935 "iban" : "123456",
936 "bic" : "SWED..."
937 }
938 }
939 {{/code}}
940
941 Create disbursement order towards a swedish bank account
942
943 {{code language="http" title="**Request**"}}
944 POST /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
945 Host: -
946 Authorization: Bearer <Token>
947 Content-Type: application/json
948
949 {
950 "amount" : 100,
951 "swedishBankAccount" : {
952 "accountNo" : "123",
953 "accountType" : "BKSE | PGSE | BGSE"
954 }
955 }
956 {{/code}}
957
958 Create disbursement order using "Swedbanks lön- och utbetalningssystem (SUS)"
959
960 {{code language="http" title="**Request**"}}
961 POST /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
962 Host: -
963 Authorization: Bearer <Token>
964 Content-Type: application/json
965
966 {
967 "amount" : 100,
968 "swedishSus" : {
969 "nationalIdentifier": {
970 "regNo" : "YYYYMMDD-NNNN",
971 "countryCode" : "SE"
972 },
973 "address" : {
974 "addressee" : "Kalle Axelstopp",
975 "streetAddress" : "Axelgatan 18",
976 "coAddress" : null,
977 "city" : "STOCKHOLM",
978 "zipCode" : "16872",
979 "countryCode" : "se",
980 }
981 }
982 }
983 {{/code}}
984
985
986 {{code language="http" title="**Response**"}}
987 HTTP/1.1 201 CREATED
988 Content-Type: application/json
989 {{/code}}
990
991 (% id="HActive-payment-ordersresourceproperties" %)
992 ==== Respite request properties ====
993
994 (% class="table-bordered table-striped" %)
995 |=Property|=Data type|=Required|=Description
996 |amount|decimal|Yes|
997 |__**norwegianBankAccount**__|object|No*|
998 | accountNo|string|Yes|
999 |__**swedishBankAccount**__|object|No*|
1000 | clearingNo|string|Yes|
1001 | accountNo|string|Yes|
1002 |__**international**__|object|No*|
1003 | iban|string|Yes|
1004 | bic|string|Yes|
1005 |__**swedishSus**__|object|No*|
1006 |**nationalIdentifier**|object|Yes|
1007 | regNo|string|Yes|
1008 | countryCode|string|Yes|
1009 |**address**|object|Yes|
1010 | addressee|string|Yes|
1011 | streetAddress|string|No|
1012 | coAddress|string|No|
1013 | city|string|Yes|
1014 | zipCode|string|Yes|
1015 | countryCode|string|Yes|
1016 | | | |
1017
1018 //* One and only one of the specified objects can be set at each request//
1019
1020 == Transfer-to-account ==
1021
1022 operation transfer current capital debt on the invoice to a provided account. This will close the invoice.
1023
1024 {{code language="http" title="**Request**"}}
1025 POST /ledger/invoice/v1/XXX/invoices/NNN/transfer-to-account HTTP/1.1
1026 Host: -
1027 Authorization: Bearer <Token>
1028 Content-Type: application/json
1029
1030 {
1031 "accountNo" : "123",
1032
1033 }
1034
1035 {{/code}}
1036
1037 (% id="HActive-payment-ordersresourceproperties" %)
1038 ==== Transfer-to-account request properties ====
1039
1040 (% class="table-bordered table-striped" %)
1041 |=Property|=Data type|=Required|=Description
1042 |accountNo|string|Yes|account number to the to transfer current capital debt into
1043
1044 {{code language="http" title="**Response**"}}
1045 HTTP/1.1 204 NO CONTENT
1046 Content-Type: application/json
1047
1048 {{/code}}
1049
1050 == ==
1051
1052 == Generate-invoice-portal-link ==
1053
1054 Creates a new public available (no authorization needed) link to the targeted invoice. Default lifetime of a link is 120 days. Creating new links does not affect old links.
1055
1056 {{code language="http" title="**Request**"}}
1057 POST /ledger/invoice/v1/XXX/invoices/NNN/generate-invoice-portal-link HTTP/1.1
1058 Host: -
1059 Authorization: Bearer <Token>
1060 Content-Type: application/json
1061
1062 {
1063 }
1064
1065 {{/code}}
1066
1067 (% id="HActive-payment-ordersresourceproperties" %)
1068 ==== ====
1069
1070 {{code language="http" title="**Response**"}}
1071 HTTP/1.1 200 OK
1072 Content-Type: application/json
1073
1074 {
1075 "invoicePortalLink": "https://public-invoice-example.com/sv/XXX?token=eyJhbGciOiJSUzI1Ni..."
1076 }
1077 {{/code}}
1078
1079 {{display reference="developer:Main.Invoicing.ledger-api-general-docs.api-section-problems.WebHome"/}}
1080
1081 === Problem types ===
1082
1083 (% class="box infomessage" %)
1084 (((
1085 Note, each problem typecode is preceded by "ledger/invoice/v1/problems/" in this API, e.g. the error "validation" in the table below will appear as typecode "ledger/invoice/v1/problems/validation".
1086 )))
1087
1088 (% class="table-bordered table-striped" %)
1089 |=(% style="width: 537px;" %)Problem type (code)|=(% style="width: 172px;" %)Httpstatus|=(% style="width: 796px;" %)Description
1090 |(% style="width:537px" %)forbidden|(% style="width:172px" %)403|(% style="width:796px" %)occurs if access to method is not allowed.
1091 |(% style="width:537px" %)customer-not-found|(% style="width:172px" %)404|(% style="width:796px" %)can occur if customernumber is part of the querystring towards invoice resource
1092 |(% style="width:537px" %)invoice-not-found|(% style="width:172px" %)404|(% style="width:796px" %)
1093 |(% style="width:537px" %)missing-offer|(% style="width:172px" %)409|(% style="width:796px" %)Invoice is not a candidate for **transfer-to-account**. This has nothing to do with the provided Account
1094 |(% style="width:537px" %)missing-account-for-billing-account|(% style="width:172px" %)409|(% style="width:796px" %)No account found on the provided AccountNo, can be expected on the us of **transfer-to-account** operation
1095 |(% style="width:537px" %)not-acceptable-for-conversion|(% style="width:172px" %)409|(% style="width:796px" %)Invoice or account was not acceptable for transfer. This could be caused a number of parameters both on the invoice and the account.
1096 |(% style="width:537px" %)credit-check-rejected|(% style="width:172px" %)422|(% style="width:796px" %)Score does not approve the conversion
1097 |(% style="width:537px" %)customer-mismatch|(% style="width:172px" %)422|(% style="width:796px" %)Invoice and account is on separate customers in the **transfer-to-account** request
1098 |(% style="width:537px" %) |(% style="width:172px" %) |(% style="width:796px" %)