Changes for page 2. Customer

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