API интерфейс используется для того, чтобы интегрировать возможности курьерского сервиса GarantBox. API предназначен для разработчиков и сопровождается детальной документацией.
Также в сервисе доступны извещения. Если хотите активировать их, укажите адрес обращения в конфигурации API.
Процесс авторизации возможен при наличии персонального ключа, которым в дальнейшем должен быть подписан каждый запрос к API.
Создать новый ключ Вы можете в настройках личного кабинета
Запросы отправляются по ссылке указанной ниже
https://garantbox.ru/api/v1/_TOKEN_/command
Для получения списка заказов отправляется запрос по ссылке
https://garantbox.ru/api/v1/_TOKEN_/getOrders
order_id[] | Array or Integer | Да | Номер заказа или список |
---|---|---|---|
mode | Integer | Нет | 0 - боевой режим (По умолчанию); 1 - тестовый режим. |
https://garantbox.ru/api/v1/_TOKEN_/getOrders/?order_id[]=10983&order_id[]=11024
{ "status": "success", "result": { "orders": { "9958": { "cargo": "Груз", "cost": 420, "cargo_insured": 0, "payment_method": 0, "card_number": "0000-000000-00000", "status": 100, "addresses": [ { "address": "ул. Тверская, дом 12", "metro": "Тверская", "contact_number": "(+7) 999 999-99-99", "time_from": "2018-05-04 16:48:57", "time_to": "2018-05-04 17:48:57" }, { "address": "ул. Вяземская, дом 5", "metro": "Молодёжная", "contact_number": "(+7) 999 999-99-99", "time_from": "2018-05-04 16:48:57", "time_to": "2018-05-04 17:48:57" } ] }, "10208": { "cargo": "Груз", "cost": 420, "cargo_insured": 0, "payment_method": 0, "card_number": "0000-000000-00000", "status": 100, "addresses": [ { "address": "ул. Тверская, дом 12", "metro": "Тверская", "contact_number": "(+7) 999 999-99-99", "time_from": "2018-05-04 16:48:57", "time_to": "2018-05-04 17:48:57" }, { "address": "ул. Вяземская, дом 5", "metro": "Молодёжная", "contact_number": "(+7) 999 999-99-99", "time_from": "2018-05-04 16:48:57", "time_to": "2018-05-04 17:48:57" } ] } } } }
Все коды ошибок вы можете посмотреть в разделе обработка ошибок
cargo | String | Предмет доствки. Документы, подарки, коробки, цветы, посылки. |
---|---|---|
cost | Float | Стоимость заказа |
cargo_insured | Float | Сумма страховки груза |
payment_method | Integer | Способ оплаты 0 - лицевой счет (По умолчанию), 1 - пакет, 2 - при отправке, 3 - при получении, 4 - на карту. |
card_number | String | Номер карты для перевода курьером |
status | Integer | Статус заказа. 0 - на проверке, 1 - курьер назначен, 100 - выполнен, -999 - отменен |
addresses[i].address | String | Адрес. Улица и дом |
addresses[i].metro | String | Ближайшее метро от указанного адреса |
addresses[i].contact_number | String | Контактный телефон адреса |
addresses[i].time_from | String | Дата и время прибытия (от) курьера на адрес Формат даты: Y-m-d H:i:s |
addresses[i].time_to | String | Дата и время прибытия (до) курьера на адрес Формат даты: Y-m-d H:i:s |
Для получение списка доступных настроек отправляется запрос по ссылке
Обратите внимание, что настройки могут быть добавлены.
https://garantbox.ru/api/v1/_TOKEN_/settings
street | text | Нет | Улица Улица начального адреса |
---|---|---|---|
house | text | Нет | Дом Дом начального адреса |
apr | text | Нет | Квартира\офис Квартира\офис начального адреса |
plus_min_from | text | Нет | Плюс от Добавить время (в минутах) от текущего (промежуток от) |
plus_min_to | text | Нет | Плюс до Добавить время (в минутах) от текущего (промежуток до) |
contact_name | text | Нет | Контактное лицо Контактное лицо начального адреса |
amount_money | text | Нет | Сумма перевода Укажите сумма перевода |
redemption_amount | text | Нет | Сумма выкупа Укажите сумма выкупа |
tel | text | Нет | Телефон Телефон начального адреса |
comment | text | Нет | Комментарий Комментарий начального адреса |
use_start_address | checkbox | Нет | Использовать указанные данные как адрес откуда (забора) 1 - использовать 0 - не использовать |
webhook | text | Нет | Ссылка для получения извещений URL адрес для получения уведомлений о событиях |
https://garantbox.ru/api/v1/_TOKEN_/settings
Все коды ошибок вы можете посмотреть в разделе обработка ошибок
errors | Array | Массив ошибок |
---|---|---|
settings | Array | Массив сохраненных настроек |
Для сохранения настроек отправляется POST с выданными данными запрос указанный выше
{ "street": "ул. Тверская", "house": "дом 12", "apr": "" }
Для создания заказа отправляется запрос по ссылке
https://garantbox.ru/api/v1/_TOKEN_/createOrder
mode | Integer | Нет | Режим 0 - боевой режим (По умолчанию); 1 - тестовый режим; |
---|---|---|---|
type_delivery | Integer | Нет | Тип доставки 0 - пешая доставка (По умолчанию); 1 - легковым автомобилем; 2 - грузовым автомобилем; |
is_draft | Integer | Нет | Флаг, является черновиком 0 - автоматическая публикация (По умолчанию); 1 - создать в черновике; |
cargo | String | Да | Предмет доставки |
cargo_weight | Integer | Да | Вес груза, кг |
cargo_insured | Integer | Нет | Страховка груза Ценность застрахованного груза |
payment_method | Integer | Нет | Способ оплаты 0 - лицевой счет (По умолчанию), 1 - пакетами, 2 - при отправке, 3 - при получении. |
card_number | String | Нет | Номер карты Номер карты для перевода |
services | Array | Нет | Дополнительные услуги 1 - Покупка товаров курьером; 2 - Доставка без оформления квитанции; 3 - Сдача налоговой отчетности и отчетности в госорганах; 4 - Оформление отправления в транспортной компании; 5 - Встреча/отправление поезда/автобуса; 6 - Отправка/получение корреспонденции в отделениях Почты России; 7 - Сделать фото товара; 8 - Сделать фото документа; 9 - Перевод денег курьером на банковскую карту или QIWI кошелек; 10 - Хрупкий груз; 12 - Наличие термосумки; 13 - Выкуп товара курьером; 14 - Крупногабаритный груз от 120-210см ; 15 - Услуги химчистки; |
addresses[i][street] | String | Да | Улица. |
addresses[i][house] | String | Да | Дом, корпус. |
addresses[i][apr] | String | Нет | Квартира/офис |
addresses[i][contact_name] | String | Нет | Имя Контактное лицо на текущем адресе |
addresses[i][amount_money] | String | Нет | Сумма перевода Сумма перевода на текущем адресе |
addresses[i][redemption_amount] | String | Нет | Сумма выкупа Сумма выкупа на текущем адресе |
addresses[i][contact_number] | Integer | Да | Номер телефона Контактный номер на текущем адресе |
addresses[i][order_number] | String | Нет | Номер заказа Внутренний номер заказа |
addresses[i][latitude] | String | Нет | Широта Широта адреса |
addresses[i][longitude] | String | Нет | Долгота Долгота адреса |
addresses[i][time_from] | String | Да | Дата и время прибытия (от) Формат даты: Y-m-d H:i:s |
addresses[i][time_to] | String | Да | Дата и время прибытия (до) Формат даты: Y-m-d H:i:s |
addresses[i][comment] | String | Нет | Комменатрий к заказу Имя или название организации, подъезд, этаж, № домофона, есть ли охрана, нужен ли курьеру пропуск на проходной, требуется ли сдача |
nomenclature[i][product_name] | String | Нет | Наименование Название товара |
nomenclature[i][product_cost] | Integer | Нет | Стоимость Цена товара |
nomenclature[i][product_quantity] | String | Нет | Единицы Количество уникального товара |
nomenclature[i][purchase_value] | String | Нет | Закупочная стоимость Закупочная стоимость товара |
nomenclature[i][product_id] | String | Нет | Идентификатор Идентификатор товара в вашей системе |
{ "status": "success", "result": { "order_id": 99999 } }
Все коды ошибок вы можете посмотреть в разделе обработка ошибок
order_id | Integer | Номер заказа |
---|
Для отмены заказа отправляется запрос по ссылке
https://garantbox.ru/api/v1/_TOKEN_/cancelOrders
order_id[] | Array or Integer | Да | Номер заказа или список |
---|---|---|---|
mode | Integer | Нет | 0 - боевой режим (По умолчанию); 1 - тестовый режим. |
https://garantbox.ru/api/v1/_TOKEN_/cancelOrders/?order_id=10065
{ "status": "success", "result": [ "10065" ] }
Все коды ошибок вы можете посмотреть в разделе обработка ошибок
[order_id] | String | Номер заказа |
---|
Для расчета заказа отправляется запрос по ссылке
https://garantbox.ru/api/v1/_TOKEN_/calcOrder
Аналогичные параметры команды createOrder
{ "status": "success", "result": { "account_balance": 1770, "account_packages": 40, "pay_balance": 270, "pay_packages": 2 } }
Все коды ошибок вы можете посмотреть в разделе обработка ошибок
account_balance | Integer | Остаток на лицевом счете |
---|---|---|
account_packages | Integer | Остаток адресов |
pay_balance | Integer | К оплате из лицевого счета |
pay_packages | Integer | К оплате из пакетов адресов |
Вам отправляются автоматические извещения об изменениях. Информация об изменениях отправляется с помощью POST-запроса в формате json на сайт указанный в настройках, параметр webhook.
Отправляется событие attached_courier при назначении курьера на ваш заказ.
{ "event": "attached_courier", "signature": "9c2ff1096f4afb49ff226564243fbaa7d994c8c3", "order_id": 10208, "order_id_client": 348640, "order_id_courier": 640, "action": "COURIER_APPOINTED", "courier": { "name": "Иван Иванов", "phone": "79999999999" } }
event | String | Имя извещения |
---|---|---|
signature | String | Цифровая подпись, token зашифрованный через sha1 Для подтверждения данных |
order_id | Integer | Номер заказа |
order_id_client | Integer | Номер заказа для клиента |
order_id_courier | Integer | Номер заказа для курьера |
action | String | Ключ действия, можно найти в разделе ключи действий |
courier[name] | String | Имя нового курьера |
courier[phone] | String | Номер телефона нового курьера |
Отправляется событие receipt с данными о файле квитанции в формате PDF.
{ "event": "receipt", "signature": "9c2ff1096f4afb49ff226564243fbaa7d994c8c3", "order_id": 10208, "order_id_client": 348640, "order_id_courier": 640, "action": "COURIER_APPOINTED", "file": { "name": "receipt", "url": "FILE_PATH" } }
event | String | Имя извещения |
---|---|---|
signature | String | Цифровая подпись, token зашифрованный через sha1 Для подтверждения данных |
order_id | Integer | Номер заказа |
order_id_client | Integer | Номер заказа для клиента |
order_id_courier | Integer | Номер заказа для курьера |
action | String | Ключ действия, можно найти в разделе ключи действий |
file[name] | String | Имя файла |
file[url] | String | Ссылка на файл |
Отправляется событие change_order при назначении курьера на ваш заказ.
{ "event": "change_order", "signature": "9c2ff1096f4afb49ff226564243fbaa7d994c8c3", "order_id": 10208, "order_id_client": 348640, "order_id_courier": 640, "action": "COURIER_APPOINTED", "data": {} }
event | String | Имя извещения |
---|---|---|
signature | String | Цифровая подпись, token зашифрованный через sha1 Для подтверждения данных |
order_id | Integer | Номер заказа |
order_id_client | Integer | Номер заказа для клиента |
order_id_courier | Integer | Номер заказа для курьера |
action | String | Ключ действия, можно найти в разделе ключи действий |
data | Array | Массив данных повротяющий информацию структуры getOrders |
Таблицы ключей и идентификаторов
Ключ | Значение |
---|---|
COURIER_ARRIVED_ADDRESS_SENDING | Курьер прибыл на адрес забора |
COURIER_TAKEN_CARGO | Курьер забрал груз |
COURIER_SEND_ADDRESS_DELIVERY | Курьер отправился на адрес доставки |
COURIER_ARRIVED_ADDRESS_DELIVERY | Курьер прибыл на адрес доставки |
COURIER_TRANSFERS_CARGO | Курьер доставил груз |
ORDER_CREATE_BY_CLIENT | Заказ создан клиентом |
ORDER_CREATE_BY_OPERATOR | Заказ создан оператором |
Идентификатор | Название региона |
---|---|
77 | Москва |
78 | Санкт-Петербург |
38 | Иркутск |
74 | Челябинск |
27 | Хабаровск |
100 | Минск |
При работе с API будут ошибки, и они должны быть корректно обработаны.
Содержит информацию об ошибке.
{ "status": "fail", "error_code": 500, "error_message": "bad request" }
Обратите внимание, что текст ошибки может быть изменен, поэтому следует избегать привязки логики приложения к этим сообщениям.
Код ошибки | Описание |
---|---|
200 | Invalid token key |
201 | Unknow token key |
202 | Unknow command |
203 | Wrong data |
204 | A technical error |
310 | Enter only available orders |
320 | Unknown parameter |
321 | Important values are missing |
322 | Invalid value format |
323 | Insufficient funds on the account |
324 | Could not create an order |
325 | The courier has already been assigned, or the order is completed or canceled |
326 | In the order of less than two addresses |
327 | Inaccessible additional service |
328 | Too short time selected |
329 | Too short a time, at least 30 minutes |
330 | Too long, up to 23 hours |
331 | Tariff does not exist or is not available |
500 | Bad request |
501 | Too many requests |
502 | Not authorized |
599 | Blocked access to api |