Wiki source code of 3. Invoice-service

Last modified by Thomas Hedström on 2025/11/06 11:11
Show last authors
1 (% class="jumbotron" %)
2 (((
3 (% class="container" %)
4 (((
5 Integrate to **PayEx Invoice service API **
6 )))
7 )))
8
9 (% id="HChangelog" %)
10 = Changelog =
11
12 2025-11-06
13
14 * Correction of documentation for Invoices resource, these are not any changes of the api, only the documentation .
15 ** Response for POST Credit and Debit invoice expects to respond with the resource created and __not a link to the invoice-api.__
16 ** Specified **invoiceNotes** & **InvoiceReason.invoiceReasonDescription **with RegEx Pattern
17
18 == Introduction ==
19
20 This API is used to create new invoices on existing customers
21
22 [[image:1615196225210-926.png||height="100" width="390"]]
23
24
25 Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below
26
27 The below route is an example of a route towards resource1Id
28 //lf-api.payex.com/ledger/**{Subdomain}**/v1/**{LedgerNumber}**/resource1/**{resource1Id}**//
29
30 (% class="table-bordered table-striped" %)
31 |=(% style="width: 604px;" %)Route segment|=(% style="width: 2790px;" %)Description
32 |(% style="width:604px" %)Subdomain|(% style="width:2790px" %)In this part of the API it will be **invoice-service**
33 |(% style="width:604px" %)LedgerNumber|(% style="width:2790px" %)The ledger identifier/number at PayEx
34 |(% style="width:604px" %)InvoiceNo|(% style="width:2790px" %)Identifier of resource invoice
35
36 (% class="wikigeneratedid" %)
37 Routes that occurs in examples of this documentation will use the following identifiers
38
39 (% class="table-bordered table-striped" %)
40 |=(% style="width: 488px;" %)Resource|=(% style="width: 2271px;" %)Identifier
41 |(% style="width:488px" %)LedgerNumber|(% style="width:2271px" %)XXX
42 |(% style="width:488px" %)Invoices|(% style="width:2271px" %)NNN
43
44 == ==
45
46 == Invoices ==
47
48 This resource is used to create new invoices, both debit invoices and credit invoices
49
50 (% class="box infomessage" %)
51 (((
52 Batches of multiple invoices should be processed sequentially towards the API. Each API call is intended for the creation of a single invoice
53 )))
54
55 ==== Example of a new debit invoice ====
56
57 {{code language="http" title="**Request**"}}
58 POST /ledger/invoice-service/v1/XXX/invoices HTTP/1.1
59 Host: -
60 Authorization: Bearer <Token>
61 Content-Type: application/json
62
63 {
64 "customerNo": "2992682",
65 "invoiceNo": "0000003",
66 "invoiceDate": "2021-05-15",
67 "preferredDueDate": "2021-06-15",
68 "externalInvoiceId": "900003",
69 "currency": "NOK",
70 "invoiceAddress": {
71 "addressee": "Annie Testsson",
72 "streetAddress": "Teststreet 1",
73 "zipCode": "50000",
74 "city": "Testcity",
75 "coAddress": "CO Bengtsson",
76 "countryCode": "SE"
77 },
78 "distribution": null,
79 "invoiceReason": {
80 "invoiceReasonCode": "CAS",
81 "invoiceReasonDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
82 },
83 "legalMonetaryTotal": {
84 "payableAmount": 97.99,
85 "vatInclusiveAmount": 98.01,
86 "vatExclusiveAmount": 98.01
87 },
88 "referenceInfo": {
89 "invoicePeriod": {
90 "startDate": "2021-04-07",
91 "endDate": "2021-04-25"
92 },
93 "deliveryInfo": {
94 "deliveryDate": "2021-04-27",
95 "deliveryAddress": {
96 "addressee": "Namn på mottagre",
97 "streetAddress": "Testgatan 789",
98 "zipCode": "11111",
99 "city": "Sthlm",
100 "coAddress": "C/O Andersson",
101 "countryCode": "SE"
102 }
103 },
104 "purchaseOrderReference": "Lorem ipsum dolor sit amet",
105 "salesOrderReference": "Lorem ipsum dolor sit amet",
106 "buyerReference": "Lorem ipsum dolor sit amet",
107 "invoicedObjectIdentifier": "Lorem ipsum do",
108 "contractReference": "Lorem ipsum dolor sit amet",
109 "despatchReference": "Lorem ipsum dolor sit amet",
110 "receiptReference": "Lorem ipsum dolor sit amet",
111 "tenderReference": "Lorem ipsum dolor sit amet",
112 "projectReference": "Lorem ipsum dolor sit amet"
113 },
114 "InvoiceNote": "InvoiceNote-Text e Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, ",
115 "invoiceSpecification": {
116 "inclVat": true,
117 "roundingAmount": -0.01,
118 "invoiceLines": [
119 {
120 "itemDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
121 "amount": 98.0,
122 "datePeriod": {
123 "StartDate": "2021-04-21",
124 "EndDate": "2021-04-25"
125 },
126 "gTIN": "156789123",
127 "itemObjectIdentifier": "itemObjectIdentifier",
128 "quantity": 1,
129 "unit": "ANN",
130 "unitPrice": 98.0,
131 "vatCategoryCode": "AE",
132 "vatRate": 10
133 },
134 {
135 "itemDescription": "Lorem ipsum dolor sit amet",
136 "amount": 0.01
137 }
138 ],
139 "invoiceVatSpecification": {
140 "vatSubTotal": [
141 {
142 "taxableAmount": 98.01,
143 "vatAmount": 0.0,
144 "vatRate": 1,
145 "vatCategoryCode": "Z"
146 }
147 ]
148 },
149 "taxCurrencyVatSpecification": {
150 "vatSubTotal": [
151 {
152 "taxableAmount": 50.0,
153 "vatAmount": 5.5,
154 "vatRate": 1.0,
155 "vatCategoryCode": "O"
156 }
157 ],
158 "taxCurrencyCode": "GBP",
159 "exchangeRate": 1.55
160 },
161 "taxReduction": {
162 "taxReductionDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
163 "taxReductionAmount": 0.01
164 }
165 }
166 }
167 {{/code}}
168
169 ==== Example of a new credit invoice ====
170
171 {{code language="http" title="**Request**"}}
172 POST /ledger/invoice-service/v1/XXX/invoices HTTP/1.1
173 Host: -
174 Authorization: Bearer <Token>
175 Content-Type: application/json
176
177 {
178 "customerNo": "2992682",
179 "invoiceNo": "000004",
180 "invoiceDate": "2021-05-17",
181 "externalInvoiceId": "900004",
182 "currency": "SEK",
183 "invoiceAddress": {
184 "addressee": "Annie Testsson",
185 "streetAddress": "Teststreet 1",
186 "zipCode": "50000",
187 "city": "Testcity",
188 "coAddress": "CO Bengtsson",
189 "countryCode": "SE"
190 },
191 "distribution": null,
192 "invoiceReason": {
193 "invoiceReasonCode": "CAS",
194 "invoiceReasonDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
195 },
196 "legalMonetaryTotal": {
197 "payableAmount": -88.0,
198 "vatInclusiveAmount": -88.01,
199 "vatExclusiveAmount": -88.01
200 },
201 "referenceInfo": {
202 "invoicePeriod": {
203 "startDate": "2021-04-07",
204 "endDate": "2021-04-25"
205 },
206 "deliveryInfo": {
207 "deliveryDate": "2021-04-27",
208 "deliveryAddress": {
209 "addressee": "Name of recipient",
210 "streetAddress": "Teststreet 789",
211 "zipCode": "11111",
212 "city": "Testcity",
213 "coAddress": "C/O Andersson",
214 "countryCode": "SE"
215 }
216 },
217 "purchaseOrderReference": "Lorem ipsum dolor sit amet",
218 "salesOrderReference": "Lorem ipsum dolor sit amet",
219 "buyerReference": "Lorem ipsum dolor sit amet",
220 "invoicedObjectIdentifier": "Lorem ipsum do",
221 "contractReference": "Lorem ipsum dolor sit amet",
222 "despatchReference": "Lorem ipsum dolor sit amet",
223 "receiptReference": "Lorem ipsum dolor sit amet",
224 "tenderReference": "Lorem ipsum dolor sit amet",
225 "projectReference": "Lorem ipsum dolor sit amet",
226 "debitInvoiceReferences": [
227 {
228 "debitInvoiceReference": "InvoiceNo xxxx"
229 }
230 ]
231 },
232 "InvoiceNote": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
233 "invoiceSpecification": {
234 "inclVat": true,
235 "roundingAmount": 0.01,
236 "invoiceLines": [
237 {
238 "itemDescription": "Description of item 1",
239 "amount": -88.01
240 }
241 ],
242 "invoiceVatSpecification": {
243 "vatSubTotal": [
244 {
245 "taxableAmount": -88.01,
246 "vatAmount": 0.0,
247 "vatRate": 1,
248 "vatCategoryCode": "Z"
249 }
250 ]
251 },
252 "taxCurrencyVatSpecification": {
253 "vatSubTotal": [
254 {
255 "taxableAmount": 50.0,
256 "vatAmount": 5.5,
257 "vatRate": 1.0,
258 "vatCategoryCode": "O"
259 }
260 ],
261 "taxCurrencyCode": "GBP",
262 "exchangeRate": 1.55
263 }
264 }
265 }
266 {{/code}}
267
268 {{code language="http" title="**Response**"}}
269 HTTP/1.1 200 OK
270 Host: -
271 Authorization: Bearer <Token>
272 Content-Type: application/json
273
274 {
275 "customerNo" : "900",
276 "invoiceNo" : "0000001",
277 "invoiceDate": "2021-05-15",
278 "preferredDueDate": "2021-06-15",
279 "externalInvoiceId": "900001",
280 "currency": "SEK",
281 "invoiceAddress": {
282 "addressee": "Annie Testsson",
283 "streetAddress": "Teststreet 1",
284 "zipCode": "50000",
285 "city": "Testcity",
286 "coAddress": "CO Bengtsson",
287 "countryCode": "SE"
288 },
289 "distribution": null,
290 "invoiceReason": {
291 "invoiceReasonCode": "CAS",
292 "invoiceReasonDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
293 },
294 "legalMonetaryTotal": {
295 "payableAmount": 88.00,
296 "vatInclusiveAmount": 98.01,
297 "vatExclusiveAmount": 98.01
298 },
299 "referenceInfo": {
300 "invoicePeriod": {
301 "startDate": "2021-04-07",
302 "endDate": "2021-04-25"
303 },
304 "deliveryInfo": {
305 "deliveryDate": "2021-04-27",
306 "deliveryAddress": {
307 "addressee": "Namn på mottagre",
308 "streetAddress": "Testgatan 789",
309 "zipCode": "11111",
310 "city": "Sthlm",
311 "coAddress": "C/O Andersson",
312 "countryCode": "SE"
313 }
314 },
315 "purchaseOrderReference": "Lorem ipsum dolor sit amet",
316 "salesOrderReference": "Lorem ipsum dolor sit amet",
317 "buyerReference": "Lorem ipsum dolor sit amet",
318 "invoicedObjectIdentifier": "Lorem ipsum do",
319 "contractReference": "Lorem ipsum dolor sit amet",
320 "despatchReference": "Lorem ipsum dolor sit amet",
321 "receiptReference": "Lorem ipsum dolor sit amet",
322 "tenderReference": "Lorem ipsum dolor sit amet",
323 "projectReference": "Lorem ipsum dolor sit amet"
324 },
325 "InvoiceNote": "InvoiceNote-Text e Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, ",
326 "invoiceSpecification": {
327 "inclVat": true,
328 "roundingAmount": -0.01,
329 "invoiceLines": [
330 {
331 "itemDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
332 "amount": 98.00,
333 "datePeriod": {
334 "StartDate": "2021-04-21",
335 "EndDate": "2021-04-25"
336 },
337 "gTIN": "156789123",
338 "itemObjectIdentifier": "itemObjectIdentifier",
339 "quantity": 8,
340 "unit": "ANN",
341 "unitPrice": 10.00,
342 "vatCategoryCode": "AE",
343 "vatRate": 10
344 },
345 {
346 "itemDescription": "Lorem ipsum dolor sit amet",
347 "amount": 0.01
348 }
349 ],
350 "invoiceVatSpecification": {
351 "vatSubTotal": [
352 {
353 "taxableAmount": 98.01,
354 "vatAmount": 0.00,
355 "vatRate": 1,
356 "vatCategoryCode": "Z"
357 }
358 ]
359 },
360 "taxCurrencyVatSpecification": {
361 "vatSubTotal": [
362 {
363 "taxableAmount": 50.00,
364 "vatAmount": 5.50,
365 "vatRate": 1.00,
366 "vatCategoryCode": "O"
367 }
368 ],
369 "taxCurrencyCode": "GBP",
370 "exchangeRate": 1.55
371 },
372 "taxReduction": {
373 "taxReductionDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
374 "taxReductionAmount": 10
375 }
376
377 },
378 "@id": "/ledger/invoice-service/v1/XXX/invoices/NNN"
379 }
380 {{/code}}
381
382
383 ==== Get single "create-invoice" request ====
384
385 {{code language="http" title="**Request**"}}
386 GET /ledger/invoice-service/v1/XXX/invoices/NNN HTTP/1.1
387 Host: -
388 Authorization: Bearer <Token>
389 Content-Type: application/json
390
391 {{/code}}
392
393 {{code language="http" title="**Response**"}}
394 HTTP/1.1 200 OK
395 Host: -
396 Authorization: Bearer <Token>
397 Content-Type: application/json
398
399 {
400 "customerNo" : "900",
401 "invoiceNo" : "0000001",
402 "invoiceDate": "2021-05-15",
403 "preferredDueDate": "2021-06-15",
404 "externalInvoiceId": "900001",
405 "currency": "SEK",
406 "invoiceAddress": {
407 "addressee": "Annie Testsson",
408 "streetAddress": "Teststreet 1",
409 "zipCode": "50000",
410 "city": "Testcity",
411 "coAddress": "CO Bengtsson",
412 "countryCode": "SE"
413 },
414 "distribution": null,
415 "invoiceReason": {
416 "invoiceReasonCode": "CAS",
417 "invoiceReasonDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
418 },
419 "legalMonetaryTotal": {
420 "payableAmount": 88.00,
421 "vatInclusiveAmount": 98.01,
422 "vatExclusiveAmount": 98.01
423 },
424 "referenceInfo": {
425 "invoicePeriod": {
426 "startDate": "2021-04-07",
427 "endDate": "2021-04-25"
428 },
429 "deliveryInfo": {
430 "deliveryDate": "2021-04-27",
431 "deliveryAddress": {
432 "addressee": "Namn på mottagre",
433 "streetAddress": "Testgatan 789",
434 "zipCode": "11111",
435 "city": "Sthlm",
436 "coAddress": "C/O Andersson",
437 "countryCode": "SE"
438 }
439 },
440 "purchaseOrderReference": "Lorem ipsum dolor sit amet",
441 "salesOrderReference": "Lorem ipsum dolor sit amet",
442 "buyerReference": "Lorem ipsum dolor sit amet",
443 "invoicedObjectIdentifier": "Lorem ipsum do",
444 "contractReference": "Lorem ipsum dolor sit amet",
445 "despatchReference": "Lorem ipsum dolor sit amet",
446 "receiptReference": "Lorem ipsum dolor sit amet",
447 "tenderReference": "Lorem ipsum dolor sit amet",
448 "projectReference": "Lorem ipsum dolor sit amet"
449 },
450 "InvoiceNote": "InvoiceNote-Text e Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, ",
451 "invoiceSpecification": {
452 "inclVat": true,
453 "roundingAmount": -0.01,
454 "invoiceLines": [
455 {
456 "itemDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
457 "amount": 98.00,
458 "datePeriod": {
459 "StartDate": "2021-04-21",
460 "EndDate": "2021-04-25"
461 },
462 "gTIN": "156789123",
463 "itemObjectIdentifier": "itemObjectIdentifier",
464 "quantity": 8,
465 "unit": "ANN",
466 "unitPrice": 10.00,
467 "vatCategoryCode": "AE",
468 "vatRate": 10
469 },
470 {
471 "itemDescription": "Lorem ipsum dolor sit amet",
472 "amount": 0.01
473 }
474 ],
475 "invoiceVatSpecification": {
476 "vatSubTotal": [
477 {
478 "taxableAmount": 98.01,
479 "vatAmount": 0.00,
480 "vatRate": 1,
481 "vatCategoryCode": "Z"
482 }
483 ]
484 },
485 "taxCurrencyVatSpecification": {
486 "vatSubTotal": [
487 {
488 "taxableAmount": 50.00,
489 "vatAmount": 5.50,
490 "vatRate": 1.00,
491 "vatCategoryCode": "O"
492 }
493 ],
494 "taxCurrencyCode": "GBP",
495 "exchangeRate": 1.55
496 },
497 "taxReduction": {
498 "taxReductionDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
499 "taxReductionAmount": 10
500 }
501
502 },
503 "@id": "/ledger/invoice-service/v1/XXX/invoices/NNN"
504 }
505 {{/code}}
506
507 ==== ====
508
509 (% id="HAccountresourceproperties" %)
510 ==== Invoice resource properties ====
511
512 (% class="box infomessage" %)
513 (((
514 For basic string properties, all characters included in "Basic Latin" and "Latin-1 Supplement" are generally supported unless otherwise stated in below table
515 )))
516
517 (% class="table-bordered table-striped" %)
518 |=(% style="width: 561.984px;" %)Property|=(% style="width: 1px;" %)Data type|=(% style="width: 213px;" %)Format|=(% style="width: 88px;" %)Required|=(% style="width: 792px;" %)Description
519 |(% style="width:561.984px" %)customerNo|(% style="width:1px" %)string|(% style="width:213px" %)MinLength: 1
520 MaxLength: 15*
521 numeric, 1-9 |(% style="width:88px" %)Yes|(% style="width:792px" %)The unique identifier of the customer
522 MaxLength may differ depending on configuration
523 KID (Norway)
524 |(% style="width:561.984px" %)(((
525 invoiceNo
526 )))|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 15
527 Regex pattern:(((
528 [A-Za-z0-9\-]+
529 )))|(% style="width:88px" %)Yes|(% style="width:792px" %)Your unique identifier/invoice number of the invoice
530 |(% style="width:561.984px" %)invoiceDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)Yes|(% style="width:792px" %)
531 |(% style="width:561.984px" %)**invoiceAddress**|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)(((
532 Optional invoice address. Only used if different from customer name and legal address
533 )))
534 |(% style="width:561.984px" %) addressee|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 72|(% style="width:88px" %)Yes|(% style="width:792px" %)Full name of addressee
535 |(% style="width:561.984px" %) streetAddress|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 72|(% style="width:88px" %)No|(% style="width:792px" %)Street address
536 |(% style="width:561.984px" %) zipCode|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 9|(% style="width:88px" %)Yes|(% style="width:792px" %)Zipcode conforming to country standard
537 |(% style="width:561.984px" %) city|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 27|(% style="width:88px" %)Yes|(% style="width:792px" %)City
538 |(% style="width:561.984px" %) coAddress|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 72|(% style="width:88px" %)No|(% style="width:792px" %)Care of address
539 |(% style="width:561.984px" %) countryCode|(% style="width:1px" %)string|(% style="width:213px" %)ISO 3166-1 alpha-2|(% style="width:88px" %)Yes|(% style="width:792px" %)Country code according to ISO 3166
540 |(% style="width:561.984px" %)preferredDueDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)No|(% style="width:792px" %)(((
541 Used if a specific duedate is preferred. Number of days between distributiondate, wich it set by PayEx based on invoicedate and processingdate, and preferred due date must exceed minimum payment terms for the specific country. Else minimum paymentterms for the country will be used. Number of days between distributiondate, which is set by PayEx based on invoicedate and processingdate, and preferred due date, can not exceed maximum paymentterms (default 60 days), if true an ERROR is created and the customer and its invoices will be rejected.
542 )))
543 |(% style="width:561.984px" %)externalInvoiceId|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50
544 Regex pattern:
545 ^[a-zA-Z0-9äåöÄÅÖ/_ -.]*$|(% style="width:88px" %)No|(% style="width:792px" %)Additional external unique invoice identfier in accountsreceivable
546 |(% style="width:561.984px" %)distribution|(% style="width:1px" %)string|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)(((
547 * **Postal**
548 * **Email**
549 * **EInvoiceB2B **//(some optional fields will be required if this is set*)//
550 * **ArchiveOnly **//(available 2023-04-19)//
551
552 If no distribution is set, [[default distribution priority >>doc:Main.Invoicing.invoice-service.invoice-service-apis.Invoice layout.WebHome||queryString="#HStandarddistributionorderofpriority"]]order will apply.
553 )))
554 |(% style="width:561.984px" %)currency|(% style="width:1px" %)string|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)Valid currency supported in Your accountsreceivable
555 |(% style="width:561.984px" %)(((
556 __**invoiceReason**__
557 )))|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)
558 |(% style="width:561.984px" %) invoiceReasonCode|(% style="width:1px" %)string|(% style="width:213px" %)[[UNCL7161>>https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL7161/]]|(% style="width:88px" %)No|(% style="width:792px" %)Invoice reason code according to format UNCL7161
559 |(% style="width:561.984px" %) invoiceReasonDescription|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 200
560 Regex pattern: ^[\u0020-\u003A \u003C-\u007E \u00A0-\u00FF]*$|(% style="width:88px" %)Yes|(% style="width:792px" %)Description of the reason for the invoice
561 |(% style="width:561.984px" %)(((
562 ==== __**legalMonetaryTotal**__ ====
563 )))|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)(((
564 Contains total amount and currency of the invoice. Positive amount is used for debit invoice. Negative amount is used for credit invoice
565 )))
566 |(% style="width:561.984px" %) PayableAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
567 Max size: 100000000
568 Min size: -100000000|(% style="width:88px" %)Yes|(% style="width:792px" %)Total amount to by payed. LegalMonetary.VatInclusiveAmount + Invoicespecification.Roundingamount - InvoiceSpecification.TaxReductionAmount
569 |(% style="width:561.984px" %) VatInclusiveAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
570 Max size: 100000000
571 Min size: -100000000|(% style="width:88px" %)Yes|(% style="width:792px" %)Total amount inclusive of Vat. Equals sum of InvoiceSpecification.InvoiceVatSpecification.VatSubTotal.TaxableAmount + VatAmount
572 |(% style="width:561.984px" %) VatExclusiveAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
573 Max size: 100000000
574 Min size: -100000000|(% style="width:88px" %)Yes|(% style="width:792px" %)Total amount exclusive of Vat. Equals sum of InvoiceSpecification.InvoiceVatSpecification.VatSubTotal.TaxableAmount
575 |(% style="width:561.984px" %)(((
576 ==== __**referenceInfo**__ ====
577 )))|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Containing invoice reference information
578 |(% style="width:561.984px" %)**__invoicePeriod__**|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Optional invoiceperiod. Used in EDI
579 |(% style="width:561.984px" %) startDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)Yes|(% style="width:792px" %)
580 |(% style="width:561.984px" %) endDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)Yes|(% style="width:792px" %)
581 |(% style="width:561.984px" %)**__deliveryInfo__**|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Optional deliveryinformation of product/service invoiced. Also used in EDI
582 |(% style="width:561.984px" %) deliveryDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)No|(% style="width:792px" %)
583 |(% style="width:561.984px" %)**__deliveryAddress__**|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)
584 |(% style="width:561.984px" %) addressee|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 72|(% style="width:88px" %)Yes|(% style="width:792px" %)
585 |(% style="width:561.984px" %) streetAddress|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 72|(% style="width:88px" %)No|(% style="width:792px" %)
586 |(% style="width:561.984px" %) zipCode|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 9|(% style="width:88px" %)Yes|(% style="width:792px" %)
587 |(% style="width:561.984px" %) city|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 27|(% style="width:88px" %)Yes|(% style="width:792px" %)
588 |(% style="width:561.984px" %) coAddress|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 72|(% style="width:88px" %)No|(% style="width:792px" %)
589 |(% style="width:561.984px" %) countryCode|(% style="width:1px" %)string|(% style="width:213px" %)ISO 3166-1 alpha-2|(% style="width:88px" %)Yes|(% style="width:792px" %)
590 |(% style="width:561.984px" %) purchaseOrderReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional unique purchase order reference issued by the Buyer. Used in EDI
591 |(% style="width:561.984px" %) salesOrderReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional sales order reference issued by Seller. Used in EDI
592 |(% style="width:561.984px" %) buyerReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional reference of who ordered the products/services. Example being the name of the person ordering, employee number or a code identifying this person or department/group. Your ref is often used for internal routing at recipient, and hence it is important to fill this element with the correct values according to the need of the recipient. Used in EDI
593 |(% style="width:561.984px" %) invoicedObjectIdentifier|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional identifier for an object on which the invoice is based, given by the Seller. Examples may be a subscription number, telephone number, meter point, vehicle, person etc., as applicable. Used in EDI
594 |(% style="width:561.984px" %) contractReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional reference to a purchase contract. Used in EDI
595 |(% style="width:561.984px" %) despatchReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional reference to a despatch advice. Used in EDI
596 |(% style="width:561.984px" %) receiptReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional reference to a receipt advice. Used in EDI
597 |(% style="width:561.984px" %) tenderReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional reference to the tenderer or lot, in most cases the Procurement Procedure Identifier. Used in EDI
598 |(% style="width:561.984px" %) projectReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional reference to a project. Used in EDI
599 |(% style="width:561.984px" %) debitInvoiceReferences|(% style="width:1px" %)list|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)If creditinvoice, optional reference to debit invoice. Used in EDI
600 |(% style="width:561.984px" %) debitInvoiceReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)Yes|(% style="width:792px" %)Reference to debit invoice
601 |(% style="width:561.984px" %)invoiceNote|(% style="width:1px" %)string|(% style="width:213px" %)(((
602 MaxLength: 250
603
604 Regex pattern: ^[\u0020-\u003A \u003C-\u007E \u00A0-\u00FF]*$
605 )))|(% style="width:88px" %)No|(% style="width:792px" %)A textual note that gives unstructured information that is relevant to the Invoice as a whole
606 |(% style="width:561.984px" %)(((
607 ==== __**invoiceSpecification**__ ====
608 )))|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)(((
609 Contains the specification of the invoice
610 )))
611 |(% style="width:561.984px" %) inclVat|(% style="width:1px" %)bool|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)If True, invoiceLine.amount must include Vat. If False, invoiceLine.amount must exclude Vat. EDI-distribution requires an excl vat InvoiceSpecification
612 | roundingAmount|decimal|Fraction digits: 2
613 Max size: 0.99
614 Min size: -0.99|No|Roundingamount +- 0.99
615 not affected by VAT
616 |(% style="width:561.984px" %)(((
617 **__invoiceLines__**
618 )))|(% style="width:1px" %)list|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)
619 |(% style="width:561.984px" %) itemDescription|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 250
620 |(% style="width:88px" %)Yes|(% style="width:792px" %)Mandatory description of the invoiced item/service
621 |(% style="width:561.984px" %) amount|(% style="width:1px" %)decimal|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)Mandatory amount rounded to two decimals. inclusive or exclusive of vat dependends of setting of the boolean attribute Invoicespecification.InclVat
622 //Sum of the amounts of all invoiceLines must equal to legalMonetaryTotal.VatInclusiveAmount or VatExclusiveAmount, depending on Invoicespecification.InclVat true/false.//
623 |(% style="width:561.984px" %)__**datePeriod**__|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Optional date/period
624 |(% style="width:561.984px" %) startDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)Yes|(% style="width:792px" %)
625 |(% style="width:561.984px" %) endDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)No|(% style="width:792px" %)
626 |(% style="width:561.984px" %) gtin|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 15|(% style="width:88px" %)No|(% style="width:792px" %)Optional global trade item identifier (GS1 GTIN)
627 |(% style="width:561.984px" %) itemObjectIdentifier|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional identifier for an object on which the invoiceitem is based, given by the Seller. Examples may be a subscription number, telephone number, meter point, vehicle, person etc., as applicable. Used in EDI
628 |(% style="width:561.984px" %) quantity|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 5
629 Max size: 100000000
630 Min size: -100000000|(% style="width:88px" %)No*|(% style="width:792px" %)//*This field is required if distribution is set to EInvoiceB2B//
631 Optional quantity with up to 5 decimals
632 |(% style="width:561.984px" %) unit|(% style="width:1px" %)string|(% style="width:213px" %)UNECERec20 |(% style="width:88px" %)No*|(% style="width:792px" %)(((
633 //*This field is required if distribution is set to EInvoiceB2B//
634 Optional unit of quantity according to UNECERec20 code list:
635
636 (((
637 * **C62 **//- Used for unit-less count (pcs)//
638 * **KGM **//- Kilogram//
639 * **GRM **//- Gram//
640 * **AD **//- Byte//
641 * **2P **//- Kilobyte//
642 * **4L **//- Megabyte//
643 * **E34 **//- Gigabyte//
644 * **E35 **//- Terabyte//
645 * **SEC **//- Seconds//
646 * **MIN **//- Minutes//
647 * **DAY**// - Day//
648 * **WEE**// - Week//
649 * **MON **//- Month//
650 * **ANN **//- Year//
651 * **DZN** – Dozen, A unit of count defining the number of units in multiples of 12.
652 * **KMT** – Kilometer
653 * **MTR** – Meter
654 * **DMT** – Decimeter
655 * **CMT** – Centimeter
656 * **MMT** – Millimeter
657 * **MTK** – Square meter
658 * **MTQ** – Cubic meter
659 * **LTR** – Liter
660 * **DLT** – Deciliter
661 * **CLT** – Centiliter
662 * **MLT** – Milliliter
663 * **TNE** – Tonne (metric ton)
664 * **HUR** – Hour
665 * **KWH** – Kilowatt hour
666 * **E48** – Service unit, A unit of count defining the number of service units (service unit: defined period / property / facility / utility of supply).
667 * **E51** – Job, A unit of count defining the number of jobs.
668 * **E53** – Test, A unit of count defining the number of tests.
669 * **IE** – Person, A unit of count defining the number of persons.
670 * **XPX** – Pallet
671 * **XPK** – Package
672 * **LS** – Lump sum
673 )))
674 )))
675 |(% style="width:561.984px" %) unitPrice|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 5
676 Max size: 100000000
677 Min size: 0|(% style="width:88px" %)No*|(% style="width:792px" %)//*This field is required if distribution is set to EInvoiceB2B//
678 Optional unitprice with up to 5 decimals. Inclusive or exclusive of vat dependent of setting of the boolean attribute Invoicespecification.InclVat
679 |(% style="width:561.984px" %) vatCategoryCode|(% style="width:1px" %)string|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Optional VatCategoryCode according to UN/CEFACT code list 5305, D.16B(((
680 * **AE **-// VAT Reverse Charge: Code specifying that the standard VAT rate is levied from the invoicee//
681 * **E **- //Exempt from tax: Code specifying that taxes are not applicable//
682 * **S **- //Standard rate: Code specifying the standard rate//
683 * **Z** - //Zero rated goods: Code specifying that the goods are at a zero rate//
684 * **G** - //Free export item, tax not charged: Code specifying that the item is free export and taxes are not charged//
685 * **O** - //Services outside scope of tax: Code specifying that taxes are not applicable to the services//
686 * **K** - //VAT exempt for EEA intra-community supply of goods and services. A tax category code indicating the item is VAT exempt due to an intra-community supply in the European Economic Area//
687 )))
688 |(% style="width:561.984px" %) vatRate|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
689 Max size: 100.00
690 Min size: 0.00|(% style="width:88px" %)No|(% style="width:792px" %)Optional valid VatRate
691 |(% style="width:561.984px" %)(((
692 **__invoiceVatSpecifications__**
693 )))|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)Is specified once per distinct combination of VatCategoryCode and VatRate. Each combination must match sum of corresponding InvoiceLines
694 |(% style="width:561.984px" %) vatSubTotal|(% style="width:1px" %)list|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)VatSubTotal is specified once per combination of VatCategoryCode and VatRate
695 |(% style="width:561.984px" %) taxableAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
696 Min size: -100000000
697 Max size: 100000000|(% style="width:88px" %)Yes|(% style="width:792px" %)
698 |(% style="width:561.984px" %) vatAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
699 Min size: -100000000
700 Max size: 100000000|(% style="width:88px" %)Yes|(% style="width:792px" %)
701 |(% style="width:561.984px" %) vatRate|(% style="width:1px" %)decimal|(% style="width:213px" %)percentage
702 min: 0.00
703 max: 100.00|(% style="width:88px" %)Yes|(% style="width:792px" %)vatRate in percentage
704 |(% style="width:561.984px" %) vatCategoryCode|(% style="width:1px" %)string|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)(((
705 Valid values:
706
707 * **AE **-// VAT Reverse Charge: Code specifying that the standard VAT rate is levied from the invoicee//
708 * **E **- //Exempt from tax: Code specifying that taxes are not applicable//
709 * **S **- //Standard rate: Code specifying the standard rate//
710 * **Z** - //Zero rated goods: Code specifying that the goods are at a zero rate//
711 * **G** - //Free export item, tax not charged: Code specifying that the item is free export and taxes are not charged//
712 * **O** - //Services outside scope of tax: Code specifying that taxes are not applicable to the services//
713 * **K** - //VAT exempt for EEA intra-community supply of goods and services. A tax category code indicating the item is VAT exempt due to an intra-community supply in the European Economic Area//
714 )))
715 |(% style="width:561.984px" %)(((
716 **__taxCurrencyVatSpecification__**
717 )))|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Used if seller tax currency is other than invoice currency
718 |(% style="width:561.984px" %)**vatSubTotal**|(% style="width:1px" %)list|(% style="width:213px" %)required 1-10 items|(% style="width:88px" %)Yes|(% style="width:792px" %)VatSubTotal is specified once per combination of VatCategoryCode and VatRate
719 |(% style="width:561.984px" %) taxableAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)amount|(% style="width:88px" %)Yes|(% style="width:792px" %)
720 |(% style="width:561.984px" %) vatAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)amount|(% style="width:88px" %)Yes|(% style="width:792px" %)
721 |(% style="width:561.984px" %) vatRate|(% style="width:1px" %)decimal|(% style="width:213px" %)percentage
722 min: 0.00
723 max: 100.00|(% style="width:88px" %)Yes|(% style="width:792px" %)vatRate in percentage
724 |(% style="width:561.984px" %) vatCategoryCode|(% style="width:1px" %)string|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)(((
725 Valid values:
726
727 * **AE **-// VAT Reverse Charge: Code specifying that the standard VAT rate is levied from the invoicee//
728 * **E **- //Exempt from tax: Code specifying that taxes are not applicable//
729 * **S **- //Standard rate: Code specifying the standard rate//
730 * **Z** - //Zero rated goods: Code specifying that the goods are at a zero rate//
731 * **G** - //Free export item, tax not charged: Code specifying that the item is free export and taxes are not charged//
732 * **O** - //Services outside scope of tax: Code specifying that taxes are not applicable to the services//
733 * **K** - //VAT exempt for EEA intra-community supply of goods and services. A tax category code indicating the item is VAT exempt due to an intra-community supply in the European Economic Area//
734 )))
735 |(% style="width:561.984px" %) taxCurrencyCode|(% style="width:1px" %)string|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)The tax currency code of the seller
736 |(% style="width:561.984px" %) exchangeRate|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 5
737 Min size: 0.00001|(% style="width:88px" %)Yes|(% style="width:792px" %)ExchangeRate used to calculate vat in seller tax currency
738 |(% style="width:561.984px" %)**__taxReduction__**|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Taxreduction used for Reversed Tax and ROT/RUT
739 |(% style="width:561.984px" %) taxReductionDescription|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 250|(% style="width:88px" %)Yes|(% style="width:792px" %)
740 |(% style="width:561.984px" %) taxReductionAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
741 Min size: 0,01
742 Max size: 100000000|(% style="width:88px" %)Yes|(% style="width:792px" %)
743
744 (% id="HBills" %)
745 == ==
746
747 (% id="H-1" %)
748 ==== Problems ====
749
750 All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
751 The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.
752 Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.
753
754 Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation
755
756 === Example ===
757
758 {{code language="http" title="**Response**"}}
759 HTTP/1.1 400 Error
760 Content-Type: application/problem+json
761
762 {
763 "Type" : "ledger/invoice-service/v1/problems/validation",
764 "Title" : "A validation error occurred",
765 "Status" : 400,
766 "Instance" : "215d4206-ca35-4f43-85ad-169c8f6d4ec1",
767 "Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
768 "Problems" : [
769 {
770 "amount" : "Expected value between [0,01]-[79228162514264337593543950335] actual [0]"
771 }
772 ]
773 }
774 {{/code}}
775
776 === Problem types ===
777
778 (% class="box infomessage" %)
779 (((
780 Note, each problem typecode is preceded by "ledger.invoice-service." in this API, e.g. the error "validation" in the table below will appear as typecode "ledger.invoice-service.validation".
781 )))
782
783 (% class="table-bordered table-striped" %)
784 |=(% style="width: 537px;" %)Problem type (code)|=(% style="width: 172px;" %)Httpstatus|=(% style="width: 796px;" %)Description
785 |(% style="width:537px" %)validation|(% style="width:172px" %)400|(% style="width:796px" %)occurs if any of the inputvalidation fails, it is described in the problem which parameter that failed the validation
786 |(% style="width:537px" %)invoice-not-found|(% style="width:172px" %)404|(% style="width:796px" %)