Changes for page 2. Customer

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