Tailor Made

Преди да започнете

Стъпка 1: Първи стъпки

OAUTH_CLIENT_ID

Пазете този „ключ“ на безопасно място! Това е Вашият OAuth2 Client ID, който ще ползвате, за да достъпите нашият API за партньори.

OAUTH_CLIENT_SECRET

Пазете този „ключ“ на безопасно място! Това е Вашият OAuth2 Client Secret, който ще ползвате, за да достъпите нашият API за партньори.

API_URL

Това е уеб-адрес основа, към който ще пращате Вашите заявки, добавяйки различните API endpoints.

Стъпка 2: Среда за разработка

Тестова

Това е тестова среда, с ограничена функционалност, желателно е да я ползвате, за да тествате Вашата интеграция.

Продукция

Използвайте тази среда като внимавате изключително много! Защото е реална и е свързана с реални клиенти, заявки и други напълно реални данни.

Стъпка 3: Заявка за доставка

Следвайте тези стъпки, за да можете успешно да направите заявка за доставка и да ползвате прилежащите функции:

3.1 Автентификация

Автентификацията е базирана на OAuth 2.0 стандарта, Client Credentials grant.

За да ползвате нашият API, е ЗАДЪЛЖИТЕЛНО да добавите токена за достъп, към т.нар. „Authorization header“ като „Bearer“ токен.

Вижте пример с успешна имплементация:

POST /api/v1/ auth sessions

{

"grant_type”: "client_credentials”,

"client_id": “string”,

"client_secret": “string”

}

Status Code 200

{

"access_token”: “client_credentials”,

"token_type": “Bearer”,

"expires_in”: 3600

}

Възможни отговори от сървъра:

400

Сървърът не може или няма да обработи заявка, която е грешна (Пример: грешен синтаксис, грешна заявка към сървъра). Необходимо е да промените заявката, преди да я изпратите отново.

401

Не сте се удостоверили. Най-вероятно използвате изтекъл токен за достъп или се опитвате да инициализирате сесия за автентификация с грешни / невалидни данни.

403

Акаунтът Ви е деактивиран. Вашият акаунт е бил деактивиран, моля свържете се с поддръжката за съдействие.

3.2 Списък с всички складове /origins

Извикването на /origins ще ни покаже списък с всички налични локации за взимане на пратка от наша страна (PUP - PickUpPoint), тоест Ваш склад, магазин или друго място, от което ние ще вземем пратките.

Всичките Ваши складове ще бъдат показани с извикването на /origins, който има същите параметри като извикването на /destinations , където не е нужно да се ползват параметрите „lat“, „lng“, “radius“ или „requiredSize“, но се подава параметъра „locationType“ с примерна стойност: „warehouse“. За да достъпите дадена локация, то е нужно да я извиквате с помощта на нейното ID (locationId).

Има и една специфична локация, наречена „any-apm“, която може да бъде извикана по същия начин - „locationType“ като “any-apm” ни връща точно една локация – any-apm. За да я реферирате, е нужно да ползвате ID (locationId). Употребата й ще бъде обяснена в следващата секция.

Това е набора от параметри, даден Ви, за да изведете определена начална локация:

Вижте пример с успешна имплементация:

GET /api/v1/ origins

curl -X ‘GET’\

'…/origins\

-H 'accept: application/json’

Status Code 200

{

"data": [

{

"id": "string",

"type": "warehouse",

"image": "https://via.placeholder.com/175",

"lat": "48.940819584637266",

"lng": "12.366962491028423",

"title": "Warehouse 1",

"name": "Main Warehouse",

"addressLine1": "ul.Tsar Boris III",

"addressLine2": "Sofia",

"postalCode": "1000",

"country": "BG",

"note": "Намира се на ъгъла до супермаркета"// can be null

}

]

}

Възможни отговори от сървъра:

Код на грешката

400

Сървърът не може или няма да обработи заявка, която е грешна (Пример: грешен синтаксис, грешна заявка към сървъра). Необходимо е да промените заявката, преди да я изпратите отново.

401

Не сте се удостоверили. Най-вероятно използвате изтекъл токен за достъп или се опитвате да инициализирате сесия за автентификация с грешни / невалидни данни.

403

Акаунтът Ви е деактивиран. Вашият акаунт е бил деактивиран, моля свържете се с поддръжката за съдействие.

3.3. Списък с локациите на всички автомати /destinations

Извикването на /destinations ще ни изведе списък с всички налични автомати, до които ние можем да доставим Вашата пратка.

По-долу са показани параметрите, по които можете да филтрирате нужната Ви локация сред всички налични локации:

Вижте пример с успешна имплементация:

GET api/v1/ destinations

curl X ‘GET’\

‘.../destinations\

-H 'accept: application/json'

Status Code 200

{

"data": [

{

"id": "string",

"type": "apm",

"image": "https://via.placeholder.com/150",

"lat": "48.78081955454138",

"lng": "12.446962472273063",

"title": "1842 - Building SIVEN, Hladilnika",

"name": "1842 - бул. Черни връх №47А, София, 1407",

"addressLine1": "bul. Cherni Vrah 47A",

"addressLine2": "string",

"postalCode": "1407",

"country": "BG",

"note": "Намира се зад зоомагазина"

}

]

}

Моля направете справка със секция номер 4 за пример с JavaScript, който можете да вградите към Вашите страници, за да Ви се покажат всички налични автомати чрезизкачащ т.е. pop-up / iframe уиджет, или като насока за успешна интеграция с изработена от Вас карта.

id

