Speedy REST API examples

• Create Shipment Request example
• Print Request example
• Get Contract Clients Request example
• Find Country Request examples
• Find Office Request examples
• Find Site Request examples
• Find Complex Request example
• Find Street Request examples
• Destination Services Request example
• Calculation Request examples
• Track Request examples
• Address examples
• Speedy demo address form

#-> GLobal variables
define('SPEEDY_API_USERNAME', 'xxxxxx');
define('SPEEDY_API_PASSWORD', 'yyyyyy');
define('SPEEDY_API_BASE_URL', 'https://api.speedy.bg/v1/');
define('LANGUAGE', 'EN');


#-> Function for api requests via cURL functions. In the examples we are using POST requests.
function apiRequest($apiURL, $jsonData)
   {
   #-> Initiate cURL
   $curl = curl_init($apiURL);
			
   #-> Encode the array into JSON.
   $jsonDataEncoded = json_encode($jsonData);
		
   #-> Set curl options
   curl_setopt($curl, CURLOPT_POST, 1); // Tell cURL that we want to send a POST request.
   curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); // Verify the peer's SSL certificate.
   curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); // Stop showing results on the screen.
   curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5); // The number of seconds to wait while trying to connect. Use 0 to wait indefinitely.
   curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json')); // Set the content type to application/json
   curl_setopt($curl, CURLOPT_POSTFIELDS, $jsonDataEncoded); // Attach our encoded JSON string to the POST fields.
   
   #-> Get the response
   $jsonResponse = curl_exec($curl);
			
   if ( $jsonResponse === FALSE) 
      { exit("cURL Error: ".curl_error($curl)); } 
		
   return($jsonResponse);
   }

Create Shipment Request View API documentation

#-> I. SENDER
$senderArray = array(
   'phone1' => array('number' => '0888112233'),
   'contactName' => 'Ivan Petrov',
   'email' => 'ivan@petrov.bg',
   /* 'clientId' => 1234567890, // Not required */
);
/*
You can skip the 'clientId' property or all sender data ($senderArray) in the JSON DATA array bellow. In this case the sender will be the default one for the username with all the address and contact information.
Your "clientId" can be obtained from the result of a Get Contract Clients Request. Every client's object has an unique 'clientId'. 
If you have three objects (a warehouse in SOFIA, a shop in VARNA and a showroom in PLOVDIV), you have three objects with different clientIds, one for each object.
For example: If you want to sent a shipment from your shop in VARNA, and the object in VARNA is not the default for the user, you have to use the clientId for your object in VARNA as a sender.
*/


#-> II. RECIPIENT
$recipientArray = array(
   'phone1' => array('number' => '0899445566'),	
   'privatePerson' => true,
   'clientName' => 'VASIL GEORGIEV',
   'email' => 'vasil@georgiev.bg'
);

#-> For self collection shipment from office
//$recipientArray['pickupOfficeId'] = 2; // The pickupOfficeId can be obtained from the result of a Find Office Request.

#-> If the shipment is to an address. There are several options to define an address. Check the examples bellow.
$recipientAddressArray = array(
   'countryId' => 100, // BULGARIA. The 'countryId' can be obtained from the result of a Find Country Request.
   'siteId' => 68134, // SOFIA. The 'siteId' can be obtained from the result of a Find Site Request.
   'complexId' => 29, // A complex named 'KRASNA POLYANA 3'. The "complexId" can be obtained from the result of a Find Complex Request.
   'streetId' => 3109, // A street named 'USTA GENCHO'. The "streetId" can be obtained from the result of a Find Street Request.
   'streetNo' => '1A',
   'blockNo' => '301',
   'entranceNo' => '2',
   'floorNo' => '3',
   'apartmentNo' => '4',
);
$recipientArray['address'] = $recipientAddressArray;



#-> III. SERVICE DETAILS
$serviceArray = array(
   'pickupDate' => date('Y-m-d'),
   'autoAdjustPickupDate' => true, // Not mandatory
   'serviceId' => 505, // The 'serviceId' can be obtained from the result of a Destination Services Request.
   'saturdayDelivery' => true, // Not mandatory. Use it if you want delivery on Saturday/Holiday.
);

