Changes for page 2. Customer

Last modified by Fredrik Nilsson on 2024/03/21 16:20
From empty
To version 105.1
edited by Fredrik Nilsson
on 2022/04/20 09:25
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +2. Customer
Parent
... ... @@ -1,0 +1,1 @@
1 +developer:Main.Invoicing.invoice-service.invoice-service-apis.Technical reference.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +xwiki:XWiki.frn
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Tags
... ... @@ -1,0 +1,1 @@
1 +px-custom-page-content
Content
... ... @@ -1,0 +1,792 @@
1 +(% class="jumbotron" %)
2 +(((
3 +(% class="container" %)
4 +(((
5 +Integrate to **PayEx Customer API **
6 +)))
7 +)))
8 +
9 +== Introduction ==
10 +
11 +(% class="lead" %)
12 +This api is used to create/read customers or change properties related to the customer.
13 +
14 +[[image:1612164561442-820.png||height="242" width="558"]]
15 +
16 +
17 +Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below
18 +
19 +The below route is an example of a route towards resource2Id, to operate on this resource you must also include the ids of its parentresources in the route.
20 +//api.payex.com/ledger/**{Subdomain}**/v1/**{LedgerNumber}**/resource1/**{resource1Id}**/resource2/**{resource2Id}**//
21 +
22 +(% class="table-bordered table-striped" %)
23 +|=(% style="width: 604px;" %)Route segment|=(% style="width: 2790px;" %)Description
24 +|(% style="width:604px" %)Subdomain|(% style="width:2790px" %)In this part of the API it will be **customer**
25 +|(% style="width:604px" %)LedgerNumber|(% style="width:2790px" %)The ledger identifier/number at PayEx
26 +|(% style="width:604px" %)resource1Id|(% style="width:2790px" %)Identifier of resource1
27 +|(% style="width:604px" %)resource2Id|(% style="width:2790px" %)identifier of resource2, subresource to resource1
28 +
29 +(% class="wikigeneratedid" %)
30 +Routes that occurs in examples of this documentation will use the following identifiers
31 +
32 +(% class="table-bordered table-striped" %)
33 +|=(% style="width: 488px;" %)Resource|=(% style="width: 2271px;" %)Identifier
34 +|(% style="width:488px" %)LedgerNumber|(% style="width:2271px" %)XXX
35 +|(% style="width:488px" %)Customer|(% style="width:2271px" %)NNN (CustomerNo)
36 +
37 +== Customer ==
38 +
39 +The **customer **resource is located under **ledger/customer/v1/ **api**. **The customer- and its sub-resources are used to create, read and modify information related to customers.
40 +
41 +==== (% style="color:inherit; font-family:inherit" %)Get a specific customer(%%) ====
42 +
43 +{{code language="http" title="**Request**"}}
44 +GET /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
45 +Host: -
46 +Authorization: Bearer <Token>
47 +Content-Type: application/json
48 +{{/code}}
49 +
50 +==== ====
51 +
52 +{{code language="http" title="**Response**"}}
53 +HTTP/1.1 200 OK
54 +Content-Type: application/json
55 +
56 +{
57 + "@id" : "/ledger/customer/v1/XXX/customers/9999",
58 + "customerNo" : "9999",
59 + "nationalIdentifier": {
60 + "regNo" : "YYYYMMDD-NNNN",
61 + "countryCode" : "SE"
62 + },
63 + "vatNo" : "SE101010101001",
64 + "legalEntity" : "consumer|business",
65 + "name" : "Britt-Marie Axelstopp",
66 + "emailAddress" : "britt@axelstopp.com",
67 + "msisdn" : "+91485918841",
68 + "eDIAddressInfo" : {
69 + "VAN": "ABCXYZ",
70 + "InterChangeRecipient": "Recipient_ID1",
71 + "BuyerId": "123465"
72 + },
73 + "legalAddress" : "/ledger/customer/v1/XXX/customers/9999/legal-address",
74 + "billingAddress" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
75 + "operations" :
76 + [
77 + {
78 + "rel" : "add-billing-address",
79 + "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
80 + "method" : "POST"
81 + }
82 + ]
83 +}
84 +{{/code}}
85 +
86 +==== Get a specific customer using $expand ====
87 +
88 +if the entire customer model is needed, you can expand property references to other resources, in this example to get the customer model including the addresses on a single call.
89 +
90 +(% class="box infomessage" %)
91 +(((
92 +Performance is affected when expand is used as more resources are retrieved. Only use $expand if you always need the referenced properties, otherwise it should be retrevied on demand.
93 +)))
94 +
95 +{{code language="http" title="**Request**"}}
96 +GET /ledger/customer/v1/XXX/customers/NNN?$expand=legal-address,billing-address HTTP/1.1
97 +Host: -
98 +Authorization: Bearer <Token>
99 +Content-Type: application/json
100 +{{/code}}
101 +
102 +
103 +{{code language="http" title="**Response**"}}
104 +HTTP/1.1 200 OK
105 +Content-Type: application/json
106 +
107 +{
108 + "@id" : "/ledger/customer/v1/XXX/customers/9999",
109 + "customerNo" : "9999",
110 + "nationalIdentifier": {
111 + "regNo" : "YYYYMMDD-NNNN",
112 + "countryCode" : "SE"
113 + },
114 + "vatNo" : "SE101010101001",
115 + "legalEntity" : "consumer|business",
116 + "name" : "Britt-Marie Axelstopp",
117 + "emailAddress" : "britt@axelstopp.com",
118 + "msisdn" : "+91485918841",
119 + "eDIAddressInfo" : {
120 + "VAN": "ABCXYZ",
121 + "InterChangeRecipient": "Recipient_ID1",
122 + "BuyerId": "123456"
123 + },
124 + "legalAddress" : {
125 + "addressee" : "Britt-Marie Axelstopp",
126 + "streetAddress" : "The street 18",
127 + "coAddress" : "c/o Jansson",
128 + "city" : "STOCKHOLM",
129 + "zipCode" : "15961",
130 + "countryCode" : "SE",
131 + "operations" :
132 + [
133 + {
134 + "rel" : "update",
135 + "href" : "/ledger/customer/v1/XXX/customers/9999/legal-address",
136 + "method" : "PUT"
137 + },
138 + {
139 + "rel" : "update-legal-address-from-population-register",
140 + "href" : "/ledger/customer/v1/XXX/customers/9999/legal-address",
141 + "method" : "POST"
142 + }
143 + ]
144 + },
145 + "billingAddress" : {
146 + "addressee" : "Kalle Axelstopp",
147 + "streetAddress" : "Axelgatan 18",
148 + "city" : "STOCKHOLM",
149 + "zipCode" : "16872",
150 + "countryCode" : "se",
151 + "operations" :
152 + [
153 + {
154 + "rel" : "update",
155 + "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
156 + "method" : "PUT"
157 + },
158 + {
159 + "rel" : "delete",
160 + "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
161 + "method" : "DELETE"
162 + }
163 + ]
164 + },
165 + "operations" :
166 + [
167 + {
168 + "rel" : "add-billing-address",
169 + "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
170 + "method" : "POST"
171 + }
172 + ]
173 +}
174 +{{/code}}
175 +
176 +
177 +----
178 +
179 +==== Create new customer ====
180 +
181 +
182 +(% id="HImportanttonote21" %)
183 +===== Important to note! =====
184 +
185 +* Standard length of CustomerNo in Norway and Denmark is 7 characters (numeric only).
186 +* Only use numeric characters for CustomerNo in Sweden, in order to use AutoGiro (Direct Debit).
187 +
188 +A new customer is created by making a POST call to the API.
189 +See below table of properties that is supported when creating a new customer. The table below also reflects what properties you can expect when retreiving a customer through a "GET" request.
190 +
191 +(% class="table-bordered table-striped" %)
192 +|=(% style="width: 509px;" %)Property|=(% style="width: 161px;" %)Required|=(% style="width: 1852px;" %)Comment *
193 +|(% style="width:509px" %)customerNo|(% style="width:161px" %)Yes*|(% style="width:1852px" %)Normally required, //exception is when the configuration on the ledger is set for payex to generate customer numbers, in that case CustomerNo must not be set in request.//
194 +|(% style="width:509px" %)__**nationalIdentifier**__|(% style="width:161px" %)No*|(% style="width:1852px" %)Normally optional, //exception is when the configuration on the ledger is set for payex to generate customer numbers, in that case nationalIdentifier is required.//
195 +|(% style="width:509px" %) nationalIdentifier.regNo|(% style="width:161px" %)Yes|(% style="width:1852px" %)
196 +|(% style="width:509px" %) nationalIdentifier.countryCode|(% style="width:161px" %)Yes|(% style="width:1852px" %)
197 +|(% style="width:509px" %)vatNo|(% style="width:161px" %)No*|(% style="width:1852px" %)Required if reverse tax is used
198 +|(% style="width:509px" %)legalEntity|(% style="width:161px" %)No|(% style="width:1852px" %)
199 +|(% style="width:509px" %)name|(% style="width:161px" %)Yes|(% style="width:1852px" %)
200 +|(% style="width:509px" %)emailAddress|(% style="width:161px" %)No|(% style="width:1852px" %)
201 +|(% style="width:509px" %)msisdn|(% style="width:161px" %)No|(% style="width:1852px" %)
202 +|(% style="width:509px" %)__**eDIAddressInfo**__|(% style="width:161px" %)No|(% style="width:1852px" %)
203 +|(% style="width:509px" %) eDIAddressInfo.van|(% style="width:161px" %)No|(% style="width:1852px" %)(((
204 +
205 +)))
206 +|(% style="width:509px" %) eDIAddressInfo.interChangeRecipient|(% style="width:161px" %)No|(% style="width:1852px" %)
207 +|(% style="width:509px" %) eDIAddressInfo.BuyerId|(% style="width:161px" %)Yes|(% style="width:1852px" %)
208 +|(% style="width:509px" %)**__legalAddress__**|(% style="width:161px" %)Yes|(% style="width:1852px" %)
209 +|(% style="width:183px" %) addressee|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
210 +|(% style="width:183px" %) streetAddress|(% style="width:1602px" %)No|(% style="width:1852px" %)
211 +|(% style="width:183px" %) coAddress|(% style="width:1602px" %)No|(% style="width:1852px" %)
212 +|(% style="width:183px" %) city|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
213 +|(% style="width:183px" %) zipCode|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
214 +|(% style="width:183px" %) countryCode|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
215 +|(% style="width:509px" %)**__billingAddress__**|(% style="width:161px" %)No|(% style="width:1852px" %)
216 +|(% style="width:183px" %) addressee|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
217 +|(% style="width:183px" %) streetAddress|(% style="width:1602px" %)No|(% style="width:1852px" %)
218 +|(% style="width:183px" %) coAddress|(% style="width:1602px" %)No|(% style="width:1852px" %)
219 +|(% style="width:183px" %) city|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
220 +|(% style="width:183px" %) zipCode|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
221 +|(% style="width:183px" %) countryCode|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
222 +
223 +===== Examples =====
224 +
225 +(% class="wikigeneratedid" %)
226 +Standard create customer
227 +
228 +{{code language="http" title="**Request**"}}
229 +POST /ledger/customer/v1/XXX/customers HTTP/1.1
230 +Host: -
231 +Authorization: Bearer <Token>
232 +Content-Type: application/json
233 +
234 +{
235 + "customerNo" : "9999",
236 + "nationalIdentifier": {
237 + "regNo" : "YYYYMMDD-NNNN",
238 + "countryCode" : "SE"
239 + },
240 + "vatNo" : "SE101010101001",
241 + "legalEntity" : "consumer|business",
242 + "name" : "Britt-Marie Axelstopp",
243 + "emailAddress" : "britt@axelstopp.com",
244 + "msisdn" : "+91485918841",
245 + "eDIAddressInfo" : {
246 + "VAN": "ABCXYZ",
247 + "InterChangeRecipient": "Recipient_ID1",
248 + "BuyerId": "123456"
249 + },
250 + "legalAddress" : {
251 + "addressee" : "Britt-Marie Axelstopp",
252 + "streetAddress" : "The street 18",
253 + "coAddress" : "c/o Jansson",
254 + "city" : "STOCKHOLM",
255 + "zipCode" : "15961",
256 + "countryCode" : "SE"
257 + }
258 +}
259 +{{/code}}
260 +
261 +(% id="HAccountresourceproperties" %)
262 +==== ====
263 +
264 +{{code language="http" title="**Response**"}}
265 +HTTP/1.1 201 CREATED
266 +Content-Type: application/json
267 +
268 +{
269 + "@id" : "/ledger/customer/v1/XXX/customers/9999",
270 + "customerNo" : " 9999"
271 +}
272 +{{/code}}
273 +
274 +(% class="wikigeneratedid" id="HCreatecustomerwithbilling-address" %)
275 +Create customer with billing-address
276 +
277 +{{code language="http" title="**Request**"}}
278 +POST /ledger/customer/v1/XXX/customers HTTP/1.1
279 +Host: -
280 +Authorization: Bearer <Token>
281 +Content-Type: application/json
282 +
283 +{
284 + "customerNo" : "9999",
285 + "nationalIdentifier": {
286 + "regNo" : "YYYYMMDD-NNNN",
287 + "countryCode" : "SE"
288 + },
289 + "vatNo" : "SE101010101001",
290 + "legalEntity" : "consumer|business",
291 + "name" : "Britt-Marie Axelstopp",
292 + "emailAddress" : "britt@axelstopp.com",
293 + "msisdn" : "+91485918841",
294 + "eDIAddressInfo" : {
295 + "VAN": "ABCXYZ",
296 + "InterChangeRecipient": "Recipient_ID1",
297 + "BuyerId": "123456"
298 + },
299 + "legalAddress" : {
300 + "addressee" : "Britt-Marie Axelstopp",
301 + "streetAddress" : "The street 18",
302 + "coAddress" : "c/o Jansson",
303 + "city" : "STOCKHOLM",
304 + "zipCode" : "15961",
305 + "countryCode" : "SE"
306 + },
307 + "billingAddress" : {
308 + "addressee" : "Kalle Axelstopp",
309 + "streetAddress" : "Axelgatan 18",
310 + "city" : "STOCKHOLM",
311 + "zipCode" : "16872",
312 + "countryCode" : "SE"
313 + }
314 +}
315 +{{/code}}
316 +
317 +(% id="HAccountresourceproperties" %)
318 +==== ====
319 +
320 +{{code language="http" title="**Response**"}}
321 +HTTP/1.1 201 CREATED
322 +Content-Type: application/json
323 +
324 +{
325 + "@id" : "/ledger/customer/v1/XXX/customers/9999",
326 + "customerNo" : " 9999"
327 +}
328 +{{/code}}
329 +
330 +==== ====
331 +
332 +----
333 +
334 +==== Update customer ====
335 +
336 +Some properties of the customer can be updated through this API. Properties will only be updated if included in the request. //To delete a property, for example, the property must be included in the request and have the value set to null (see examples below). //
337 +
338 +The following customer properties is possible to update through a patch call
339 +
340 +(% class="table-bordered table-striped" %)
341 +|=(% style="width: 509px;" %)Property
342 +|(% style="width:509px" %)emailAddress
343 +|(% style="width:509px" %)msisdn
344 +|(% style="width:509px" %)__**eDIAddressInfo**__
345 +|(% style="width:509px" %) eDIAddressInfo.van
346 +|(% style="width:509px" %) eDIAddressInfo.interChangeRecipient
347 +|(% style="width:509px" %) eDIAddressInfo.BuyerId
348 +
349 +===== Examples =====
350 +
351 +Update all properties
352 +
353 +{{code language="http" title="**Request**"}}
354 +PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
355 +Host: -
356 +Authorization: Bearer <Token>
357 +Content-Type: application/json
358 +
359 +{
360 + "emailAddress" : "britt@axelstopp.com",
361 + "msisdn" : "+91485918841",
362 + "eDIAddressInfo" : {
363 + "VAN": "ABCXYZ",
364 + "InterChangeRecipient": "Recipient_ID1",
365 + "BuyerId": "123456"
366 + },
367 +}
368 +{{/code}}
369 +
370 +Update only emailAddress
371 +
372 +{{code language="http" title="**Request**"}}
373 +PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
374 +Host: -
375 +Authorization: Bearer <Token>
376 +Content-Type: application/json
377 +
378 +{
379 + "emailAddress" : "britt@axelstopp.com"
380 +}
381 +{{/code}}
382 +
383 +Update emailAddress and delete msisdn
384 +
385 +{{code language="http" title="**Request**"}}
386 +PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
387 +Host: -
388 +Authorization: Bearer <Token>
389 +Content-Type: application/json
390 +
391 +{
392 + "emailAddress" : "britt@axelstopp.com",
393 + "msisdn" : null
394 +}
395 +{{/code}}
396 +
397 +----
398 +
399 +(% id="HAccountresourceproperties" %)
400 +==== Customer resource properties ====
401 +
402 +(% class="table-bordered table-striped" %)
403 +|=(% style="width: 343px;" %)Property|=(% style="width: 137px;" %)Data type|=(% style="width: 230px;" %)Format|=(% style="width: 1076px;" %)Description
404 +|(% style="width:343px" %)@id |(% style="width:137px" %)string|(% style="width:230px" %) |(% style="width:1076px" %)Uri of the specific customer
405 +|(% style="width:343px" %)customerNo|(% style="width:137px" %)string|(% style="width:230px" %)MinLength: 1
406 +MaxLength: 15*
407 +numeric, 1-9 |(% style="width:1076px" %)The unique identifier of the customer
408 +MaxLength may differ depending on configuration
409 +KID (Norway)
410 +|(% style="width:343px" %)__**nationalIdentifier**__|(% style="width:137px" %)object|(% style="width:230px" %) |(% style="width:1076px" %)
411 +|(% style="width:343px" %) nationalIdentifier.regNo|(% style="width:137px" %)string|(% style="width:230px" %)Country specific|(% style="width:1076px" %)Sweden: YYYYMMDD-NNNC
412 +Norway: DDMMYYNNNNN
413 +|(% style="width:343px" %) nationalIdentifier.countryCode|(% style="width:137px" %)string|(% style="width:230px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:1076px" %)
414 +|(% style="width:343px" %)vatNo|(% style="width:137px" %)string|(% style="width:230px" %)MinLength: 7
415 +MaxLength: 17
416 +Regex pattern:
417 +[A-Z]{2}.*|(% style="width:1076px" %)Customer VAT registration number. Mandatory if reverse tax is used. Must conform to country specific algorithm
418 +|(% style="width:343px" %)legalEntity|(% style="width:137px" %)string|(% style="width:230px" %) |(% style="width:1076px" %)valid values:
419 +"consumer"
420 +"business"
421 +|(% style="width:343px" %)name|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 72
422 +Regex?|(% style="width:1076px" %)Full name of end-customer
423 +|(% style="width:343px" %)emailAddress|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 254
424 +Regex pattern: [^@]+@[^\.]+\..+|(% style="width:1076px" %)
425 +|(% style="width:343px" %)msisdn|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 15
426 +Minlength: 5
427 ++NNNN|(% style="width:1076px" %) "Mobile Subscriber Integrated Services Digital Network Number", ie. Cellphone number
428 +Countrycode is always required as the example below
429 ++46720000000
430 +|(% style="width:343px" %)__**eDIAddressInfo**__|(% style="width:137px" %)object|(% style="width:230px" %) |(% style="width:1076px" %)EDI addressing info
431 +|(% style="width:343px" %) eDIAddressInfo.van|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 255|(% style="width:1076px" %)(((
432 +Buyer VAN identifier (OperatorId)
433 +)))
434 +|(% style="width:343px" %) eDIAddressInfo.interChangeRecipient|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 13|(% style="width:1076px" %)Routing address. EAN
435 +|(% style="width:343px" %) eDIAddressInfo.BuyerId|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 13|(% style="width:1076px" %)NAD_BY/Buyerparty. EAN/Corporate identity number
436 +|(% style="width:343px" %)legalAddress|(% style="width:137px" %)uri|(% style="width:230px" %) |(% style="width:1076px" %)reference to the customers legal address
437 +|(% style="width:343px" %)billingAddress|(% style="width:137px" %)uri|(% style="width:230px" %) |(% style="width:1076px" %)reference to the customer billing address
438 +
439 +==== Operations ====
440 +
441 +Depending on the current permissions the following operations is supported on the customer resource
442 +
443 +===== add-billing-address =====
444 +
445 +Method: POST
446 +This operation will be available if no billing-address exists on the customer, see [[billing-address>>Main.Invoicing.invoice-service.Implementation guide.Technical reference.API.CustomerApi.WebHome||anchor="HAddabilling-address"]] resource for more details
447 +
448 +----
449 +
450 +== Legal-address ==
451 +
452 +The legal address is where claims is normally sent to. It is required for a customer to have a legal address registered
453 +
454 +==== Get the legal address of the customer ====
455 +
456 +{{code language="http" title="**Request**"}}
457 +GET /ledger/customer/v1/XXX/customers/NNN/legal-address HTTP/1.1
458 +Host: -
459 +Authorization: Bearer <Token>
460 +Content-Type: application/json
461 +{{/code}}
462 +
463 +
464 +{{code language="http" title="**Response**"}}
465 +HTTP/1.1 200 OK
466 +Content-Type: application/json
467 +
468 +{
469 + "addressee" : "Britt-Marie Axelstopp",
470 + "streetAddress" : "The street 18",
471 + "coAddress" : "c/o Jansson",
472 + "city" : "STOCKHOLM",
473 + "zipCode" : "15961",
474 + "countryCode" : "SE",
475 + "operations" :
476 + [
477 + {
478 + "rel" : "update",
479 + "href" : "/ledger/customer/v1/XXX/customers/9999/legal-address",
480 + "method" : "PUT"
481 + },
482 + {
483 + "rel" : "update-legal-address-from-population-register",
484 + "href" : "/ledger/customer/v1/XXX/customers/9999/legal-address/update-legal-address-from-population-register",
485 + "method" : "POST"
486 + }
487 + ]
488 +}
489 +{{/code}}
490 +
491 +==== Operations ====
492 +
493 +Depending on the current permissions the following operations is supported on the legal address resource
494 +
495 +===== Update (replace) =====
496 +
497 +Method: PUT
498 +Use this operation to update the address, this "PUT" operation will replace the existing billing-address with the address specified in the request body.
499 +
500 +(% class="table-bordered table-striped" %)
501 +|=(% style="width: 183px;" %)Property|=(% style="width: 1602px;" %)Required
502 +|(% style="width:183px" %)addressee|(% style="width:1602px" %)Yes
503 +|(% style="width:183px" %)streetAddress|(% style="width:1602px" %)No
504 +|(% style="width:183px" %)coAddress|(% style="width:1602px" %)No
505 +|(% style="width:183px" %)city|(% style="width:1602px" %)Yes
506 +|(% style="width:183px" %)zipCode|(% style="width:1602px" %)Yes
507 +|(% style="width:183px" %)countryCode|(% style="width:1602px" %)Yes
508 +
509 +Example
510 +
511 +{{code language="http" title="**Request**"}}
512 +PUT /ledger/customer/v1/XXX/customers/NNN/legal-address HTTP/1.1
513 +Host: -
514 +Authorization: Bearer <Token>
515 +Content-Type: application/json
516 +
517 +{
518 + "addressee" : "Kalle Axelstopp",
519 + "streetAddress" : "Axelgatan 18",
520 + "city" : "STOCKHOLM",
521 + "zipCode" : "16872",
522 + "countryCode" : "SE"
523 +}
524 +{{/code}}
525 +
526 +
527 +----
528 +
529 +===== update-legal-address-from-population-register =====
530 +
531 +Method: POST
532 +Execution of this operation will result in an attempt to retrieve (and replace) the customer's legal address from the population registry.
533 +
534 +(% class="box infomessage" %)
535 +(((
536 +Access to this operation is not normally granted, unless otherwise agreed.
537 +)))
538 +
539 +{{code language="http" title="**Request**"}}
540 +POST /ledger/customer/v1/XXX/customers/NNN/legal-address/update-legal-address-from-population-register HTTP/1.1
541 +Host: -
542 +Authorization: Bearer <Token>
543 +Content-Type: application/json
544 +
545 +{
546 +}
547 +{{/code}}
548 +
549 +----
550 +
551 +==== Legal-address resource properties ====
552 +
553 +(% class="table-bordered table-striped" %)
554 +|=(% style="width: 161px;" %)Property|=(% style="width: 121px;" %)Data type|=(% style="width: 195px;" %)Format|=(% style="width: 1309px;" %)Description
555 +|(% style="width:161px" %)addressee|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 72|(% style="width:1309px" %)Fullname
556 +|(% style="width:161px" %)streetAddress|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 35|(% style="width:1309px" %)
557 +|(% style="width:161px" %)coAddress|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 35|(% style="width:1309px" %)Care of (C/O) name. This is optional.
558 +|(% style="width:161px" %)city|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 30|(% style="width:1309px" %)
559 +|(% style="width:161px" %)zipCode|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 9|(% style="width:1309px" %)ZipCode without whitespaces
560 +|(% style="width:161px" %)countryCode|(% style="width:121px" %)string|(% style="width:195px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:1309px" %)
561 +
562 +----
563 +
564 +== Billing-address ==
565 +
566 +The billing address is where invoices/bills/letters etc. is normally sent to.This address is optional
567 +
568 +==== Get the billing address of the customer ====
569 +
570 +{{code language="http" title="**Request**"}}
571 +GET /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
572 +Host: -
573 +Authorization: Bearer <Token>
574 +Content-Type: application/json
575 +{{/code}}
576 +
577 +
578 +{{code language="http" title="**Response**"}}
579 +HTTP/1.1 200 OK
580 +Content-Type: application/json
581 +
582 +{
583 + "addressee" : "Kalle Axelstopp",
584 + "streetAddress" : "Axelgatan 18",
585 + "coAddress" : "c/o Jansson",
586 + "city" : "STOCKHOLM",
587 + "zipCode" : "16872",
588 + "countryCode" : "SE",
589 + "operations" :
590 + [
591 + {
592 + "rel" : "update",
593 + "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
594 + "method" : "PUT"
595 + },
596 + {
597 + "rel" : "delete",
598 + "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
599 + "method" : "DELETE"
600 + }
601 + ]
602 +}
603 +{{/code}}
604 +
605 +==== Add a billing-address ====
606 +
607 +(% class="table-bordered table-striped" %)
608 +|=(% style="width: 183px;" %)Property|=(% style="width: 1602px;" %)Required
609 +|(% style="width:183px" %)addressee|(% style="width:1602px" %)Yes
610 +|(% style="width:183px" %)streetAddress|(% style="width:1602px" %)No
611 +|(% style="width:183px" %)coAddress|(% style="width:1602px" %)No
612 +|(% style="width:183px" %)city|(% style="width:1602px" %)Yes
613 +|(% style="width:183px" %)zipCode|(% style="width:1602px" %)Yes
614 +|(% style="width:183px" %)countryCode|(% style="width:1602px" %)Yes
615 +
616 +{{code language="http" title="**Request**"}}
617 +POST /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
618 +Host: -
619 +Authorization: Bearer <Token>
620 +Content-Type: application/json
621 +
622 +{
623 + "addressee" : "Kalle Axelstopp",
624 + "streetAddress" : "Axelgatan 18",
625 + "city" : "STOCKHOLM",
626 + "zipCode" : "16872",
627 + "countryCode" : "SE"
628 +}
629 +{{/code}}
630 +
631 +==== Operations ====
632 +
633 +Depending on the current permissions the following operations is supported on the billing address resource
634 +
635 +===== Update (replace) =====
636 +
637 +Method: PUT
638 +Use this operation to update the address, the "PUT" body of the request should be accoring to the properties of the resource.
639 +
640 +(% class="table-bordered table-striped" %)
641 +|=(% style="width: 183px;" %)Property|=(% style="width: 1602px;" %)Required
642 +|(% style="width:183px" %)addressee|(% style="width:1602px" %)Yes
643 +|(% style="width:183px" %)streetAddress|(% style="width:1602px" %)No
644 +|(% style="width:183px" %)coAddress|(% style="width:1602px" %)No
645 +|(% style="width:183px" %)city|(% style="width:1602px" %)Yes
646 +|(% style="width:183px" %)zipCode|(% style="width:1602px" %)Yes
647 +|(% style="width:183px" %)countryCode|(% style="width:1602px" %)Yes
648 +
649 +{{code language="http" title="**Request**"}}
650 +PUT /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
651 +Host: -
652 +Authorization: Bearer <Token>
653 +Content-Type: application/json
654 +
655 +{
656 + "addressee" : "Kalle Axelstopp",
657 + "streetAddress" : "Axelgatan 18",
658 + "city" : "STOCKHOLM",
659 + "zipCode" : "16872",
660 + "countryCode" : "SE"
661 +}
662 +{{/code}}
663 +
664 +===== Delete =====
665 +
666 +Method: DELETE
667 +Use this operation to delete the billing address.
668 +
669 +{{code language="http" title="**Request**"}}
670 +DELETE /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
671 +Host: -
672 +Authorization: Bearer <Token>
673 +Content-Type: application/json
674 +
675 +{
676 +}
677 +{{/code}}
678 +
679 +==== Billing-address resource properties ====
680 +
681 +(% class="table-bordered table-striped" %)
682 +|=Property|=(% style="width: 94px;" %)Data type|=(% style="width: 255px;" %)Format|=(% style="width: 1053px;" %)Description
683 +|addressee|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 72|(% style="width:1053px" %)Fullname
684 +|streetAddress|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 35|(% style="width:1053px" %)
685 +|coAddress|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 35|(% style="width:1053px" %)Care of (C/O) name. This is optional.
686 +|city|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 30|(% style="width:1053px" %)
687 +|zipCode|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 9|(% style="width:1053px" %)ZipCode without whitespaces
688 +|countryCode|(% style="width:94px" %)string|(% style="width:255px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:1053px" %)
689 +
690 +----
691 +
692 +== Generate customer ==
693 +
694 +The **generate consumer customer by reg no **resource is located under **ledger/customer/v1/ **api**. **It is used to genarate a customer with a nationalIdentifier. It will retreive an legal address from the population register and create a consumer customer.
695 +
696 +(% class="box infomessage" %)
697 +(((
698 +Access to this operation is not normally granted, unless otherwise agreed.
699 +)))
700 +
701 +(% class="table-bordered table-striped" %)
702 +|=(% style="width: 222px;" %)Property|=(% style="width: 1562px;" %)Required
703 +|(% style="width:222px" %)customerNo|(% style="width:1562px" %)No
704 +|(% style="width:222px" %)nationalIdentifier.regNo|(% style="width:1562px" %)Yes
705 +|(% style="width:222px" %)nationalIdentifier.countryCode|(% style="width:1562px" %)Yes
706 +|(% style="width:222px" %)emailAddress|(% style="width:1562px" %)No
707 +|(% style="width:222px" %)msisdn|(% style="width:1562px" %)No
708 +
709 +{{code language="http" title="**Request**"}}
710 +POST /ledger/customer/v1/XXX/generate-consumer-customer-by-reg-no HTTP/1.1
711 +Host: -
712 +Authorization: Bearer <Token>
713 +Content-Type: application/json
714 +
715 +{
716 + "nationalIdentifier": {
717 + "regNo" : "YYYYMMDD-NNNN",
718 + "countryCode" : "SE"
719 + },
720 + "emailAddress" : "britt@axelstopp.com",
721 + "msisdn" : "+91485918841"
722 +}
723 +{{/code}}
724 +
725 +{{code language="http" title="**Response**"}}
726 +HTTP/1.1 201 CREATED
727 +Content-Type: application/json
728 +
729 +{
730 + "@id" : "/ledger/customer/v1/XXX/customers/9999",
731 + "customerNo" : " 9999"
732 +}
733 +{{/code}}
734 +
735 +(% id="HAccountresourceproperties" %)
736 +==== Generate customer resource properties ====
737 +
738 +(% class="table-bordered table-striped" %)
739 +|=(% style="width: 248px;" %)Property|=(% style="width: 108px;" %)Data type|=(% style="width: 233px;" %)Format|=(% style="width: 1196px;" %)Description
740 +|(% style="width:248px" %)@id |(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: |(% style="width:1196px" %)Uri of the specific customer
741 +|(% style="width:248px" %)customerNo|(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: 15|(% style="width:1196px" %)
742 +|(% style="width:248px" %)nationalIdentifier.regNo|(% style="width:108px" %)string|(% style="width:233px" %)Country specific|(% style="width:1196px" %)Sweden: YYYYMMDD-NNNC
743 +Norway: DDMMYYNNNNN
744 +|(% style="width:248px" %)nationalIdentifier.countryCode|(% style="width:108px" %)string|(% style="width:233px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:1196px" %)
745 +|(% style="width:248px" %)emailAddress|(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: 254
746 +Regex pattern: [^@]+@[^\.]+\..+|(% style="width:1196px" %)
747 +|(% style="width:248px" %)msisdn|(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: 15|(% style="width:1196px" %) "Mobile Subscriber Integrated Services Digital Network Number", ie. Cellphone number
748 ++46720000000
749 +
750 +(% id="HBills" %)
751 +== Problems ==
752 +
753 +All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
754 +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.
755 +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.
756 +
757 +Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation
758 +
759 +=== Example ===
760 +
761 +{{code language="http" title="**Response**"}}
762 +HTTP/1.1 400 Error
763 +Content-Type: application/problem+json
764 +
765 +{
766 + "Type" : "ledger/customer/v1/problems/validation",
767 + "Title" : "A validation error occurred",
768 + "Status" : 400,
769 + "Instance" : "215d4206-ca35-4f43-85ad-169c8f6d4ec1",
770 + "Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
771 + "Problems" : [
772 + {
773 + "amount" : "Expected value between [0,01]-[79228162514264337593543950335] actual [0]"
774 + }
775 + ]
776 +}
777 +{{/code}}
778 +
779 +=== Problem types ===
780 +
781 +(% class="box infomessage" %)
782 +(((
783 +Note, each problem typecode is preceded by "ledger.customer." in this API, e.g. the error "validation" in the table below will appear as typecode "ledger.customer.validation".
784 +)))
785 +
786 +(% class="table-bordered table-striped" %)
787 +|=(% style="width: 537px;" %)Problem type (code)|=(% style="width: 172px;" %)Httpstatus|=(% style="width: 796px;" %)Description
788 +|(% 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
789 +|(% style="width:537px" %)forbidden|(% style="width:172px" %)403|(% style="width:796px" %)occurs if access to method is not allowed.
790 +|(% style="width:537px" %)customer-does-not-exists|(% style="width:172px" %)404|(% style="width:796px" %)specified customer number does not exists
791 +|(% style="width:537px" %)legal-address-does-not-exists|(% style="width:172px" %)404|(% style="width:796px" %)legal address does not exists for the specified customer
792 +|(% style="width:537px" %)billing-address-does-not-exists|(% style="width:172px" %)404|(% style="width:796px" %)billing address does not exists for the specified customer
1612164530151-211.png
Author
... ... @@ -1,0 +1,1 @@
1 +xwiki:XWiki.dap
Size
... ... @@ -1,0 +1,1 @@
1 +0 bytes
Content
1612164561442-820.png
Author
... ... @@ -1,0 +1,1 @@
1 +xwiki:XWiki.dap
Size
... ... @@ -1,0 +1,1 @@
1 +0 bytes
Content