Авторизация
API-ключ создаётся администратором компании в разделе «Интеграции». Полный токен показывается один раз.
Authorization: Bearer vl_live_xxxxxxxxx
Content-Type: application/json
Не передавайте API-ключ в URL, клиентском JavaScript или мобильном приложении. Он предназначен для server-to-server интеграции.
Рейсы
Один код активации соответствует одной поездке. Повторный запрос с тем же Idempotency-Key не создаёт дубликат.
POST/external/v1/trips
Создать рейс и получить tracking-код
GET/external/v1/trips
Список рейсов компании
GET/external/v1/trips/{tracking_code}
Данные конкретного рейса
POST/external/v1/trips/{tracking_code}/status
Изменить рабочий статус
curl -X POST "$BASE/external/v1/trips" \
-H "Authorization: Bearer $VEZILINK_API_KEY" \
-H "Idempotency-Key: order-2026-001" \
-H "Content-Type: application/json" \
-d '{
"title": "Москва - Новосибирск",
"client_name": "ООО Клиент",
"client_ref": "ORDER-001",
"metadata": {
"Товары": [{
"Тип": "цветы",
"Наименование": "Розы",
"Параметры": {"Количество": "40 коробок", "Вес": "820 кг"}
}]
},
"stops": [{"name": "Новосибирск, склад клиента"}]
}'
Получатели и QR-выдача
Один рейс может содержать несколько адресных отправлений. Каждое отправление показывает получателю только его товары; для палеты или коробки можно выпустить отдельный QR с выбранными позициями.
POST/external/v1/trips/{tracking_code}/shipments
Создать отправление и получить QR и токен
GET/external/v1/trips/{tracking_code}/shipments
Список отправлений рейса
GET/public/v1/shipments/{token}
Безопасная карточка получателя без авторизации
POST/public/v1/shipments/{token}/receive
Подтвердить количество и состояние товаров по PIN
{
"recipient_name": "ООО Получатель",
"recipient_phone": "+7 900 000-00-00",
"external_ref": "ORDER-1001",
"items": [
{
"category": "Цветы",
"name": "Роза Explorer",
"quantity": 40,
"unit": "коробок",
"weight_kg": 820,
"metadata": {"длина_см": 60}
}
],
"packages": [
{"label": "Палета 1", "item_indexes": [0]}
]
}
API-ключ компании используется только для создания. Ссылка и QR не содержат PIN: водитель создаёт короткоживущий одноразовый код в приложении только при фактической выдаче.
Геопозиция через API
Используется для GPS-шлюза или собственной CRM компании.
POST/external/v1/locations
Передать координату водителя или рейса
{
"driver_number": "FT-101",
"lat": 55.751244,
"lon": 37.618423,
"source": "crm-gateway"
}
Клиентский tracking
Публичный endpoint не раскрывает номер телефона, токены водителя или внутренние комментарии.
GET/public/v1/track/{tracking_code}
Без авторизации
GET/track/{tracking_code}
Готовая страница для клиента
GPS и мобильные устройства
Device-токен имеет отдельный префикс `vl_dev_` и не даёт доступ к данным компании.
POST/device/v1/location
Координата от закреплённого устройства
curl -X POST "$BASE/device/v1/location" \
-H "Authorization: Bearer $VEZILINK_DEVICE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"lat":55.751244,"lon":37.618423,"source":"gps"}'
Webhooks
VEZILINK отправляет события рейса и выдачи POST-запросом. Подпись вычисляется HMAC-SHA256 по исходному телу запроса.
X-VeziLink-EventСобытия: `trip.*`, `shipment.*`, `package.received`, `package.partial`, `package.problem`.
X-VeziLink-SignatureШестнадцатеричная HMAC-SHA256 подпись.
Коды ошибок
400Некорректное тело или статус.
401 / 403Нет ключа или недостаточно scope.
404Рейс или водитель не найден.
409Конфликт идентификатора.
429Превышен лимит запросов.
5xxПовторить запрос с тем же Idempotency-Key.