/* Cash on delivery - Not mandatory */
$cashOnDeliveryArray = array(
   'amount' => 100,
   'processingType' => 'CASH' // (CASH, POSTAL_MONEY_TRANSFER)
);

/* Options before payment - Not mandatory */
$optionsBeforePaymentArray = array(
   'option' => 'OPEN', 
   'returnShipmentServiceId' => 505,
   'returnShipmentPayer' => 'SENDER' // (SENDER, RECIPIENT, THIRD_PARTY). The sender of the returning shipment is the recipient of the primary shipment.
);
/* 
"returnShipmentServiceId" is the service for the returning shipment in case the recipient refuses to accept the primary shipment. 
It can be the same serviceId as in the primary shipment or one obtained from the result of a Destination Services Request.
*/

/* Declared value - Not mandatory */
$declaredValueArray = array(
   'amount' => 100, 
   'fragile' => true 
);

/* Additional services */
$additionalServicesArray = array(
   'cod' => $cashOnDeliveryArray,
   'obpd' => $optionsBeforePaymentArray,
   'declaredValue' => $declaredValueArray
);

/* Add additional services to the main service array */
$serviceArray['additionalServices'] = $additionalServicesArray;



#-> IV. CONTENT OF THE PARCEL
$contentsArray = array(
   'parcelsCount' => 1,
   'contents' => 'MOBILE PHONE',
   'package' => 'BOX',
   'totalWeight' => 0.6
);



#-> V. PAYMENTS
$paymentsArray = array(
   'courierServicePayer' => 'RECIPIENT', // (SENDER, RECIPIENT, THIRD_PARTY)
   'declaredValuePayer' => 'RECIPIENT' // Mandatory only if the shipment has a 'declaredValue'.
);
      


#-> VI. JSON DATA
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'sender' => $senderArray, // You can skip the sender data. In this case the sender will be the default one for the username with all the address and contact information.
   'recipient' => $recipientArray,
   'service' => $serviceArray,
   'content' => $contentsArray,
   'payment' => $paymentsArray,
   'ref1' => 'ORDER 123456'
);



#-> Create Shipment Request
$jsonResponse = apiRequest(SPEEDY_API_BASE_URL.'shipment/', $jsonData);		
$jsonResponse = json_decode($jsonResponse, true);

#-> Print the result
print_r($jsonResponse);

Print Request example. View API documentation

$parcelsArray = array(
   array('parcel' => array('id' => '1234567890')),
);

#-> The JSON data.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'paperSize' => 'A4', // A4, A6, A4_4xA6
   'parcels' => $parcelsArray
);

$jsonResponse = apiRequest(SPEEDY_API_BASE_URL.'print/', $jsonData);
			
header("Content-type: application/octet-stream");
header("Content-Type: application/pdf");
	
echo $jsonResponse;

Get Contract Clients Request example.
Retrieve all clientIds, of the own contract, and other details like names, addresses etc. Use the clientIds in your requests. View API documentation

#-> JSON DATA
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE
);

#-> Get Contract Clients Request
$jsonResponse = apiRequest(SPEEDY_API_BASE_URL.'client/contract/', $jsonData);
$jsonResponse = json_decode($jsonResponse, true);

#-> Print the result
print_r($jsonResponse);

Find Country Request examples.
Get 'id' and other details for countries. The search can be by name, part of the name or country ISO code. The 'id' is the unique identifier of the country and is used to define an address. View API documentation

#-> Example 1. Search by full country name.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'name' => 'ROMANIA'
);
/*
The result from the example will return all data for ROMANIA such as id, isoAlpha2, isoAlpha3, currencyCode, postCodeFormats, requireState etc.
If the result for a country has a property named 'currencyCode' and selected service allows it, you can use Cash On Delivery in your parcels for this country. 
*/


#-> Example 2. Search by part of the country name.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'name' => 'GER' // The 'name' is partial
);
/* The result from the example will return all countries which contain 'GER' in their names: GERMANY, ALGERIA, NIGER, NIGERIA. */


#-> Example 3. Search by country isoAlpha2.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'isoAlpha2' => 'GR'
);
/* The result from the example will return all data for GREECE. The 'isoAlpha2' and 'isoAlpha3' are unique. */

#-> Find Country Request
$jsonResponse = apiRequest(SPEEDY_API_BASE_URL.'location/country/', $jsonData);
$jsonResponse = json_decode($jsonResponse, true);

