Wiki source code of 4. Invoice

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