API курьерской службы «Рултек»

1Общие сведения

Адреса в этом документе указаны относительно базового: полный путь создания заказа — https://api.rultek.ru/api/external/server/orders.

Заголовок Accept: application/json обязателен. Без него ошибки валидации возвращаются HTML-страницей вместо JSON.

Спецификация OpenAPI 3.0 — импортируется в Postman и подходит для генерации клиента.

2Аутентификация

Каждый запрос сопровождается заголовком:

Authorization: Bearer <ваш токен>

Токен выдаёт администратор «Рултек» для учётной записи вашей компании. Токен постоянный: срока действия не имеет, продления не требует, процедуры входа в этом интерфейсе нет.

• Токен равнозначен паролю. Храните его в защищённом хранилище, не публикуйте в репозитории и не передавайте по открытым каналам.
• Повторная выдача отзывает предыдущий токен. Старый перестанет работать немедленно, и интеграция встанет до замены значения.
• Компания определяется токеном. Указывать её в запросах не нужно, а увидеть чужие заказы по чужим номерам невозможно.

При компрометации токена сообщите менеджеру — мы отзовём его и выдадим новый.

3Соглашения

Дата и время

В запросах время передаётся в формате ISO 8601. Указывайте часовой пояс явно:

2026-08-28T09:30:00+03:00

В ответах время приходит строкой ГГГГ-ММ-ДД ЧЧ:ММ:СС по московскому времени.

Денежные значения

Все суммы — целые числа в рублях. Порядок налогообложения определяется вашим договором.

Коды ответов

Формат ошибок

Ошибки валидации приходят в стандартном виде, ключи в errors соответствуют именам полей запроса:

{
  "message": "Номер заказа: ожидается вид R000000000.",
  "errors": {
    "order": ["Номер заказа: ожидается вид R000000000."]
  }
}

Остальные ошибки содержат только message.

4Нумерация

Обычный заказ состоит из одной квитанции. Их становится несколько, когда по одному заказу выполняется несколько поездок — подробнее в разделе «Несколько квитанций».

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

Создаёт заказ с одной накладной. Если передать order, накладная станет очередной квитанцией существующего заказа — так объединяются заявки, которые должны быть выполнены одной поездкой.

Формально обязательных полей нет — валидатор пропустит и полупустой запрос. Но заказ без адресов и времени выполнить невозможно, поэтому поля с пометкой «нужное» заполняйте всегда.

Поля верхнего уровня

Адреса

Объекты sender (отправитель) и recipient (получатель) имеют одинаковый набор полей.

Пример запроса

curl -X POST https://api.rultek.ru/api/external/server/orders \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "type_of_delivery": "foot",
    "how_pay": "invoice",
    "visit_time": "2026-08-28T10:00:00+03:00",
    "delivery_time": "2026-08-28T14:00:00+03:00",
    "weight": 0.3,
    "cargo_description": "Пакет документов",
    "remark": "V246-702-458-122",
    "sender": {
      "name": "ООО «Пример»",
      "address": "Москва, ул. Тверская, д. 1",
      "contacts": "Иванова Мария, +7 900 000-00-00",
      "y": 55.757, "x": 37.611,
      "floor": 3, "elevator": true
    },
    "recipient": {
      "name": "АО «Получатель»",
      "address": "Москва, Ленинский пр-т, д. 20",
      "contacts": "Петров Сергей, +7 900 111-11-11",
      "y": 55.712, "x": 37.586
    }
  }'

Ответ

{
  "number": "R000196340-001",   // номер накладной, он же в документах
  "order":  "R000196340"        // номер заказа — для запроса статусов
}

6Статусы и стоимость

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

Параметры

• order и number взаимоисключающие — вместе дают ошибку 422;
• order можно дополнить периодом — вернутся квитанции этого заказа с приездом в эти даты;
• период без номера возвращает все ваши накладные за эти дни;
• период задаётся обеими границами и не может превышать 31 день;
• запрос без единого параметра отклоняется.

Порядок строк: внутри заказа — по номеру квитанции, в выборке по датам — по времени приезда.

Примеры запросов

# все квитанции заказа
curl -G https://api.rultek.ru/api/external/server/orders/status \
  -H "Authorization: Bearer <токен>" -H "Accept: application/json" \
  -d order=R000196340

# конкретная накладная
curl -G https://api.rultek.ru/api/external/server/orders/status \
  -H "Authorization: Bearer <токен>" -H "Accept: application/json" \
  -d number=R000196340-001

# всё, что приезжало за день
curl -G https://api.rultek.ru/api/external/server/orders/status \
  -H "Authorization: Bearer <токен>" -H "Accept: application/json" \
  -d date_from=2026-08-27 -d date_to=2026-08-27

Ответ

{
  "data": [
    {
      "number": "R000196340-001",
      "status": "завершён",
      "remark": "V246-702-458-122",
      "delivery": "Колотур",
      "delivery_time": "2026-08-27 14:56:00",
      "return": "-",
      "return_time": "-",
      "back": "no",
      "type_of_delivery_ab": "бандероль до 5 кг",
      "weight_ab": "4.0",
      "type_of_delivery_ba": "-",
      "weight_ba": "-",
      "price": 1170,
      "waiting": 0,
      "load_unload": 0
    }
  ]
}

Поля ответа

Клиентам, работающим по агентской схеме, дополнительно приходят поля price_base, waiting_base и load_unload_base — базовая стоимость, рекомендованная для расчёта с вашим заказчиком. Если этих полей в ответе нет, схема к вам не применяется.

