Введение

API интерфейс используется для того, чтобы интегрировать возможности курьерского сервиса GarantBox. API предназначен для разработчиков и сопровождается детальной документацией.

Также в сервисе доступны извещения. Если хотите активировать их, укажите адрес обращения в конфигурации API.

Авторизация

Процесс авторизации возможен при наличии персонального ключа, которым в дальнейшем должен быть подписан каждый запрос к API.

Создать новый ключ Вы можете в настройках личного кабинета

Запросы отправляются по ссылке указанной ниже

https://khb.garantbox.ru/api/v1/_TOKEN_/command

Методы

Получение данных о заказах

Для получения списка заказов отправляется запрос по ссылке

https://khb.garantbox.ru/api/v1/_TOKEN_/getOrders

Параметры запроса
order_id[] Array or Integer Да Номер заказа или список
mode Integer Нет 0 - боевой режим (По умолчанию);
1 - тестовый режим.
Пример запроса
https://khb.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"
          }
        ]
      }
    }
  }
}
Пример ошибки

Все коды ошибок вы можете посмотреть в разделе обработка ошибок

Структура ответа result.orders[id]
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://khb.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://khb.garantbox.ru/api/v1/_TOKEN_/settings
Пример ошибки

Все коды ошибок вы можете посмотреть в разделе обработка ошибок

Структура ответа result
Сохранение настроек

Для сохранения настроек отправляется POST с выданными данными запрос указанный выше

Пример отправки данных
{
  "street": "ул. Тверская",
  "house": "дом 12",
  "apr": ""
}

Создание заказа

Для создания заказа отправляется запрос по ссылке

https://khb.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
  }
}
Пример ошибки

Все коды ошибок вы можете посмотреть в разделе обработка ошибок

Структура ответа result
order_id Integer Номер заказа

Отмена заказа

Для отмены заказа отправляется запрос по ссылке

https://khb.garantbox.ru/api/v1/_TOKEN_/cancelOrders

Параметры запроса
order_id[] Array or Integer Да Номер заказа или список
mode Integer Нет 0 - боевой режим (По умолчанию);
1 - тестовый режим.
Пример запроса
https://khb.garantbox.ru/api/v1/_TOKEN_/cancelOrders/?order_id=10065
Пример успешного ответа
{
  "status": "success",
  "result": [
    "10065"
  ]
}
Пример ошибки

Все коды ошибок вы можете посмотреть в разделе обработка ошибок

Структура ответа result
[order_id] String Номер заказа

Расчет заказа

Для расчета заказа отправляется запрос по ссылке

https://khb.garantbox.ru/api/v1/_TOKEN_/calcOrder

Параметры запроса

Аналогичные параметры команды createOrder

Пример успешного ответа
{
  "status": "success",
  "result": {
    "account_balance": 1770,
    "account_packages": 40,
    "pay_balance": 270,
    "pay_packages": 2
  }
}
Пример ошибки

Все коды ошибок вы можете посмотреть в разделе обработка ошибок

Структура ответа result
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
API GarantBox для разработчиков