#-> Print the result
print_r($jsonResponse);

Find Office Request examples.
Get 'id' and other details for offices. The search can be by name, part of name, site etc. The 'id' is the unique identifier of the office and is used in create shipment or calculation requests. View API documentation

#-> Example 1. Find offices in a country.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'countryId' => 100, // BULGARIA
);
/* The result from the example will return all offices in BULGARIA. */


#-> Example 2. Find offices in a site.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'siteId' => 68134, // SOFIA
);
/* The result from the example will return all offices in SOFIA. */


#-> Example 3. Find office by country and part of the name. The 'countryId' is not mandatory.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'countryId' => 100, // BULGARIA
   'name' => 'SOM' // The name can be partial
);
/* The result from the example will return all offices in BULGARIA which names contain 'SOM'. */


#-> Example 4. Find office in a site by part of the name. The 'siteId' is not mandatory.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'siteId' => 68134, // SOFIA
   'name' => 'SOM' // The name can be partial
);
/* The result from the example will return all offices in SOFIA which names contain 'SOM'. */


#-> Find Office Request
$jsonResponse = apiRequest(SPEEDY_API_BASE_URL.'location/office/', $jsonData);
$jsonResponse = json_decode($jsonResponse, true);

#-> Print the result
print_r($jsonResponse);

Find Site Request examples.
Get site details such as id, type, name etc. Use these details to define an address. The 'id' is the unique identifier of the site. View API documentation

#-> Example 1. Search by part of the site name.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'countryId' => 100, // BULGARIA
   'name' => 'DOBR'
);
/* The result from the example will return data (such as id, type, post code) for all sites in BULGARIA witch contain 'DOBR' in their names: 'DOBRINISHTE', 'DOBRICH', 'DOBRA POLYANA' etc. */


#-> Example 2. Search by exact site name. The site names in BULGARIA are not unique.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'countryId' => 100, // BULGARIA
   'name' => 'DOBRICH'
);
/* The result from the example will return 3 sites in BULGARIA but with 3 different types, post codes, regions, coordinates etc. You will have to select one of the records or add another filter for more precise result. */


#-> Example 3. Search site by name and post code. The combination from the name and post code is unique.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'countryId' => 100, // BULGARIA
   'name' => 'DOBRICH', // The name can be partial
   'postCode' => 9300 
);
/* The result from the example will be an exact match for the search criteria and will return only one site. */


#-> Example 4. Search by site post code. The post codes in BULGARIA are not unique.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'countryId' => 100, // BULGARIA
   'postCode' => 1475 
);
/* The result from the example will return two sites with this post code: 'PLANA' and 'ZHELEZNITSA'. You will have to select one of the records or add another filter for more precise result. */


#-> Example 5. Search by site name, type and region. The combination from these three elements is unique.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'countryId' => 100, // BULGARIA
   'type' => 'gr.', 
   'name' => 'KOSTENETS', // The name can be partial
   'region' => 'SOFIA' // The region can be partial
);
/* The result from the example will be an exact match for the search criteria and will return only one site. */


#-> Find site Request
$jsonResponse = apiRequest(SPEEDY_API_BASE_URL.'location/site/', $jsonData);
$jsonResponse = json_decode($jsonResponse, true);

#-> Print the result
print_r($jsonResponse);

Find Complex Request examples.
Get complex details such as id, type and name. Use these details to define an address. The 'id' is the identifier of the complex. View API documentation

#-> Example 1. Search by part of the complex name.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'siteId' => 68134, // SOFIA
   'name' => 'KRASN'
);
/* The result from the example will return data such as id, type, name for all complexes in SOFIA witch contain 'KRASN' in their names: 'KRASNA POLYANA 1', 'KRASNA POLYANA 2', 'KRASNO SELO' etc. */

#-> Find Complex Request
$jsonResponse = apiRequest(SPEEDY_API_BASE_URL.'location/complex/', $jsonData);
$jsonResponse = json_decode($jsonResponse, true);

Find Street Request examples.
Get the street details and use them to define an address. The 'id' is the unique identifier of the street. View API documentation

