Class CustomersApiV2Controller

┗ CustomersApiV2Controller

Package: ApiV2Controllers
Category: System
Located at Controllers/Api/v2/CustomersApiV2Controller.inc.php

Methods summary


				
				 protected 
				
				

				__initialize( void )

Initializes API Controller


				
				 public 
				
				

				post( void )

Api

{post} /customers Create Customer

Apidescription

This method enables the creation of a new customer (whether registree or a guest). Additionally the user can provide new address information or just set the id of an existing one. Check the examples bellow. An example script to demonstrate the creation of a new customer is located under ./docs/REST/samples/customer-service/create_account.php in the git clone, another one to demonstrate the creation of a guest customer is located under ./docs/REST/samples/customer-service/create_guest_account.php.

Apierror

409-Conflict The API will return this status code if the customer's email already exists in the database (only applies on registree records).

Apigroup

Customers

Apiname

CreateCustomer

Apiparam

{string} gender Customer's gender, provide "m" for male and "f" for female.
{string} firstname Customer's first name.
{string} lastname Customer's last name.
{string} dateOfBirth Customer's date of birth in "yyyy-mm-dd" format.
{string} vatNumber Valid customer VAT number.
{string} telephone Customer's telephone number.
{string} fax Customer's fax number.
{string} email Valid email address for the customer.
{string} password (Optional) Customer's password, only registree records need this value.
{bool} isGuest Customer's record type, whether true if guest or false if not.

{int} addressId Provide a record ID if the address already exist in the database (otherwise omit this property).

{object} address (Optional) Contains the customer's address data, can be omitted if the "addressId" is provided.

{string} address.company Customer's company name.
{string} street The address street.
{string} houseNumber The address house number.
{string} additionalAddressInfo Additional information about the address.
{string} address.suburb Customer's suburb.
{string} address.postcode Customer's postcode.
{string} address.city Customer's city.
{int} address.countryId Must be a country ID registered in the shop database.
{int} address.zoneId The country zone ID, as registered in the shop database.
{Object} addonValues Contains some extra addon values.

Apiparamexample

{json} Registree (New Address) { "gender": "m", "firstname": "John", "lastname": "Doe", "dateOfBirth": "1985-02-13", "vatNumber": "0923429837942", "telephone": "2343948798345", "fax": "2093049283", "email": "customer@email.de", "password": "0123456789", "isGuest": false, "address": { "company": "Test Company", "street": "Test Street", "houseNumber": "123", "additionalAddressInfo": "1. Etage", "suburb": "Test Suburb", "postcode": "23983", "city": "Test City", "countryId": 81, "zoneId": 84, "b2bStatus": true }, "addonValues": { "test_key": "test_value" } }

{json} Registree (Existing Address) { "gender": "m", "firstname": "John", "lastname": "Doe", "dateOfBirth": "1985-02-13", "vatNumber": "0923429837942", "telephone": "2343948798345", "fax": "2093049283", "email": "customer@email.de", "password": "0123456789", "isGuest": false, "addressId": 57, "addonValues": { "test_key": "test_value" } }

{json} Guest (New Address) { "gender": "m", "firstname": "John", "lastname": "Doe", "dateOfBirth": "1985-02-13", "vatNumber": "0923429837942", "telephone": "2343948798345", "fax": "2093049283", "email": "customer@email.de", "isGuest": true, "address": { "company": "Test Company", "street": "Test Street", "houseNumber": "123", "additionalAddressInfo": "1. Etage", "suburb": "Test Suburb", "postcode": "23983", "city": "Test City", "countryId": 81, "zoneId": 84, "b2bStatus": false }, "addonValues": { "test_key": "test_value" } }

