Документация GraphQL API сервиса ТоргТранс
Вступление
API интерфейс используется для того, чтобы интегрировать возможности
сервиса ТоргТранс в личный
проект
клиента. API предназначен для разработчиков и сопровождается детальной документацией.
О GraphQL можно почитать здесь:
Основной URL
Все ссылки на запросы к API в данной документации включают обязательный основной URL: https://api.torgtrans.com/graphql/название схеме (customer, transporter, claim, tender)
Авторизация
Процесс авторизации возможен при наличии персонального ключа (api-key), которым в дальнейшем должен
быть
подписан каждый запрос к API.
Ключ (api-key) передается в заголовке любого запроса (в "headers") X-API-KEY.
Пример ключа:
X-API-KEY: tfTAPyHXUgjig72jlrd5HpIJ4Si1LydYpL5oigmcПолучение api-key
Для получения апи ключа авторизуйтесь в веб интерфейсе и пройдите по ссылке
Примеры запросов(query) и мутаций(mutation) с использованием curl
Запрос списка пользователей компании
curl -X POST 'https://api.torgtrans.com/graphql/secure'
-H 'X-API-KEY: ВАШ API-KEY'
-H 'content-type: application/json'
-H 'accept: */*'
--data-raw '{"operationName":"FetchUserList","variables":{},"query":"query FetchUserList { user_list
{ name surname phone email confirmed }}"}'
--compressed
Мутация, приглашение пользователя в компанию
curl -X POST 'https://api.torgtrans.com/graphql/secure'
-H 'X-API-KEY: ВАШ API-KEY'
-H 'content-type: application/json'
-H 'accept: */*'
--data-raw '{"operationName":"InviteUser","variables":{"emails":["test_email@torgtrans.com"]}, "query":"mutation InviteUser($emails: [String]) { invite_user(emails: $emails) { status message }}"}'
--compressed
Жизненный цикл заявки
Основные запросы
| Описание запроса | Тип | Схема | Название запроса |
|---|---|---|---|
| Получение информации о заявке | Запрос (query) | customer | order_info |
| Список заявок | Запрос (query) | customer | order_list |
| Создать/изменить заявку | Мутация (mutation) | customer | save_order |
| Начать торги по заявке | Мутация (mutation) | customer | start_auction |
| Остальные запросы и мутации можно найти в описании схемы customer | |||
| Дополнительные доступные схемы secure, tender, claim, warehouse. | |||
Тендеры
Тендеры позволяют организовать конкурентные торги для выбора перевозчика на длительный период. В отличие от обычных заявок, тендеры предназначены для долгосрочного сотрудничества и могут включать множество маршрутов и условий.
| Описание запроса | Тип | Схема | Название запроса |
|---|---|---|---|
| Получение информации о тендере | Запрос (query) | tender | header_info |
| Получение информации о строках тендера | Запрос (query) | tender | header_lines |
| Список тендеров | Запрос (query) | tender | headers_list |
| Создать/изменить заголовок тендера | Мутация (mutation) | tender | save_header |
| Создать/изменить строку тендера | Мутация (mutation) | tender | save_line |
| Полное описание всех запросов и мутаций можно найти в описании схемы tender | |||
Веб хуки
Вебхук - это механизм отправки уведомлений при наступлении в системе ключевых событий. Под событием понимается изменение состояния системы. Уведомлением будет POST запрос, который будет содержать следующую информацию о наступившем событии: его тип и идентификатор сущности. Например, при появлении новой ставки на рейс, будет отправлено уведомление: {"event_type":"order_new_auction_bet", "entity_id":"1"}
В заголовоке будет передан X-API-KEY, значение можно найти на странице настройки веб хуков.
Жизненный цикл заявки
Основные запросы
| Описание запроса | Тип | Схема | Название запроса |
|---|---|---|---|
| Получение информации о заявке | Запрос (query) | transporter | order_info |
| Список заявок | Запрос (query) | transporter | order_list |
| Сделать ставку на заявку | Мутация (mutation) | transporter | bet_price |
| Создать/изменить водителя | Мутация (mutation) | transporter | save_driver |
| Назначить транспорт и водителя на заказ | Мутация (mutation) | transporter | set_transport |
| Основные запросы можно найти в описании схемы transporter | |||
| Дополнительные доступные схемы secure, claim, warehouse. | |||