#-> Example 1. Search street details by part of the name.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'siteId' => 68134, // SOFIA
   'name' => 'USTA'
);
/* 
The result from the example will return data (such as id, type and name) for all streets in SOFIA witch contain 'USTA' in their names: 'USTA GENCHO', 'TSANKO DYUSTABANOV'. 
You will have to select one of the records. 
*/


#-> Example 2. Search street details by full street name.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'siteId' => 68134, // SOFIA
   'name' => 'VASIL LEVSKI'
);
/* The result from the example will return 3 streets in SOFIA named 'VASIL LEVSKI' but with 3 different types: 'bul.', 'ul.' and 'pl.', and you will have to select one of the records. */


#-> Example 3. Search street details by full name and type.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'siteId' => 68134, // SOFIA
   'name' => 'VASIL LEVSKI',
   'type' => 'bul.'
);
/* The result from the example will be an exact match for the search criteria and will return only one street. */


#-> Find Street Request
$jsonResponse = apiRequest(SPEEDY_API_BASE_URL.'location/street/', $jsonData);
$jsonResponse = json_decode($jsonResponse, true);

#-> Print the result
print_r($jsonResponse);

Destination Services Request examples.
Destination Services Request will return all valid services between the sender and recipient addresses. View API documentation.

#-> Example 1. The sender has clientId, the recipient is a private person.
#-> SENDER
$senderArray = array(
   'clientId' => 1234567890
);
/*
You can skip the 'clientId' property or all sender data ($senderArray) in the JSON DATA array bellow. In this case the sender will be the default one for the username with all the address and contact information.
Your 'clientId' can be obtained from the result of a Get Contract Clients Request. Every client's object has an unique 'clientId'. 
If you have three objects (a warehouse in SOFIA, a shop in VARNA and a showroom in PLOVDIV), you have three objects with different clientIds, one for each object.
For example: If you want to sent a shipment from your shop in VARNA, and the object in VARNA is not the default for the user, you have to use the clientId for your object in VARNA as a sender.
*/

#-> RECIPIENT
$recipientArray = array(
   'privatePerson' => true,
   'addressLocation' => array(
      'siteId' => 68134 // SOFIA
   )
); 
/* There is no need to define full address. The price of the courier service is the same for different addresses in a site. */

#-> JSON DATA
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'date' => date('Y-m-d'),
   'sender' => $senderArray, // You can skip the sender data. In this case the sender will be the default one for the username with all the address and contact information.
   'recipient' => $recipientArray
); 
   
   
#-> Example 2. The sender has clientId, the recipient is a private person in another country.
#-> SENDER
$senderArray = array(
   'clientId' => 1234567890
);
/*
You can skip the 'clientId' property or all sender data ($senderArray) in the JSON DATA array bellow. In this case the sender will be the default one for the username with all the address and contact information.
Your 'clientId' can be obtained from the result of a Get Contract Clients Request. Every client's object has an unique 'clientId'.
If you have three objects (a warehouse in SOFIA, a shop in VARNA and a showroom in PLOVDIV), you have three objects with different clientIds, one for each object.
For example: If you want to sent a shipment from your shop in VARNA, and the object in VARNA is not the default for the user, you have to use the clientId for your object in VARNA as a sender.
*/

#-> RECIPIENT
$recipientArray = array(
   'privatePerson' => true,
   'addressLocation' => array(
      'countryId' => 300, // GREECE
      'postCode' => 54248 // Thessaloniki
   )
);

#-> JSON DATA
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'date' => date('Y-m-d'),
   'sender' => $senderArray, 
   'recipient' => $recipientArray
);


#-> Destination Services Request
$jsonResponse = apiRequest(SPEEDY_API_BASE_URL.'services/destination', $jsonData);
$jsonResponse = json_decode($jsonResponse, true);

#-> Print the result
print_r($jsonResponse);

Calculation Request Example. View API documentation

#-> I. SENDER
$senderArray = array(
   'clientId' => 1234567890
);
/*
You can skip the 'clientId' property or all sender data ($senderArray) in the JSON DATA array bellow. In this case the sender will be the default one for the username with all the address and contact information.
Your 'clientId' can be obtained from the result of a Get Contract Clients Request. Every client's object has an unique 'clientId'. 
If you have three objects (a warehouse in SOFIA, a shop in VARNA and a showroom in PLOVDIV), you have three objects with different clientIds, one for each object.
For example: If you want to sent a shipment from your shop in VARNA, and the object in VARNA is not the default for the user, you have to use the clientId for your object in VARNA as a sender.
*/