{json} Guest (Existing Address) { "gender": "m", "firstname": "John", "lastname": "Doe", "dateOfBirth": "1985-02-13", "vatNumber": "0923429837942", "telephone": "2343948798345", "fax": "2093049283", "email": "customer@email.de", "isGuest": true, "addressId": 57, "addonValues": { "test_key": "test_value } }

Apisuccess

(Success 201) Response-Body If successful, this method returns a complete Customers resource in the response body.

Apiversion

2.3.0


				
				 public 
				
				

				put( void )

Api

{put} /customers/:id Update Customer

Apidescription

This method will update the information of an existing customer record. You will need to provide all the customer information with the request (except from password and customer id). Also note that you only have to include the "addressId" property. An example script to demonstrate how to update the admin accounts telephone number is located under ./docs/REST/samples/customer-service/update_admin_telephone.php in the git clone.

Apierror

400-BadRequest Customer record ID was not provided or is invalid.
400-BadRequest Customer data were not provided.
404-NotFound Customer record was not found.

409-Conflict The API will return this status code if the customer's email already exists in the database (only applies on registree records).

Apigroup

Customers

Apiname

UpdateCustomer

Apiparamexample

{json} Request-Body (Registree) { "number": "234982739", "gender": "m", "firstname": "John", "lastname": "Doe", "dateOfBirth": "1985-02-13", "vatNumber": "0923429837942", "vatNumberStatus": 0, "telephone": "2343948798345", "fax": "2093049283", "email": "customer@email.de", "statusId": 2, "isGuest": false, "addressId": 54, "addonValues": { "test_key": "test_value-UPDATED" } }

{json} Request-Body (Guest) { "number": "234982739", "gender": "m", "firstname": "John", "lastname": "Doe", "dateOfBirth": "1985-02-13", "vatNumber": "0923429837942", "vatNumberStatus": true, "telephone": "2343948798345", "fax": "2093049283", "email": "customer@email.de", "statusId": 1, "isGuest": true, "addressId": 98, "addonValues": { "test_key": "test_value-UPDATED" } }

Apisuccess

Response-Body If successful, this method returns the updated customer resource in the response body.

Apiversion

2.3.0


				
				 public 
				
				

				delete( void )

Api

{delete} /customers/:id Delete Customer

Apidescription

Remove a customer record from the system. This method will always return success even if the customer does not exist (due to internal CustomerWriteService architecture decisions, which strive to avoid unnecessary failures). An example script to demonstrate how to delete a customer is located under ./docs/REST/samples/customer-service/remove_account.php in the git clone.

Apiexample

{curl} Delete Customer with ID = 84 curl -X DELETE --user admin@shop.de:12345 http://shop.de/api.php/v2/customers/84

Apigroup

Customers

Apiname

DeleteCustomer

Apisuccessexample

{json} Success-Response { "code": 200, "status": "success", "action": "delete", "customerId": 84 }

Apiversion

2.1.0


				
				 public 
				
				

				get( void )

Api

{get} /customers/:id Get Customers

Apidescription

Get multiple or a single customer record through the GET method. This resource supports the following GET parameters as described in the first section of documentation: sorting minimization, search, pagination and links. Additionally you can filter customers by providing the GET parameter "type=guest" or "type=registree". Sort and pagination GET parameters do not apply when a single customer record is selected (e.g. api.php/v2/customers/84). An example script to demonstrate how to fetch customer data is located under ./docs/REST/samples/customer-service/get_admin_data.php in the git clone

Important: Currently the CustomerReadService does not support searching in address information of a customer.

Apierror

404-NotFound Customer record could not be found.
400-BadRequest Invalid customer type filter provided (expected 'registree' or 'guest').

Apierrorexample

Error-Response (Customer Not Found) HTTP/1.1 404 Not Found { "code": 404, "status": "error", "message": "Customer record could not be found." }

Error-Response (Invalid Type Filter) HTTP/1.1 400 Bad Request { "code": 400, "status": "error", "message": "Invalid customer type filter provided, expected 'guest' or 'registree' and got: admin" }

Apiexample

{curl} Get All Customers curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/customers

{curl} Get Customer With ID = 982 curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/customers/982

{curl} Get Guest Customers curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/customers?type=guest

{curl} Search Customers curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/customers?q=admin@shop.de

{curl} Get Customer Addresses curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/customers/57/addresses

Apigroup

Customers

Apiname

GetCustomer

Apiversion

2.3.0


				
				 protected 
				
				

				_getCustomerAddresses( void )

Sub-Resource Customer Addresses

Methods inherited from HttpApiV2Controller

_linkResponse(), _locateResource(), _mapResponse(), _minimizeResponse(), _paginateResponse(), _searchResponse(), _setJsonValue(), _sortResponse(), _writeResponse()

Methods inherited from AbstractApiV2Controller

__construct(), _prepareResponse(), _setRateLimitHeader(), _validateRequest()

Constants summary

Constants inherited from AbstractApiV2Controller

DEFAULT_CONTROLLER_NAME, DEFAULT_PAGE_ITEMS, DEFAULT_RATE_LIMIT, DEFAULT_RATE_RESET_PERIOD

Properties summary


				
				protected  
				

				
					$customerWriteService
				

				: CustomerWriteService


				
				protected  
				

				
					$customerReadService
				

				: CustomerReadService


				
				protected  
				

				
					$countryService
				

				: CountryService


				
				protected  
				

				
					$addressService
				

				: AddressBookSErvice


				
				protected  
				

				
					$customerJsonSerializer
				

				: CustomerJsonSerializer


				
				protected  
				

				
					$addressJsonSerializer
				

				: AddressJsonSerializer

Properties inherited from AbstractApiV2Controller

$api, $uri

Class CustomersApiV2Controller

Methods summary

Api

Apidescription

Apierror

Apigroup

Apiname

Apiparam

Apiparamexample

Apisuccess

Apiversion

Api

Apidescription

Apierror

Apigroup

Apiname

Apiparamexample

Apisuccess

Apiversion

Api

Apidescription

Apiexample

Apigroup

Apiname

Apisuccessexample

Apiversion

Api

Apidescription

Apierror

Apierrorexample

Apiexample

Apigroup

Apiname

Apiversion

Throws

See

Methods inherited from HttpApiV2Controller

Methods inherited from AbstractApiV2Controller

Constants summary

Constants inherited from AbstractApiV2Controller

Properties summary

Properties inherited from AbstractApiV2Controller