Автентифікація та ключі
Створіть ключ у розділі API-ключі у кабінеті. Ключі належать вашій компанії: будь-який експедитор компанії може переглядати й відкликати їх. Ключ показується лише один раз; GigFreight зберігає тільки його хеш SHA-256 і префікс (gf_xxxxxxxx), який ви бачите у списку.
Передавайте ключ у заголовку Authorization: Bearer gf_… у кожному запиті. Ключі в URL-адресах не приймаються. Кожен ключ має права: loads:read (запити GET) і loads:write (POST, PATCH, DELETE, масове завантаження). Для запису потрібні обліковий запис експедитора у верифікованій компанії та активний тариф Elite.
Створений вантаж розміщується на ринку облікового запису, якому належить ключ, з цінами у валюті цього ринку (для України – у гривнях), і позначається як опублікований через API. Ринок, експедитора чи класифікацію GigFreight встановити самостійно не можна.
Ендпоінти
| Метод | Шлях | Що робить |
|---|---|---|
GET | /api/v1/loads | Список вантажів вашої компанії, найновіші першими. Право: loads:read. |
POST | /api/v1/loads | Створити вантаж. Право: loads:write. |
GET | /api/v1/loads/{id} | Отримати один вантаж. Для вантажів інших компаній повертається 404. Право: loads:read. |
PATCH | /api/v1/loads/{id} | Змінити поля вантажу (лише чернетки та активні вантажі) або його статус. Право: loads:write. |
DELETE | /api/v1/loads/{id} | Скасувати вантаж (статус cancelled; вантажі ніколи не видаляються остаточно). Право: loads:write. |
POST | /api/v1/loads/bulk | Створити до 500 вантажів за один запит; кожен рядок отримує власний результат. Право: loads:write. |
GET | /api/v1/marketplace/loads | Переглянути актуальні вантажі біржі на ваших ринках (див. /ua/api-docs). |
GET | /api/v1/docs | Специфікація OpenAPI 3.1 у форматі JSON (англійською). |
Повторні запити та ідемпотентність
Поле external_ref (ваш номер замовлення) робить створення ідемпотентним: якщо вантаж із таким external_ref у вашій компанії вже існує, новий не створюється. Заголовок Idempotency-Key дозволяє безпечно повторити той самий запит: з тим самим ключем і тілом повертається перша відповідь.
Обов’язкові поля нового вантажу: pickup_city, pickup_date (сьогодні або пізніше), delivery_city, delivery_date, vehicle_type. Дати – у форматі YYYY-MM-DD.
Ліміти запитів
60 запитів на хвилину і 10 000 на добу на один ключ; 120 запитів на хвилину з однієї IP-адреси. Масовий запит зараховується як один запит на кожні розпочаті 25 рядків. Після перевищення ліміту API відповідає 429 із заголовком Retry-After.
Коди помилок
Коди в полі error відповіді лишаються англійською, щоб ваші системи могли їх обробляти.
| HTTP | Код | Значення |
|---|---|---|
| 400 | invalid_json / validation_failed | Некоректне тіло запиту або параметри |
| 401 | unauthorized | Ключ відсутній, невідомий або відкликаний |
| 402 | subscription_inactive | Підписка неактивна (оплата очікується, прострочена або скасована) |
| 403 | plan_required / insufficient_scope / account_suspended / posting_not_allowed | Потрібен тариф Elite, у ключа немає потрібного права, обліковий запис заблоковано або ви не експедитор у верифікованій компанії |
| 404 | not_found | Вантаж не існує або належить іншій компанії |
| 409 | invalid_transition / conflict / idempotency_in_progress | Поточний статус вантажу не дозволяє цю зміну |
| 413 | payload_too_large | Тіло понад 2 МБ або більше ніж 500 рядків у масовому запиті |
| 422 | validation_failed / idempotency_key_reused | Помилки полів наведено в «errors» |
| 429 | rate_limited | Забагато запитів; зачекайте кількість секунд із заголовка Retry-After |
Повний довідник
Приклади запитів, формат відповіді, масове завантаження та всі поля описано в повному довіднику англійською і в специфікації OpenAPI JSON. API для перегляду біржі описано на сторінці Документація API.