#-> II. RECIPIENT (to an address)
$recipientArray = array(
   'privatePerson' => true,
   'addressLocation' => array(
      'siteId' => 10135, // VARNA. The 'siteId' can be obtained from the result of a Find Site Request.
   )
);
#-> II. RECIPIENT (for self collection shipment from office)
$recipientArray = array(
   'privatePerson' => true,
   'pickupOfficeId' => 77 // VARNA - OFFICE. The 'pickupOfficeId' can be obtained from the result of a Find Office Request.
);


#-> III. SERVICE DETAILS
$serviceArray = array(
   'pickupDate' => date('Y-m-d'),
   'serviceIds' => array(505) // The 'serviceId' list can be obtained from the result of a Destination Services Request.
);

#-> Additional services
/* Cash on delivery - Not mandatory */
$cashOnDeliveryArray = array(
   'amount' => 100,
   'processingType' => 'CASH' // (CASH, POSTAL_MONEY_TRANSFER)
);

/* Options before payment - Not mandatory */
$optionsBeforePaymentArray = array(
   'option' => 'OPEN', 
   'returnShipmentServiceId' => 505, 
   'returnShipmentPayer' => 'SENDER' // (SENDER, RECIPIENT, THIRD_PARTY). The sender of the returning shipment is the recipient of the primary shipment.
);
/* 
'returnShipmentServiceId' is the service for the returning shipment in case the recipient refuses to accept the primary shipment. 
It can be the same serviceId as in the primary shipment or one obtained from the result of a Destination Services Request.
*/

/* Declared value - Not mandatory */
$declaredValueArray = array(
   'amount' => 100, 
   'fragile' => true 
);

/* Additional services */
$additionalServicesArray = array(
   'cod' => $cashOnDeliveryArray,
   'obpd' => $optionsBeforePaymentArray,
   'declaredValue' => $declaredValueArray
);

/* Add additional services to the main service array */
$serviceArray['additionalServices'] = $additionalServicesArray;


#-> IV. CALCULATION CONTENT OF THE PARCEL
$contentsArray = array(
   'parcelsCount' => 1,
   'totalWeight' => 0.6
);


#-> V. PAYMENTS
$paymentsArray = array(
   'courierServicePayer' => 'RECIPIENT' // (SENDER, RECIPIENT, THIRD_PARTY)
);


#-> VI. JSON DATA.
$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'sender' => $senderArray, // You can skip the sender data. In this case the sender will be the default one for the username with all the address and contact information.
   'recipient' => $recipientArray,
   'service' => $serviceArray,
   'content' => $contentsArray,
   'payment' => $paymentsArray
);



#-> Calculate Request
$jsonResponse = apiRequest(SPEEDY_API_BASE_URL.'calculate/', $jsonData);
$jsonResponse = json_decode($jsonResponse, true);

#-> Print the result
print_r($jsonResponse);

Track Request examples
For testing purposes, please use the provided bills of lading: 299999990, 299999991, 299999992. View API documentation

#-> Example 1. Track a parcel.
$parcelsArray = array(
   array('id' => 299999990)
);

$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'parcels' => $parcelsArray
);


#-> Example 2. Track a parcel and return only last operation.
$parcelsArray = array(
   array('id' => 299999990)
);

$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'parcels' => $parcelsArray,
   'lastOperationOnly' => true
);


#-> Example 3. Track more than one parcels with one request.
$parcelsArray = array(
   array('id' => 299999990),
   array('id' => 299999991),
   array('id' => 299999992)
);

$jsonData = array(
   'userName' => SPEEDY_API_USERNAME,
   'password' => SPEEDY_API_PASSWORD,
   'language' => LANGUAGE,
   'parcels' => $parcelsArray
);

#-> Track parcel Request
$jsonResponse = apiRequest(SPEEDY_API_BASE_URL.'track/', $jsonData);
$jsonResponse = json_decode($jsonResponse, true);


#-> Print the result
print_r($jsonResponse);

Define address examples.
The address structure is used to provide addresses. Addresses are two types:
- Address type 1 (local addresses - currently supported by Romania and Bulgaria);
- Address type 2 (foreign addresses - all non-local countries);
'addressType' property obtained from the result of a Find Country Request

