Logistica REST API
Создавайте объявления, управляйте предложениями, передавайте этапы сделок и координаты транспорта из TMS, ERP или своей системы. События мгновенно поступают через вебхуки.
Начало
Базовый адрес: https://alfaloji.forum/api/v1. Ключ создаёт владелец компании на странице Интеграции ; ключ показывается один раз. Ключи «Чтение» могут выполнять только GET-запросы. Лимит — 120 запросов в минуту на ключ (X-RateLimit-Remaining ).
Даты возвращаются в ISO 8601 (UTC); при отправке укажите часовой пояс или местное время согласно полю timezone объявления. Идентификаторы совпадают с платформой: UUID для объявлений, предложение T-…, сделка A-…, компания F-….
Аутентификация
curl https://alfaloji.forum/api/v1/me \ -H "Authorization: Bearer lgk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Ключ действует с правами создавшего его сотрудника. Если он покинет компанию или лишится прав, ключ перестанет работать — создайте новый. Не размещайте ключ в клиентском коде (браузер, мобильное приложение).
Ответы и ошибки
Успешные ответы имеют вид {"data": …}, ошибки {"error": {"code", "message"}} . Язык сообщений выбирается по заголовку Accept-Language (tr, en, ru).
| HTTP | Код | Значение |
|---|---|---|
| 401 | unauthorized, invalid_key | Ключ отсутствует, недействителен или отозван. |
| 403 | insufficient_scope, forbidden | Запись с ключом «Чтение» или действие без прав. |
| 403 | plan_required | Доступ к API не входит в тариф вашей компании (тариф «Корпоративный»). |
| 404 | not_found | Запись не существует или не принадлежит вашей компании. |
| 422 | validation, confirmation_required | Ошибка поля или бизнес-правило (напр. компания не верифицирована). |
| 429 | rate_limited | Retry-After секунд и повторите. |
Аккаунт
| GET | /me | Компания, права и пользователь ключа. |
| GET | /events | Список типов событий вебхуков. |
Объявления
| GET | /listings | Объявления вашей компании. Фильтры: status, kind, limit, offset. |
| POST | /listings | Создаёт объявление. "publish": true — сразу публикует. |
| GET | /listings/{id} | Одно объявление. |
| PATCH | /listings/{id} | Обновляет объявление; если оно опубликовано, создаётся новая версия и участники уведомляются. |
| POST | /listings/{id}/publish | Публикует черновик. |
| POST | /listings/{id}/close | Снимает объявление; открытые предложения закрываются. |
| GET | /listings/{id}/offers | Предложения по объявлению. |
Биржа
| GET | /market/listings | Поиск опубликованных объявлений. Фильтры: kind, from, to, vehicle, mode, date, sort, limit. |
| GET | /market/listings/{id} | Одно опубликованное объявление. Если оно принадлежит другой компании, содержит сводку доверия «company.trust». |
| POST | /market/listings/{id}/offers | Делает предложение: price, currency, vat (excl/incl), payment_term (prepaid, net15, net30, net45, net60), valid_hours (6, 24, 48, 72, 168), note. |
Ставки
| GET | /offers | direction=incoming|outgoing, status=open|accepted|rejected|withdrawn|closed. |
| GET | /offers/{id} | Одно предложение (T-…). Во всех ответах по предложениям сводка доверия к контрагенту приходит в поле «trust» (уровень: trusted|new|caution, строки-основания, числа); это не гарантия оплаты или перевозки. |
| POST | /offers/{id}/accept | Принимает предложение и создаёт сделку. Требуется тело {"confirm": true}. |
| POST | /offers/{id}/reject | reason: price_too_high, date_unsuitable, vehicle_unsuitable, other_solution, other; note. |
| POST | /offers/{id}/withdraw | Отзывает ваше предложение. |
Сделки и координаты
| GET | /deals | Сделки. Фильтр: status (active, completed, cancelled, dispute). |
| GET | /deals/{id} | Сделка, история событий, последняя позиция и статус защиты платежа. |
| POST | /deals/{id}/stage | {"stage": 1–4}. 1–3 — перевозчик, 4 (подтверждение) — грузовладелец. |
| GET | /deals/{id}/positions | Трек координат. |
| POST | /deals/{id}/positions | Перевозчик передаёт координаты рейса: lat, lng, speed_kmh, heading, recorded_at или {"positions": […]} (до 500). |
Телематика и аренда
| GET | /telematics/vehicles | Подключённый транспорт и последние координаты. |
| POST | /telematics/positions | Пакет координат для транспорта подключения «API push»: {"positions":[{"vehicle","lat","lng","speed_kmh","heading","recorded_at"}]}. |
| GET | /rentals | Заявки на аренду. direction=incoming|outgoing. |
| GET | /webhooks | Настроенные вебхуки. |
Вебхуки
Укажите https-адрес и события на странице «Интеграции». Каждое событие отправляется POST-запросом в JSON; если за 10 секунд нет ответа 2xx, отправка повторяется 6 раз с растущими интервалами. Одно событие может прийти несколько раз; id устраняйте дубли по полю id.
POST /logistica/webhook
X-Logistica-Event: deal.stage_changed
X-Logistica-Signature: t=1790260000,v1=5f1c…
{"id":"evt_…","event":"deal.stage_changed","created_at":"2026-09-24T10:15:00+00:00",
"data":{"deal":{"id":"A-3110","stage":2,"stage_label":"Taşımada", …}}}
Проверьте подпись: hex(HMAC_SHA256(imza_anahtarı, t + "." + ham_gövde)) == v1 и t не старше 5 минут.
$sig = $_SERVER['HTTP_X_LOGISTICA_SIGNATURE'];
preg_match('/t=(\d+),v1=([0-9a-f]+)/', $sig, $m);
$ok = abs(time() - (int)$m[1])
offer.createdНовое предложение offer.acceptedВаша ставка принята offer.rejectedВаша ставка отклонена offer.withdrawnСтавка отозвана deal.createdСделка создана deal.stage_changedЭтап перевозки изменён deal.completedСделка завершена deal.cancelledСделка отменена deal.disputedОткрыт спор message.createdНовое сообщение listing.publishedОбъявление опубликовано listing.closedОбъявление закрыто rental.requestedЗапрос на аренду rental.acceptedАренда подтверждена rental.declinedАренда отклонена rental.cancelledАренда отменена/отозвана tender.awardedТендер выигран escrow.fundedЗащищённый платёж внесён escrow.releasedЗащищённый платёж выплачен escrow.refundedЗащищённый платёж возвращён
Пример: объявление о грузе из TMS
curl -X POST https://alfaloji.forum/api/v1/listings \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{
"kind": "cargo", "title": "İstanbul → Münih tekstil",
"origin": {"city": "İstanbul", "country": "Türkiye"},
"destination": {"city": "Münih", "country": "Almanya"},
"transport_mode": "FTL", "vehicle_type": "tent", "weight_kg": 18000,
"available_from": "2026-10-01T08:00:00+03:00", "available_until": "2026-10-03T18:00:00+03:00",
"timezone": "Europe/Istanbul", "price_type": "offer", "currency": "EUR", "publish": true }'
Ставки offer.created . Подходящее предложение принимайте через POST /offers/T-…/accept ; по мере сообщений перевозчика о загрузке и доставке приходят события deal.stage_changed а если транспорт привязан — GET /deals/A-… возвращает последнюю позицию.
Типы транспорта: tent (Tenteli), refrigerated (Frigorifik), box (Kapalı kasa), flatbed (Açık kasa), mega (Mega), container (Konteyner taşıyıcı), lowbed (Lowbed), tanker (Tanker).