= Customers resource methods =
== Customer creation (POST) ==
To create a new customer the client needs to send a HTTP <code>POST</code> request on the customer collection resource URI <code>https://api.example.com/v1/customers</code> (also see [[Application_Programming_Interface_(API)#Base_URI|Base URI]]), including the associated customer informationsinformation.The service will generate a new customer and responds with a HTTP status code <code>201</code> (Created) on success. The newly created customer URI is returned within the HTTP location header, which can be used by the client to gather informations information about the new customer.
We have two types of customers:* '''Company customer''': where we actually have a proper company or business name.* '''Private customer''': where we have the given name and the surname of the customer. === Company customer Customer creation request message ===
{| class="wikitable sortable" style="width: 100%;"
|-
|-
| [[#Compnay_customer_creation_request_message_bodyCustomer_creation_request_message_body|Request body]]
| JSON object
| <source lang="javascript">{ ... }</source>
|}
==== Company customer Customer creation request message body ====
{| class="wikitable sortable" style="width: 100%;" id="customer_object"
|-
|string
|yes
|The customer's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|UTF-8 {64}
|
|
|<source lang="javascript">"customerName": "Super-duper Hosting"</source> |-|<code>id</code>|integer|yes|The identification number the newly created customer resource should belong toCustomer Ltd.||@TODO add regex||<source lang="javascript">"belongsToResellerID": 4000001</source>
|-
|object
|yes
|An object holding the billing address informations information for the given customer. Refer to the [[#billingAddress_object|billingAddress object table]] for more informationsinformation.
|
|
|object
|no
|An object holding the shipping address informations information for the given customer. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informationsinformation.
|
|
</source>
|}
{| class="wikitable sortable" style="width: 100%;" id="billingAddress_object"
|-
|+ align="top" style="text-align:left;"|billingAddress Object!Parameter name!Data type!Mandatory!Description!Valid content![http://www.pcre.org/ PCRE]!Default value!Example |-|<code>organizationNameexternalID</code>
|string
|no
|The name of An optional external ID the organizationcustomer belongs to (is used for the mapping to external databases).
|
|@TODO: Add add regex
|
|<source lang="javascript">"organizationNameexternalID": "Customer Ltd."12345</source>
|-
|<code>gender</code>|string|yes|The gender of the address holder|Either <code>f</code> for female, <code>m</code> for male or <code>n</code> for neutral.|||<source lang="javascript">"gender": "f"</source> |-|<code>givenName</code>|string|yes|The given name (first name or forename) of the address holder.|UTF-8 {64}|@TODO: Add regex||<source lang="javascript">"givenName": "Name"</source> |-|<code>surname</code>|string|yes|The surname (last name or family name) of the address holder.|UTF-8 {64} |@TODO: Add regex||<source lang="javascript">"surname": "Surname"</source> |-|<code>postalAddress</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"postalAddress": ""</source> |-|<code>countryCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"countryCode": ""</source> |-|<code>postalCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"postalCode": ""</source> |-|<code>localityName</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"localityName": ""</source> |-|<code>preferredLanguage</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"preferredLanguage": ""</source> |-|<code>mail</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"mail": ""</source> |-|<code>telephoneNumber</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"telephoneNumber": ""</source> |-|<code>mobileTelephoneNumber</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"mobileTelephoneNumber": ""</source> |-|<code>websiteURL</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"websiteURL": ""</source> |} {| class="wikitable sortable" style="width: 100%;" id="shippingAddress_object"|-|+ align="top" style="text-align:left;"|shippingAddress Object!Parameter name!Data type!Mandatory!Description!Valid content![http://www.pcre.org/ PCRE]!Default value!Example |-|<code>organizationName</code>|string|no|The name of the organization.||@TODO: Add regex||<source lang="javascript">"organizationName": "Customer Ltd."</source> |-|<code>gender</code>|string|yes|The gender of the address holder|Either <code>f</code> for female, <code>m</code> for male or <code>n</code> for neutral.|||<source lang="javascript">"gender": "f"</source> |-|<code>givenName</code>|string|yes|The given name (first name or forename) of the address holder.||@TODO: Add regex||<source lang="javascript">"givenName": "Name"</source> |-|<code>surname</code>|string|yes|The surname (last name or family name) of the address holder.||@TODO: Add regex||<source lang="javascript">"surname": "Surname"</source> |-|<code>postalAddress</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"postalAddress": ""</source> |-|<code>countryCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"countryCode": ""</source> |-|<code>postalCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"postalCode": ""</source> |-|<code>localityName</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"localityName": ""</source> |-|<code>preferredLanguage</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"preferredLanguage": ""</source> |-|<code>mail</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"mail": ""</source> |-|<code>telephoneNumber</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"telephoneNumber": ""</source> |-|<code>mobileTelephoneNumber</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"mobileTelephoneNumber": ""</source> |-|<code>websiteURL</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"websiteURL": ""</source> |} ==== Customer creation request message body (Private Customer) ===={| class="wikitable sortable" style="width: 100%;" id="customer_object"|-|+ align="top" style="text-align:left;"|Customer Object! Parameter name! Data type! Mandatory! Description! Valid content![http://www.pcre.org/ PCRE]! Default value! Example |-|<code>isCompany</code>|boolean|yes|<code>true</code> if the customer represents a company, <code>false</code> if it's an individual person.|<code>true</code> or <code>false</code>|||<source lang="javascript">"isCompany": false</source> |-|<code>isActive</code>|boolean|yes||<code>true</code> or <code>false</code>||<code>true</code>|<source lang="javascript">"isActive": true</source> |-|<code>customerName</code>|string|yes|The customer's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.|UTF-8 {64}|||<source lang="javascript">"customerName": "Name Surname"</source> |-|<code>idbelongsToResellerID</code>
|integer
|yes
|The reseller identification number the newly created customer resource should must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"belongsToResellerID": 4000001</source> |-|[[#billingAddress_object|<code>billingAddress</code>]]|object|yes|An object holding the billing address informations for the given customer. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.||||<source lang="javascript">"billingAddress":{ "gender": 'm', "givenName": "Name", "surname": "Surname", "postalAddress": "Street Number", "countryCode": "CH", "postalCode": "1234", "localityName": "Locality", "preferredLanguage": "en-GB", "mail": "name.surname@example.com", "telephoneNumber": "+41 00 000 00 00", "mobileTelephoneNumber": "+41 00 000 00 00", "websiteURL": "https://www.example.com/"}</source> |-|[[#shippingAddress_object|<code>shippingAddress</code>]]|object|no|An object holding the shipping address informations for the given customer. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.||||<source lang="javascript">"shippingAddress":{ "gender": 'm', "givenName": "Name", "surname": "Surname", "postalAddress": "Street Number", "countryCode": "CH", "postalCode": "1234", "localityName": "Locality", "preferredLanguage": "en-GB", "mail": "name.surname@example.com", "telephoneNumber": "+41 00 000 00 00", "mobileTelephoneNumber": "+41 00 000 00 00", "websiteURL": "https://www.example.com/"}4000000</source>
|}
|object
|no
|In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more informationsinformation.
|
|
"isCompany": true,
"isActive": true,
"customerName": "Customer Ltd."
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern", "belongsToResellerID": 4000000
},
{
|object
|no
|In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more informationsinformation.
|
|
|string
|yes
|The customer's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"customerName": "SuperCustomer Ltd."</source> |-duper Hosting|<code>countryCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"countryCode": "CH"</source> |-|<code>postalCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"postalCode": "3012"</source> |-|<code>localityName</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"localityName": "Bern</source> |-|<code>belongsToResellerID</code>|integer|yes|The reseller identification number the customer resource must belong to.||@TODO add regex||<source lang="javascript">"belongsToResellerID": 4000000</source>
|}
=== Customer element retrieval (GET) ===
To retrieve an existing customer and fetch the informations information associated with it, the client needs to send a HTTP <code>GET</code> request on the customer's element resource URI (such as <code>https://api.example.com/v1/customers/5000001</code>.The service responds with a HTTP status code 200 (OK) on success and returns the associated customer informationsinformation.
==== Customer element retrieval request message ====
|string
|yes
|The customer's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"customerName": "SuperCustomer Ltd."</source> |-duper Hosting|<code>externalID</code>|string|no|An optional external ID the customer belongs to (is used for the mapping to external databases).||@TODO add regex||<source lang="javascript">"externalID": 12345</source> |-|<code>belongsToResellerID</code>|integer|yes|The reseller identification number the customer resource must belong to.||@TODO add regex||<source lang="javascript">"belongsToResellerID": 4000000</source>
|-
|object
|yes
|An object holding the billing address informations information for the given customer. Refer to the [[#billingAddress_object|billingAddress object table]] for more informationsinformation.
|
|
|object
|no
|An object holding the shipping address informations information for the given customer. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informationsinformation.
|
|
}
</source>
|-
|<code>customers</code>
|string
|yes
|The location URI of the customers belonging to this customer resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"customers": "https://api.example.com/v1/customers/5000001/customers"</source>
|-
|object
|no
|In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more informationsinformation.
|
|
==== Customer update response message body ====
On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further informations information about the failure.
== Customer partly update (PATCH) ==
==== Customer partly update response message body ====
On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further informations information about the failure.
== Customer deletion (DELETE) ==
==== Customer deletion response message body ====
On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further informations information about the failure.
== Customer search ==