When address is required (i.e. when clientId is null), the following rule must be met:
not empty street (streetId or type&name) and (streetNo or blockNo)
or
not empty complex (complexId or type&name) and (streetNo or blockNo)
or
not empty poi (poiId)
or
all components of the address within the site stored in addressNote.

If the addressType is 1 and 'addressNomenclature' property for the site is 1 or 2, you should try to define the address using ids of site, street, complex etc.
or by exact match from 'complexType' and 'complexName' or/and by exact match from 'streetType' and 'streetName'.
When the address is well defined via ids or/and matches it will be processed automatically.
Otherwise the address will be placed in the 'addressNote' property. It will not be processed automatically and there are probabilities for mistakes and delay of the delivery.

#-> Example 1. Defined address via ids (the 'addressType' property has a value 1 and 'addressNomenclature' property of the site has value 1 or 2).
$recipientAddressArray = array(
   'countryId' => 100, // BULGARIA. The 'countryId' can be obtained from the result of a Find Country Request.
   'siteId' => 68134, // SOFIA. The 'siteId' can be obtained from the result of a Find Site Request.
   'complexId' => 29, // A complex named 'KRASNA POLYANA 3'. The 'complexId' can be obtained from the result of a Find Complex Request.
   'streetId' => 3109, // A street named 'USTA GENCHO'. The 'streetId' can be obtained from the result of a Find Street Request.
   'streetNo' => '1A',
   'blockNo' => '301',
   'entranceNo' => '2',
   'floorNo' => '3',
   'apartmentNo' => '4'
);


#-> Example 2. An address defined by exact match from 'siteType' and 'siteName' exact match from 'streetType' and 'streetName' (the 'addressType' property has a value 1 and 'addressNomenclature' property of the site has value 1 or 2).
$recipientAddressArray = array(
   'countryId' => 100, // BULGARIA. The 'countryId' can be obtained from the result of a Find Country Request. 
   'siteType' => 'gr.', // The 'siteType' can be obtained from the result of a Find Country Request.
   'siteName' => 'SOFIA', 
   'streetType' => 'ul.', // The 'streetType' can be obtained from the result of a Find Country Request.
   'streetName' => 'USTA GENCHO', // The 'streetName' can be obtained from the result of a Find Street Request.
   'streetNo' => '1A'
);
/* 
If there is exact match from 'siteType' and 'siteName', the id of the site will be added automatically. 
If there is exact match from 'streetType' and 'streetName', the id of the street will be added automatically. 
If there is not exact match from 'streetType' and 'streetName' the address will be placed in the 'addressNote' property.
*/


#-> Example 3. An address defined by ids of the site and the complex, and an exact match between 'streetType' and 'streetName' (the 'addressType' property has a value 1 and 'addressNomenclature' property of the site has value 1 or 2).
$recipientAddressArray = array(
   'countryId' => 100, // BULGARIA. The 'countryId' can be obtained from the result of a Find Country Request. 
   'siteId' => 68134, // SOFIA. The 'siteId' can be obtained from the result of a Find Site Request.
   'complexId' => 29, // A complex named 'KRASNA POLYANA 3'. The 'complexId' can be obtained from the result of a Find Complex Request.
   'streetType' => 'ul.', // The 'streetType' can be obtained from the result of a Find Country Request.
   'streetName' => 'USTA GENCHO', // The 'streetName' can be obtained from the result of a Find Street Request.
   'streetNo' => '1A'
);
/* 
If there is exact match from 'streetType' and 'streetName', the id of the street will be added automatically. 
If there is not exact match from 'streetType' and 'streetName' the address will be placed in the 'addressNote' property.
*/