Как читать значения

Прочерк в текстовом поле означает, что данные ещё не внесены либо не заполняются по характеру услуги: у доставки без возврата поля возврата всегда прочеркнуты.

Стоимость появляется, когда заказ переходит в состояние «завершён», и после этого не меняется — кроме случаев ручной корректировки нашим расчётным отделом.

7Предварительный расчёт

Считает стоимость по маршруту до оформления заказа. Варианты доставки считаются пачкой: один запрос на маршрут вместо отдельного обращения на каждый вид.

Цена рассчитывается по вашей тарифной схеме — той же, по которой потом выставляется счёт. Скидка за объём поездок здесь не применяется: на момент прикидки месяц ещё не набран.

Параметры

Элемент options — либо строка с типом доставки ("foot"), либо объект, где можно задать свои вес и габариты для этого варианта: { "type_of_delivery": "van", "weight": 400 }. За один запрос не более десяти вариантов.

Пример

curl -X POST https://api.rultek.ru/api/external/server/calculate \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "sender":    { "y": 55.757, "x": 37.611 },
    "recipient": { "y": 55.712, "x": 37.586 },
    "weight": 0.3,
    "options": ["foot", "auto"]
  }'

{
  "data": [
    { "type_of_delivery": "пешая", "shipment": "письмо",       "weight": "0.3", "zone": "Москва", "price": 830 },
    { "type_of_delivery": "авто",  "shipment": "автодоставка", "weight": "0.3", "zone": "Москва", "price": 3290 }
  ]
}

Поля ответа

Клиентам на агентской схеме дополнительно приходит price_base — базовая стоимость для их заказчика.

Вид отправления может отличаться от запрошенного: пешая доставка при весе 400 кг будет посчитана как минивен — правила перехода описаны в справочниках.

8Несколько квитанций в одном заказе

Обычно заказ — это одна поездка и одна квитанция -001. Дополнительные квитанции появляются, когда по заказу выполняется несколько поездок:

Пример: ложный приезд и повторный выезд

{
  "data": [
    {
      "number": "R000196340-001",
      "status": "завершён",
      "delivery": "груз не приняли",
      "delivery_time": "2026-08-27 11:20:00",
      "price": 830, "waiting": 0, "load_unload": 0
    },
    {
      "number": "R000196340-002",
      "status": "завершён",
      "delivery": "Колотур",
      "delivery_time": "2026-08-28 14:56:00",
      "price": 830, "waiting": 300, "load_unload": 0
    }
  ]
}

Отсюда два практических следствия:

1. Обрабатывайте ответ как массив. Итоговая стоимость по заказу — сумма всех строк.
2. Опрашивайте по номеру заказа, а не накладной. Запрос по order покажет все квитанции, включая те, о которых вы при создании заказа не знали.

Как объединить свои заявки

Если вы заранее знаете, что две ваши заявки должны стать одной поездкой, передайте во втором запросе на создание поле order с номером заказа из первого ответа. Вторая накладная станет квитанцией -002 того же заказа, и опрашивать вы будете один номер вместо двух.

Дописывать квитанции можно только в собственные заказы. Чужой и несуществующий номер дают одинаковую ошибку 422 с текстом «Заказ не найден».

9Справочники

Тип доставки — type_of_delivery

Принимается как число, так и текстовый ключ.

Способ оплаты — how_pay

Состояния заказа — status

Состояние «завершён» — это в том числе ложный приезд, когда груз не приняли. В таком случае в поле delivery вместо фамилии стоит пояснение, а поездка оплачивается.

Как вес и габариты влияют на тариф

Вид отправления определяем мы — из типа доставки, веса и габаритов. Учитывается больший из двух весов: фактический и объёмный, где объёмный равен произведению длины, ширины и высоты в сантиметрах, делённому на 5000.

Поэтому заказ, оформленный как пешая доставка, при указании веса 15 кг будет выполнен и оплачен как авто. Указывайте вес и габариты честно: это избавит от расхождений в счёте.

Виды отправления в ответе

письмо · бандероль · бандероль до 1 кг · бандероль до 3 кг · бандероль до 5 кг · бандероль более 5 кг · подарки, в т.ч. цветы (до 5 кг) · автодоставка · минивен · грузовая доставка · сопровождение

Если вид отправления в поездке не уточнялся, доставка считается письмом — так она и отображается в ответе.

10Эксплуатация

Частота запросов

На практике столько и не нужно. Пока статус не «завершён», стоимость не появится, а после завершения смысл в частом опросе пропадает. Для регулярной сверки делайте один запрос за период вместо сотен запросов по отдельным номерам: за один вызов возвращаются все накладные с приездом в эти дни.

Что сохранять у себя

Номер заказа — обязательно, номер накладной — для сверки документов. Свой собственный номер передавайте в remark: он будет виден нашим логистам и вернётся в ответе.

Повторные запросы

Повторная отправка одного и того же заказа создаёт новый заказ — защиты от дублей по содержимому нет. Если ответ не получен из-за обрыва связи, проверьте статус за нужную дату перед повторной отправкой.

Сверка сумм

Значения price, waiting и load_unload соответствуют тем, что попадут в счёт. Разница возможна, если наш расчётный отдел скорректировал стоимость вручную — тогда в статусе будет актуальное значение.

11Поддержка

По вопросам подключения, выдачи токена и расхождений в расчётах обращайтесь к вашему менеджеру в «Рултек».

При обращении по технической проблеме приложите номер заказа или накладной, дату и время запроса, отправленное тело запроса и полученный ответ с кодом.