Когато заявявате доставка, ще бъде нужно да реферирате всички тези записи, по тяхното id – най-вече чрез: locationId:

locationId

Възможни отговори от сървъра:

Error Code

400

Сървърът не може или няма да обработи заявка, която е грешна (Пример: грешен синтаксис, грешна заявка към сървъра). Необходимо е да промените заявката, преди да я изпратите отново.

401

Не сте се удостоверили. Най-вероятно използвате изтекъл токен за достъп или се опитвате да инициализирате сесия за автентификация с грешни / невалидни данни.

403

Акаунтът Ви е деактивиран. Вашият акаунт е бил деактивиран, моля свържете се с поддръжката за съдействие.

3.4 Заявка за доставка /delivery-requests

Чрез /delivery-request ще изпратите заявка към нас, да доставим пратка (или множество пратки). Това е основното „запитване“, което ще ползвате, за да създавате какъвто и да било тип заявка за доставка.

Когато е направена успешна заявка за доставка:

• (опционално) Ще Ви изпратим имейл с потвърждение за успешна заявка за доставка, с товарителница в PDF формат, която ще бъде прикачена в съобщението. За да се случи това обаче е нужно да използвате параметъра notifyOnAccepted (Моля вижте Приложение 6.3).
• (Описан по-долу) Друг вариант е да генерирате товарителница в PDF формат за всяка Ваша пратка, използвайки: GET /parcels/{id}/label.pdf, която ще разпечатате и залепите към пратката.
• Ние ще Ви изпратим куриер, който да вземе пратката (пратките) спрямо предварително договореното време за взимане.
• Ние също така ще уведомим крайният клиент за следното:

1. Че сме получили заявка за доставка от Вас и че пратката ще им бъде доставена в избран от Вас автомат.
2. Че сме занесли пратка им до избрания автомат с всички нужни данни за взимане на пратката.

Вижте пример с успешна имплементация:

POST api/v1/ delivery requests

{

"orderNumber": “string”,

"invoiceValue": “25.50”,

"paymentMode":”prepaid”,

”amountToBeCollected": “0.00",

"allowReturn”: true,

"origin”:{

"contactNumber":“+3598XXXXXXXX”,

"contactEmail”: “[email protected]”,

"contactName": “Ivan Ivanov",

"locationId":”string”

},

“destination”:{

"contactNumber": "+3598XXXXXXXX”,

"contactEmail”: “[email protected]”,

"contactName” "Ivan Petrov",

"locationId":”string”

},

"items”: [

{

"id": “string”,

"name": “Smartphone”

"value”: “3.45”,

"weight”: 0

}

]

}

items: weight

Ако не знаете теглото на пратката, моля задайте стойност 0.

Тези параметри са основните индентификатори на местата за взимане на пратката и на местата за оставяне на пратка:

Начална точка: locationId

Склада, от който ние ще вземем пратката.

Крайна точка: locationId

Автомат - мястото, на което пратката ще бъде доставена от нас.

Също така, моля не забравяйте да подадете следните параметри с всяка заявка.

Sender:

1. Име на подател

Recipient:

1. Име на получател
2. Телефонен номер
3. Имейл адрес

Status Code 200

{

"referenceNumber":”string”,

"parcels”:[

{

"id":”string”

}

]

}

ВНИМАНИЕ: В горния пример масива “items” съответства на пратки, но „item ID“ е уникален индентификатор за самия електронен магазин (приемете го като важен референтен номер). Ако нямате уникално ID за всяка пратка, то в такъв случай е необходимо да го създадете като към номер на поръчката добавите поредния номер на всяка пратка във възходящ ред или можете да го генерирате по друг начин, но идеята е да подадете уникален номер. А т.нар. ID на пратката/„parcel ID“ (parcels: id) е вътрешен и уникален за BOX NOW - ID номер.

Ако желаете да изпратите пратка чрез автомат, можете да използвате “any-APM” за начална точка и определен автомат като крайна точка.

Ако лично ще оставите пратката до същият АПС, от който крайният клиент ще си вземе тази пратка, то тогава ползвате „any-APM“ като начална точка, но и като крайна точка.

Възможни отговори от сървъра:

Код на грешката

400

Сървърът не може или няма да обработи заявка, която е грешна (Пример: грешен синтаксис, грешна заявка към сървъра). Необходимо е да промените заявката, преди да я изпратите отново.

401

Не сте се удостоверили. Най-вероятно използвате изтекъл токен за достъп или се опитвате да инициализирате сесия за автентификация с грешни / невалидни данни.

403

Акаунтът Ви е деактивиран. Вашият акаунт е бил деактивиран, моля свържете се с поддръжката за съдействие.

3.5 Генериране на товарителница /parcels/{id}/label.pdf

Използвайте тази заявка, за да създадете товарителница в .pdf формат или .zpl формат, която трябва задължително да се залепи към всяка пратка.

Това са параметрите, които може да подадете:

    
<div id="boxnowmap"></div>
    
<script type="text/javascript">
    
var _bn_map_widget_config = {
    
partnerId: 123,
    
parentElement: "#boxnowmap"
    
afterSelect: function(selected){
    
alert(selected.boxnowLockerPostalCode);
    
    
alert(selected.boxnowLockerAddressLine1);
    
    
alert(selected.boxnowLockerId);

    
    
}
    
};
    
    
(function(d){var e = d.createElement("script");e.src = "https://widget-cdn.boxnow.bg/map-widget/client/v5.js";e.async = true;e.defer = true;d.getElementsByTagName("head")[0].appendChild(e);})(document);</script>

	

<div id="boxnowmap"></div>