Repository and Configuration
In order get the SDK to execute API calls, we use the request method in the Client repository. This repository manages the cache layer and provides a mechanism to register logs. It can also take generic configurations variables that are used to create the API calls.
Examples
Test Request in production environment
// Execute the 'test' method to check the connection with the API
$response = Client::getInstance()
->setApiKey($api_key)
->request(Client::TEST);
Service Availability Request in test environment displaying debug information
$response = Client::getInstance()
->setApiKey('dGVzdDp0ZXN0')
->setEnvironment('sandbox')
->setDebug(true)
->request(
Client::SERVICE_AVAILABILITY,
[ "destination_address" => [
"postal_code" => "08022",
"street_name" => "Urquinaona",
"street_number" => "5",
"city" => "Barcelona",
"country_code" => "ES"
],
"products" => [
[
"name" => "T-shirt Monashee",
"reference" => "PQR48-D",
"quantity" => 1,
"weight_kg" => 0.5
],
[
"name" => "Jeans Lemon pie",
"reference" => "WDV48-D",
"quantity" => 2,
"weight_kg" => 0.5
]
]
]);
Last Mile Confirmation Request in production environment
$response = Client::getInstance()
->setApiKey('dGVzdDp0ZXN0')
->setServiceNumber('HRI-6523')
->request(Client::LASTMILE_VALIDATION,
[
"user_selection" => [
"validation_windows" =>
[
[
"start_time" => "2016-04-19T08:00:00+0200",
"end_time" => "2016-04-19T12:00:00+0200"
],
[
"start_time" => "2016-04-19T12:00:00+0200",
"end_time" => "2016-04-19T14:00:00+0200"
]
],
"delivery_windows":
[
[
"start_time" => "2016-04-19T12:00:00+0200",
"end_time" => "2016-04-19T14:00:00+0200"
]
],
"total_price": 5.18,
"currency_code": "EUR"
],
"shopper" => [
"name" => "Roberto",
"surname" => "RodrÃguez",
"email" => "roberto.rodriguez@gmail.com",
"phone" => "83486923409"
],
"destination_address" => [
"postal_code" => "08022",
"street_name" => "Urquinaona",
"street_number" => "5",
"city" => "Barcelona",
"country_code" => "ES" ]
]
);
Constants
List of all API requests and their corresponding constants to be executed via the SDK:
- Service Requests:
- Service Availability: SERVICE_AVAILABILITY
- Service Cancellation: SERVICE_CANCELLATION
- Coverage: SERVICE_COVERAGE
- Show Shipping Service: SERVICE_STATUS
- Last Mile Shipping Requests:
- Last Mile Best Price: LASTMILE_BESTPRICE
- Last Mile Service Request: LASTMILE_CREATION
- Get Assets: LASTMILE_ASSETS
- Last Mile Validation: LASTMILE_VALIDATION
- Last Mile Confirmation: LASTMILE_CONFIRMATION
- Standard Shipping Requests:
- Standard Service Request: STANDARD_CREATION
- Standard Confirmation: STANDARD_CONFIRMATION
- Other types of requests:
- Test Request: TEST
- Backend Access: ACCESS_BACKEND
- Registration Access: ACCESS_REGISTRATION
- Payment Confirmation: PAYMENT_CONFIRMATION
Initialization & Configuration
API Key
setApiKey initializes the key that is used to connect to the API.
Client::getInstance()->setApiKey($api_key)
Service Number
As many requests have to do with a specific service, setServiceNumber sets the number of the service we are working with.
Client::getInstance()->setServiceNumber($service_number);
Cache
setCacheConfiguration takes as a parameter an array that details the cache configuration in the format used by the php fast cache library.
Client::getInstance()->setCacheConfiguration($cache_config)
Logger
setLogger makes it possible for the user of the SDK to assig a custom object to manage the API log messages. This object has to implement the Components\LoggerInterface interface: it has one log method that takes two parameters - an error message and an error code.
Client::getInstance()->setLogger($my_custom_logger);
Sandbox environment
setEnvironment defines where the API requests are being sent to. It can take the values of sandbox to perform some tests or production to work with real world services. No service that has been confirmed in the test environment will be executed. The sandbox environment requires no API Key, and ignores the API key that may have been configured.
Client::getInstance()->setEnvironment('sandbox');
By default, the environment is set to 'production'.
General Configuration
setConfig is used to set general configuration variables. It takes an array of key and their corresponding values.
Request Timeouts
The timeout option, available via the timeout key, sets the maximum number of seconds an API request will wait for the response to complete.
Client::getInstance()->setConfig([
'timeout' => 2.25
]);
The default value is 5 seconds.
Debug mode
Debug mode can be activated using the setDebug method of the repository:
Client::getInstance()->setDebug(true);
By default, this parameter value is false. When set to true, all API calls will print information about requests that are made to the api.
Exceptions
All SDK exceptions are children of the base exception Exceptions\ApiClientException.
Any request that receives an error response when executed (http status code 4xx or 5xx) throws a Exceptions\ApiResponseException. This exception provides the following methods:
- exact http status code: getCode()
- api specific error code: getApiErrorCode()
- error message: getMessage()
- Details about the error (depending on the request): getApiMessageBody()
List of API specific error codes, along with the corresponding http error code:
- #1. Incorrect message format. (HTTP 400 Bad Request)
- #2. Invalid ContentType. (HTTP 415 Unsupported Media Type)
- #3. Missing message body. (HTTP 400 Bad Request)
- #4. The user or password is invalid. (HTTP 401 Unauthorized)
- #5. You cannot access this resource. (HTTP 403 Forbidden)
- #6. The method you are applying to this resource has expired (http 400 Bad Request)
- #7. The format of the request or the data is incorrect. (HTTP 422 Unprocesable Entity)
- #20. Currency code is invalid (HTTP 422 Unprocesable Entity)
- #21. Currency code is not suported (HTTP 422 Unprocesable Entity)
- #22. Country code in invalid (HTTP 422 Unprocesable Entity)
- #23. Country code is not supported (HTTP 422 Unprocesable Entity)
- #24. Postal code is invalid (HTTP 422 Unprocesable Entity)
- #25. Time window is invalid (HTTP 422 Unprocesable Entity)
example
try {
$params = [
"shopper" => $shopper_info,
"destination_address" => $shopper_address,
"products" => $products
];
$response = Client::getInstance()
->setApiKey($api_key)
->request(Client::SERVICE_CREATION, $params);
} catch (ApiClientException $e) {
echo "There was an error executing the request : ".$e->getMessage();
}