#-> Example 4. An address defined by exact match from 'complexType' and 'complexName' or/and exact match from 'streetType' and 'streetName' (the 'addressType' property has a value 1 and 'addressNomenclature' property of the site has value 1 or 2).
$recipientAddressArray = array(
   'countryId' => 100, // BULGARIA. The 'countryId' can be obtained from the result of a Find Country Request. 
   'siteId' => 68134, // SOFIA. The 'siteId' can be obtained from the result of a Find Site Request.
   'complexType' => 'zhk', // 'complexType' can be obtained from the result of a Find Country Request.
   'complexName' => 'KRASNA POLYANA 3', // The 'complexName' can be obtained from the result of a Find Complex Request.
   'streetType' => 'ul.', // The 'streetType' can be obtained from the result of a Find Country Request.
   'streetName' => 'USTA GENCHO', // The 'streetName' can be obtained from the result of a Find Street Request.
   'streetNo' => '1A'
);
/*
If there is exact match from 'complexType' and 'complexName', the id of the complex will be added automatically. 
If there is exact match from 'streetType' and 'streetName', the id of the street will be added automatically.
If there are not exact matches, the address will be placed in the 'addressNote' property.
*/


#-> Example 5. An address defined by 'siteId' and exact match from 'streetType' and 'streetName'.
$recipientAddressArray = array(
   'countryId' => 100, // BULGARIA. The 'countryId' can be obtained from the result of a Find Country Request. 
   'siteId' => 68134, // SOFIA. The 'siteId' can be obtained from the result of a Find Site Request.
   'streetType' => 'ul.', // The 'streetType' can be obtained from the result of a Find Country Request.
   'streetName' => 'USTA GENCHO', // The 'streetName' can be obtained from the result of a Find Street Request.
   'streetNo' => '1A'
);
/* 
If there is exact match from 'streetType' and 'streetName', the id of the street will be added automatically. 
If there is not exact match, the address will be placed in the 'addressNote' property.
*/


#-> Example 6. The address defined by 'poiId' and some additional info filled in the 'addressNote'.
$recipientAddressArray = array(
   'countryId' => 100, // BULGARIA. The 'countryId' can be obtained from the result of a Find Country Request. 
   'siteId' => 68134, // SOFIA. The 'siteId' can be obtained from the result of a Find Site Request.
   'poiId' => 68134000483088, // NATIONAL ART GALLERY. The 'poiId' can be obtained from the result of a Find POI Request.
   'addressNote' => '2nd floor, office 201'
);


#-> Example 7A. The whole address is placed in the 'addressNote' field. It will be not processed automatically and there are probabilities for mistakes and delay of the delivery.
$recipientAddressArray = array(
   'countryId' => 100, // BULGARIA. The 'countryId' can be obtained from the result of a Find Country Request. 
   'siteId' => 68134, // SOFIA. The 'siteId' can be obtained from the result of a Find Site Request.
   'addressNote' => 'ul. USTA GENCHO, No.1A, bl.301, ent.2, fl.3, ap.4' 
);


#-> Example 7B. The whole address is placed in the 'addressNote' field. It will be not processed automatically and there are probabilities for mistakes and delay of the delivery.
$recipientAddressArray = array(
   'countryId' => 100, // BULGARIA. The 'countryId' can be obtained from the result of a Find Country Request. 
   'siteType' => 'gr.', // The 'siteType' can be obtained from the result of a Find Country Request.
   'siteName' => 'SOFIA', 
   'addressNote' => 'ul. USTA GENCHO, No.1A, bl.301, ent.2, fl.3, ap.4' 
);
/* 
If there is exact match from 'siteType' and 'siteName', the id of the site will be added automatically. 
*/


#-> Example 7C. The whole address is placed in the 'addressNote' field. It will be not processed automatically and there are probabilities for mistakes and delay of the delivery.
$recipientAddressArray = array(
   'countryId' => 100, // BULGARIA. The 'countryId' can be obtained from the result of a Find Country Request. 
   'siteName' => 'SOFIA', 
   'postCode' => 1330, 
   'addressNote' => 'ul. USTA GENCHO, No.1A, bl.301, ent.2, fl.3, ap.4' 
);
/* 
If there is exact match from 'siteName' asd 'postCode', the id of the site will be added automatically. 
*/


#-> Example 8. A foreign address (the addressType property has a value 2).
$recipientAddressArray = array(
   'countryId' => 276, // GERMANY. The 'countryId' can be obtained from the result of a Find Country Request. 
   'siteName' => 'MUNICH', 
   'postCode' => 80001, // Depends from the 'postCodeFormats' property from the result of a Find Country Request. It shows the required post code format. 
   'addressLine1' => 'Some complex, some street name, No.1', // Required for 'addressType' 2
   'addressLine2' => 'Some additional address note' /* Not mandatory */
);