Class OrdersApiV2Controller
Provides a gateway to the OrderWriteService and OrderReadService classes, which handle the shop order resources.
| category |
System |
|---|---|
| package |
ApiV2Controllers |
__construct(\Slim\Slim $api, array $uri)
Call this constructor from every child controller class in order to set the Slim instance and the request routes arguments to the class.
| deprecated |
The "__initialize" method will is deprecated and will be removed in a future version. Please use the new "init" for bootstrapping your child API controllers. |
|---|---|
| Throws |
|
\Slim\SlimSlim framework instance, used for request/response manipulation.
arrayThis array contains all the segments of the current request, starting from the resource.
__initialize()
_changeHistory()
| Throws |
|
|---|
_linkResponse(array &$response)
The APIv2 operates with simple resources that might be linked with other resources. This architecture promotes flexibility so that API consumers can have a simpler structure. This method will search for existing external resources and will add a link to the end of each resource.
IMPORTANT: If for some reason you need to include custom links to your resources do not use this method. Include them inside your controller method manually.
NOTICE #1: This method will only search at the first level of the resource. That means that nested ID values will not be taken into concern.
NOTICE #2: You can provide both associative (single response item) or sequential (multiple response items) arrays and this method will adjust the links accordingly.
arrayPassed by reference, new links will be appended into the end of each resource.
_locateResource(string $p_name, integer $p_id)
Use this method whenever you want the "Location" header to point to an existing resource so that clients can use it to fetch that resource without having to generate the URL themselves.
| Throws |
|
|---|
string
integer
_mapResponse(array $criteria) : boolean
Some API resources contain many subresources which makes the creation of a single controller class complicated and hard to maintain. This method will forward the request to a another controller by checking the provided criteria.
Example:
$criteria = array( 'items' => 'OrdersItemsAttributesApiV2Controller', 'totals' => 'OrdersTotalsApiV2Controller' );
Notice: Each controller should map a direct subresource and not deeper ones. This way every API controller is responsible to map its direct subresources.
| Throws |
|
|---|
arrayAn array containing the mapping criteria.
booleanReturns whether the request was eventually mapped.
_minimizeResponse(array &$response)
APIv2 supports the GET "fields" parameter which enables the client to select the exact fields to be included in the response. It does not support nested fields, only first-level.
You can provide both associative (single response item) or sequential (multiple response items) arrays and this method will adjust the links accordingly.
arrayPassed by reference, it will be minified to the required fields.
_paginateResponse(array &$response, integer $p_totalItemCount = null)
One of the common functionalities of the APIv2 is the pagination and this can be easily achieved by this function which will update the response with the records that need to be returned. This method will automatically set the pagination headers in the response so that client apps can easily navigate through results.
arrayPassed by reference, it will be paginated according to the provided parameters.
integer|null Optionally set the total number of resources.
_prepareResponse()
This method will prepare default attributes of the API responses. Further response settings must be set explicitly from each controller method separately.
Not available to child-controllers (private method).
_search()
This method will search all orders with a given search condition.
| see | \OrdersApiV2Controller::post() |
|---|---|
_searchResponse(array &$response, string $p_keyword)
Normally the best way to filter the results is through the corresponding service but some times there is not specific method for searching the requested resource or subresource. When this is the case use this method to filter the results of the response before returning them back to the client.
| Throws |
|
|---|
arrayContains the response data to be written.
stringThe keyword to be used for the search.
_setJsonValue(string $jsonString, string $property, string $value) : string
stringThe json formatted string which should be updated.
stringThe name or key of the property which should be updated.
stringThe new value which should be set.
stringThe updated json formatted string.
_setPaginationHeader(integer $p_currentPage, integer $p_itemsPerPage, integer $p_totalItemCount)
Useful for GET responses that return multiple items to the client. The client can use the links to navigate through the records without having to construct them on its own.
| link |
Not available to child-controllers (private method). |
|---|---|
| Throws |
|
integerCurrent request page number.
integerThe number of items to be returned in each page.
integerTotal number of the resource items.
_setRateLimitHeader()
There is a cache file that will store each user session and provide a security mechanism that will protect the shop from DOS attacks or service overuse. Each session will use the hashed "Authorization header" to identify the client. When the limit is reached a "HTTP/1.1 429 Too Many Requests" will be returned.
Headers: X-Rate-Limit-Limit >> Max number of requests allowed. X-Rate-Limit-Remaining >> Number of requests remaining. X-Rate-Limit-Reset >> UTC epoch seconds until the limit is reset.
Important: This method will be executed in every API call and it might slow the response time due to filesystem operations. If the difference is significant then it should be optimized.
Not available to child-controllers (private method).
| Throws |
|
|---|
_sortResponse(array &$response)
This method supports nested sort values, so by providing a "+address.street" value to the "sort" GET parameter the records will be sort by street value in ascending order. Method supports sorting up to 5 fields.
Important #1: This method has some advantages and disadvantages over the classic database sort mechanism. First it does not need mapping between the API fields and the database fields. Second it does not depend on external system code to sort the response items, so if for example a domain-service does not support sorting the result can still be sorted before sent to the client. The disadvantages are that it will only support a predefined number of fields and this is a trade-off because the method should not use the "eval" function, which will introduce security risks. Furthermore it might be a bit slower than the database sorting.
Important #2: This method is using PHP's array_multisort which by default will sort strings in a case sensitive manner. That means that strings starting with a capital letter will come before strings starting with a lowercase letter. http://php.net/manual/en/function.array-multisort.php
Example: // will sort ascending by customer ID and descending by customer company api.php/v2/customers?sort=+id,-address.company
arrayPassed by reference, contains an array of the multiple items that will returned as a response to the client.
_validateRequest()
This method will validate the request headers, user authentication and other parameters before the controller proceeds with the response.
Not available to child-controllers (private method).
| Throws |
|
|---|
_writeResponse(array $response, integer $p_statusCode = 200)
Use this method to write a JSON encoded, pretty printed and unescaped response to the client consumer. It is very important that the API provides pretty printed responses because it is easier for users to debug and develop.
IMPORTANT: PHP v5.3 does not support the JSON_PRETTY_PRINT and JSON_UNESCAPED_SLASHES so this method will check for their existance and then use them if possible.
arrayContains the response data to be written.
integer(optional) Provide a custom status code for the response, default 200 - Success.
delete()
| apiVersion |
2.1.0 |
|---|---|
| apiName |
DeleteOrder |
| apiGroup |
Orders |
| apiDescription |
Remove an entire Order record from the database. This method will also remove the order-items along with
their attributes and the order-total records. To see an example usage take a look at
|
| apiExample |
{curl} Delete Order With ID = 400597 curl -X DELETE --user admin@shop.de:12345 http://shop.de/api.php/v2/orders/400597 |
| apiSuccessExample |
{json} Success-Response { "code": 200, "status": "success", "action": "delete", "resource": "Order", "orderId": 400597 } |
| apiError |
400-BadRequest The order ID value was invalid. |
| apiErrorExample |
Error-Response HTTP/1.1 400 Bad Request { "code": 400, "status": "error", "message": "Order record ID was not provided in the resource URL." } |
get()
| apiVersion |
2.3.0 |
|---|---|
| apiName |
GetOrder |
| apiGroup |
Orders |
| apiDescription |
Get multiple or a single order record through a GET request. This method supports all the GET parameters that are mentioned in the "Introduction" section of this documentation. Important: Whenever you make requests that will return multiple orders the response will contain a smaller version of each order record called order-list-item. This is done for better performance because the creation of a complete order record takes significant time (many objects are involved). If you still need the complete data of an order record you will have to make an extra GET request with the ID provided. |
| apiExample |
{curl} Get All Orders curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/orders {curl} Get Order With ID = 400242 curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/orders/400242 {curl} Search Orders curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/orders?q=DE {curl} Get Order's Items curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/orders/400573/items {curl} Get Order Item's Attributes curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/orders/400573/items/57/attributes {curl} Get Orders Totals curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/orders/400573/totals |
patch()
| apiVersion |
2.3.0 |
|---|---|
| apiName |
UpdateOrderStatus |
| apiGroup |
Orders |
| apiDescription |
Use this method if you want to update the status of an existing order and create an order history entry. The status history entry must also contain extra information as shown in the JSON example. |
| apiParamExample |
{json} Order Status History { "statusId": 1, "comment": "This is the entry comment", "customerNotified": false, "customerId": 1 } |
| apiParam |
{Number} statusId The new status ID will also be set in the order record. {String} comment Assign a comment to the status history entry. {Boolean} customerNotified Defines whether the customer was notified by this change. {Number} customerId The customer ID of the admin account. |
| apiSuccess |
(200) Request-Body If successful, this method returns the complete order status history resource in the response body. |
| apiSuccessExample |
{json} Success-Response { "id": 984, "statusId": 3, "dateAdded": "2016-01-22 10:52:11", "comment": "This is the entry's comments", "customerNotified": true, "customerId": 1 } |
| apiError |
400-BadRequest Order data were not provided or order record ID was not provided or is invalid. |
| apiErrorExample |
Error-Response (Empty request body) HTTP/1.1 400 Bad Request { "code": 400, "status": "error", "message": "Order data were not provided." } Error-Response (Missing or invalid ID) HTTP/1.1 400 Bad Request { "code": 400, "status": "error", "message": "Order record ID was not provided or is invalid." } |
post()
| apiVersion |
2.2.0 |
|---|---|
| apiName |
CreateOrder |
| apiGroup |
Orders |
| apiDescription |
This method enables the creation of a new order into the system. The order can be bound to an existing
customer or be standalone as implemented in the OrderService. Make sure that you check the Order resource
representation. To see an example usage take a look at |
| apiParamExample |
{json} Request-Body { "id": 400210, "statusId": 1, "purchaseDate": "2015-11-06 12:22:39", "currencyCode": "EUR", "languageCode": "DE", "totalWeight": 0.123, "comment": "", "paymentType": { "title": "cod", "module": "cod" }, "shippingType": { "title": "Pauschale Versandkosten (Standar", "module": "flat_flat" }, "customer": { "id": 1, "number": "", "email": "admin@shop.de", "phone": "0421 - 22 34 678", "vatId": "", "status": { "id": 0, "name": "Admin", "image": "admin_status.gif", "discount": 0, "isGuest": false } }, "addresses": { "customer": { "gender": "m", "firstname": "John", "lastname": "Doe", "company": "JD Company", "street": "Test Street", "houseNumber": "123", "additionalAddressInfo": "1. Etage", "suburb": "", "postcode": "28219", "city": "Bremen", "countryId": 81, "zoneId": 0, "b2bStatus": false }, "billing": { "gender": "m", "firstname": "John", "lastname": "Doe", "company": "JD Company", "street": "Test Street", "houseNumber": "123", "additionalAddressInfo": "1. Etage", "suburb": "", "postcode": "28219", "city": "Bremen", "countryId": 81, "zoneId": 0, "b2bStatus": false }, "delivery": { "gender": "m", "firstname": "John", "lastname": "Doe", "company": "JD Company", "street": "Test Street", "houseNumber": "123", "additionalAddressInfo": "1. Etage", "suburb": "", "postcode": "28219", "city": "Bremen", "countryId": 81, "zoneId": 0, "b2bStatus": false } }, "items": [ { "id": 1, "model": "12345-s-black", "name": "Ein Artikel", "quantity": 1, "price": 11, "finalPrice": 11, "tax": 19, "isTaxAllowed": true, "discount": 0, "shippingTimeInformation": "", "checkoutInformation": "Checkout information goes here ...", "quantityUnitName": "Liter", "attributes": [ { "id": 1, "name": "Farbe", "value": "rot", "price": 0, "priceType": "+", "optionId": 1, "optionValueId": 1, "combisId": null } ], "downloadInformation": [ { "filename": "Dokument.pdf", "maxDaysAllowed": 5, "countAvailable": 14 } ], "addonValues": { "productId": "2", "quantityUnitId": "1" } } ], "totals": [ { "id": 1, "title": "Zwischensumme:", "value": 50, "valueText": "50,00 EUR", "class": "ot_subtotal", "sortOrder": 10 } ], "statusHistory": [ { "id": 1, "statusId": 1, "dateAdded": "2015-11-06 12:22:39", "comment": "", "customerNotified": true } ], "addonValues": { "customerIp": "", "downloadAbandonmentStatus": "0", "serviceAbandonmentStatus": "0", "ccType": "", "ccOwner": "", "ccNumber": "", "ccExpires": "", "ccStart": "", "ccIssue": "", "ccCvv": "" } } |
| apiParam |
{String} statusId Order status ID, use one of the existing statuses IDs. {String} purchaseDate Must have the 'Y-m-d H:i:s' format. {String} currencyCode Order's currency code, use one of the existing currency codes. {String} languageCode Use one of the existing language codes. {Number} totalWeight The total weight of the order items. {String} comment Order's comments. {Object} paymentType Contains information about the payment type, use values that match with the shop's modules. {String} paymentType.title The payment title. {String} paymentType.module The payment module name. {Object} shippingType Contains information about the shipping type, use values that match with the shop's modules. {String} shippingType.title The shipping title. {String} shippingType.module The shipping module name. {Object} customer Contains the order's customer information. {String} customer.number Customer's number (often referred as CID). {String} customer.email Customer's email address. {String} customer.phone Customer's telephone number. {String} customer.vatId Customer's VAT ID number. {Object} customer.status Contains information about the customer's status on the system. {Number} customer.status.id The customer's status ID must be one of the existing statuses in the shop. {String} customer.status.name The customer-status name. {String} customer.status.image The customer-status image (check the value from the shop). {Number} customer.status.discount The discount that is made to this customer status. {Boolean} customer.status.isGuest Defines whether the customer is a guest. {Object} addresses Contains the address information of the order. There are three different kind of addresses: customer, billing and delivery. {Object} addresses.customer Contains the customer-address data. {String} addresses.customer.gender The gender value can be either "m" or "f". {String} addresses.customer.firstname First name of the address block. {String} addresses.customer.lastname Last name of the address block. {String} addresses.customer.company Company name of the address block. {String} addresses.customer.street Street of the address block. {string} addresses.customer.houseNumber The house number of the address block. {string} addresses.customer.additionalAddressInfo Additional information of the address block. {String} addresses.customer.suburb Suburb of the address block. {String} addresses.customer.postcode Postcode of the address block. {String} addresses.customer.city City of the address block. {String} addresses.customer.countryId Country ID of the address block. You can use the "countries" resource of the API to get the available countries. {String} addresses.customer.zoneId Zone ID of the address block. You can use the "zones" resource of the API to get the available countries. {Boolean} addresses.customer.b2bStatus Whether the customer has the b2bStatus. {Object} addresses.billing{...} Contains the address block for the billing. It expects the same value types as the customer-address block. See the JSON example above. {Object} addresses.delivery{...} Contains the address block for the billing. It expects the same value types as the customer-address block. See the JSON example above. {Array} items Every order contains a list of order items which can also have their own attributes. {String} items.model Item's model value. {String} items.name Item's name value. {Number} items.quantity Quantity of the purchase. {Number} items.price The initial price of the order item. {Number} items.finalPrice The final price of the order item. {Number} items.tax The tax applied to the value. {Boolean} items.isTaxAllowed Whether tax is allowed. {Number} items.discount Percentage of the discount made for this order. {String} items.shippingTimeInformation Include shipping information to the order. {String} items.checkoutInformation Include checkout information to the order. {String} items.quantityUnitName The Quantity unit name of the order item. {Array} items.attributes Contains some attributes or properties of the order item. The difference between the attributes and the properties is that attributes must have the "optionId" and "optionValueId" values while properties must only have the "combisId" value. The properties system is still included as a fallback to old releases of the shop, so we will use the "attributes" term in this document. {String} items.attributes.name Attribute's name. {String} items.attributes.value Attribute's value. {Number} items.attributes.price Give the attributes price. {String} items.attributes.priceType Make sure that you use one of the existing price types of the shop. {Number} items.attributes.optionId Only-attributes need this value. {Number} items.attributes.optionValueId Only-attributes need this value. {Number} items.attributes.combisId Only-properties need this value. {Array} items.downloadInformation Contains the downloads of the order item. {String} items.downloadInformation.filename Contains a non empty filename. {Number} items.downloadInformation.maxDaysAllowed Contains the number of days where downloads are possible. {Number} items.downloadInformation.countAvailable Contains the number of possible downloads. {Object} items.addonValues (Optional) Contains key value pairs of additional order item data. {Array} totals Contains the order totals. The order totals are entries that display analytic information about the charges of the user. {String} totals.title Order total's title. {Number} totals.value The value stands for the money. {String} totals.valueText String representation of the value containing the currency code. {String} totals.class Internal order-total class. A list of possible values can be seen in the database once you create a complete order record. {Number} totals.sortOrder Defines the order of the totals list as they are being displayed. {Object} addonValues (Optional) Contains key value pairs of additional order data. |
| apiSuccess |
(Success 201) Response-Body If successful, this method returns a complete Order resource in the response body. |
| apiError |
400-BadRequest The body of the request was empty. |
| apiErrorExample |
Error-Response HTTP/1.1 400 Bad Request { "code": 400, "status": "error", "message": "Order data were not provided." } |
put()
| apiVersion |
2.2.0 |
|---|---|
| apiName |
UpdateOrder |
| apiGroup |
Orders |
| apiDescription |
Use this method to update an existing order record. It uses the complete order JSON resource so
it might be useful to fetch it through a GET request, alter its values and PUT it back in order
to perform the update operation. Take a look in the POST method for more detailed explanation on
every resource property. To see an example usage take a look at
|
| apiSuccess |
Response-Body If successful, this method returns the updated Order resource in the response body. |
| apiError |
400-BadRequest The body of the request was empty or the order record ID was not provided or is invalid. |
| apiErrorExample |
Error-Response (Empty request body) HTTP/1.1 400 Bad Request { "code": 400, "status": "error", "message": "Order data were not provided." } Error-Response (Missing or invalid ID) HTTP/1.1 400 Bad Request { "code": 400, "status": "error", "message": "Order record ID was not provided or is invalid." } |
DEFAULT_PAGE_ITEMS
| var |
|---|
DEFAULT_CONTROLLER_NAME
| var |
|---|
DEFAULT_RATE_LIMIT
| var |
|---|
DEFAULT_RATE_RESET_PERIOD
| var |
|---|
orderListItemJsonSerializer : \OrderListItemJsonSerializer
subresource : array
| var |
|---|
array
api : \Slim\Slim
| var |
|---|
\Slim\Slim
uri : array
Example: URI - api.php/v2/customers/73/addresses CODE - $this->uri[1]; // will return '73'
| var |
|---|
array