API 4logist: подключение, авторизация и работа с документацией

0
0
0

API 4logist предназначен для автоматизированного обмена данными между 4logist и внешними системами.

С помощью API можно получать, создавать и изменять данные в тех разделах и в том объёме, которые предусмотрены текущей API-документацией.

API является техническим инструментом. Для разработки интеграции со стороны клиента необходим специалист, умеющий работать с REST API, HTTP-запросами, авторизацией и обработкой ответов сервера.

Где находится документация API

Актуальная документация доступна непосредственно в вашей базе 4logist:

Установки → Система → API

Для отдельных методов дополнительно могут быть указаны:

  • тип запроса — GET, POST, DELETE и др.;
  • параметры метода;
  • структура передаваемых данных;
  • доступные фильтры;
  • отдельные технические схемы.

При этом документация не является пошаговой инструкцией по разработке интеграции и не описывает бизнес-логику использования каждого метода.

OpenAPI

API 4logist описан в формате OpenAPI.

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

Что необходимо для работы с API

Для подключения потребуется:

  1. Доступ к базе 4logist.
  2. Сотрудник 4logist, от имени которого будет работать интеграция.
  3. Необходимые права доступа у этого сотрудника.
  4. Данные API, созданные в разделе Установки → Система → API.
  5. Разработчик или технический специалист со стороны клиента.
  6. Внешняя система, которая будет выполнять API-запросы и обрабатывать ответы.

Рекомендуем создавать отдельного сотрудника специально для интеграции и предоставить ему доступ Супер админ.

Это позволяет отдельно управлять его правами и не использовать для автоматизированных запросов личную учётную запись сотрудника.

Авторизация

В 4logist работа с API выполняется от имени сотрудника системы.

Права API зависят от прав сотрудника, от имени которого выполняется авторизация.

Для подключения используются данные API и учётные данные сотрудника в соответствии со схемой авторизации, указанной в разделе:

Установки → Система → API

После успешной авторизации система выдаёт токен.

Для последующих API-запросов используется схема:

Authorization: Bearer <token>

В API используется Bearer JWT.

Важно

Не следует использовать client_credentials как замену авторизации от имени сотрудника, если такой способ прямо не предусмотрен актуальной документацией вашей базы.

Ситуация, когда токен технически получен, но API-методы возвращают:

403 access denied

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

Client ID и Client Secret

Данные подключения создаются в разделе:

Установки → Система → API

Client ID, Client Secret, пароли и токены являются конфиденциальными данными.

Не размещайте в открытой переписке:

  • Client Secret;
  • пароль сотрудника;
  • access token;
  • refresh token;
  • другие данные, позволяющие выполнить авторизацию.

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

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

Как начать работу

Шаг 1. Определите задачу

Сначала необходимо определить, что именно должна делать интеграция.

Например:

  • получать заказы;
  • получать закрытые заказы;
  • передавать данные во внутреннюю CRM;
  • получать рейсы;
  • синхронизировать клиентов;
  • получать перевозчиков;
  • создавать полученные счета;
  • загружать документы;
  • формировать отчётность;
  • выгружать данные при переходе на другую систему.

После этого разработчик самостоятельно определяет необходимые методы по документации.

Шаг 2. Создайте отдельного сотрудника

Рекомендуется создать отдельного сотрудника 4logist для интеграции с правами Супер админ.

Шаг 3. Создайте API-доступ

Перейдите:

Установки → Система → API

Создайте или используйте существующие данные API.

Шаг 4. Выполните авторизацию

Используйте схему авторизации, указанную в API-документации.

После получения токена передавайте его в API-запросах:

Authorization: Bearer <token>

Шаг 5. Проверьте получение данных

До разработки всей интеграции рекомендуется выполнить один простой запрос на получение данных.

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

Шаг 6. Настройте обработку страниц

Многие методы получения списков используют пагинацию.

Обычно доступны параметры:

limit

page

sort

Для ряда методов максимальный limit составляет:

100

Если необходимо получить больше данных, интеграция должна последовательно запрашивать следующие страницы.

Не следует рассчитывать на получение всей базы одним запросом.

Основные методы

Ниже приведены только примеры.

Полный перечень методов, параметров и полей необходимо смотреть в текущей API-документации.

Заказы

Получение списка:

POST /api/orders/list

Получение полной информации по конкретному заказу:

GET /api/orders/{orderId}/all-info

Создание:

POST /api/orders/new

Редактирование:

POST /api/orders/edit/{id}

Для списка заказов предусмотрены различные фильтры, включая:

  • период;
  • дату загрузки;
  • дату выгрузки;
  • номер заказа;
  • ID заказа;
  • клиента;
  • статус;
  • автомобиль;
  • прицеп;
  • водителя;
  • компанию;
  • другие параметры, указанные в документации.

Для получения расширенной информации по известному ID заказа можно использовать:

GET /api/orders/{orderId}/all-info

Дата изменения заказа

В текущей документации для /api/orders/list отсутствует отдельный фильтр по дате последнего изменения заказа.

Поля dateFrom / dateTo не следует автоматически трактовать как дату изменения записи.

Если интеграции необходимо регулярно получать только изменённые заказы, разработчику необходимо построить логику синхронизации исходя из реально доступных фильтров.

Рейсы

Получение списка рейсов:

POST /api/trips/list

В API также предусмотрены отдельные методы для некоторых операций с рейсами и статусами рейсов.

Важно: наличие данных в карточке рейса в веб-интерфейсе не означает автоматически, что эти же данные возвращаются через API.

Например, для некоторых сценариев поля транспорта или водителя могут присутствовать в структуре API, но возвращаться пустыми.

В таких случаях необходимо сначала проверить фактический ответ API.

Запросы

Активные запросы:

POST /api/requests/list

Архив:

POST /api/requests/archive-list

Грузы конкретного запроса:

GET /api/request-consignments/list

Справочник статусов:

POST /api/request-statuses/list

Важно различать:

справочник статусов — список возможных статусов;

и

историю статусов — последовательность изменения статусов конкретного запроса с датой, временем и пользователем.

Если отдельный endpoint истории статусов отсутствует в документации, получить такую информацию документированным способом нельзя.

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

Перевозчики

Список перевозчиков:

POST /api/carriers/list

Создание:

POST /api/carriers/new

Редактирование:

POST /api/carriers/edit/{carrier}

Для части связанных данных используются отдельные API-методы.

При этом не весь функционал карточки перевозчика имеет отдельный публичный endpoint.

Например, если в веб-интерфейсе существует отдельная вкладка «Транспорт», это ещё не означает наличие метода вида:

/api/carriers/{id}/vehicles

Необходимо проверять актуальную документацию.

Полученные счета

Список полученных счетов:

POST /api/received-invoices/list

Создание:

POST /api/received-invoices/{order}/new

Добавление рейса в распределение:

POST /api/received-invoices/{invoice}/add-trip/{trip}

Добавление расхода в распределение:

POST /api/received-invoices/{invoice}/add-service/{service}

Для метода распределения на рейс используется схема, в которой обязательным параметром является:

form[amount]

Не следует передавать дополнительные параметры, отсутствующие в схеме, в расчёте на недокументированную логику.

Формат POST-запросов

Для многих методов в API используется:

multipart/form-data

Названия параметров необходимо передавать точно так, как они приведены в документации.

Например:

form[amount]

form[client]

form[company]

или:

form_order_api_filter[orderStatus]

Не следует:

  • самостоятельно переименовывать параметры;
  • изменять регистр;
  • заменять структуру массива строкой;
  • предполагать существование недокументированных полей.

Фильтры

Фильтры отличаются в зависимости от метода.

Наличие конкретного фильтра в одном разделе API не означает его наличие в другом.

Например, некоторые методы счетов содержат фильтры:

modifiedFrom

modifiedTo

Это не означает, что такие же фильтры автоматически доступны для заказов, рейсов или запросов.

Всегда проверяйте схему конкретного метода.

Пользовательские поля

Через API можно использовать только те поля, которые поддерживаются соответствующим методом.

Если поле существует в интерфейсе 4logist, но отсутствует в API-документации, его получение или передача через API не гарантируется.

Не следует самостоятельно использовать недокументированные поля.

API не является полной копией интерфейса 4logist

API и интерфейс системы могут предоставлять разный объём данных.

Возможны ситуации, когда:

  • поле отображается в интерфейсе, но отсутствует в API;
  • API возвращает только часть данных;
  • существует ID связанного объекта, но отсутствует отдельный метод его получения;
  • API возвращает текущий статус, но не историю изменений;
  • отдельные данные представлены в интерфейсе, но не имеют публичного API-метода.

Ориентироваться необходимо на доступные методы и фактические ответы API.

Если нужного метода или поля нет

Если необходимого метода или поля нет в API-документации, техническая поддержка не предоставляет недокументированные способы доступа к данным.

При необходимости можно направить запрос на расширение API.

В запросе желательно указать:

  • какие данные необходимы;
  • для какой сущности;
  • каким методом клиент работает сейчас;
  • каких данных не хватает;
  • для чего они нужны.

Такой запрос может быть передан разработчикам на рассмотрение.

Передача запроса не означает обязательную реализацию или определённый срок разработки.

Что делает техническая поддержка

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

Например:

  • метод возвращает серверную ошибку;
  • метод не работает при корректно сформированном запросе;
  • фактическое поведение отличается от ожидаемого;
  • возникает стабильная ошибка 500 или 502;
  • данные не возвращаются в ситуации, где ожидается их наличие.

Что необходимо предоставить поддержке

Для проверки проблемы необходимо предоставить:

  • домен базы;
  • API-метод;
  • полный URL;
  • HTTP-метод;
  • параметры запроса;
  • request body;
  • код ответа сервера;
  • response body;
  • ID объекта;
  • дату и точное время запроса.

Если прикладываются скриншоты, необходимо скрыть:

  • токены;
  • Client Secret;
  • пароль;
  • другие конфиденциальные данные.

Что не входит в техническую поддержку API

Техническая поддержка не выполняет:

  • разработку интеграций;
  • написание клиентского кода;
  • настройку сторонних систем;
  • настройку n8n, Make, Bitrix24 и других сервисов;
  • настройку Postman;
  • подбор API-методов под бизнес-процесс;
  • подбор полей вместо разработчика;
  • формирование готовых curl-запросов;
  • генерацию токенов для клиента;
  • настройку регулярной синхронизации;
  • разработку скриптов выгрузки;
  • перенос данных между системами.

Для этих задач необходимо привлечь технического специалиста со стороны клиента.

Ошибка 401 Unauthorized

Ошибка 401 Unauthorized обычно связана с авторизацией.

Необходимо проверить:

  • используемый токен;
  • способ авторизации;
  • домен;
  • заголовок Authorization;
  • актуальность учётных данных.

Ошибка 403 Access denied

Ошибка 403 access denied означает отсутствие доступа к выполняемой операции.

Необходимо проверить:

  • сотрудника, от имени которого выполняется работа;
  • права сотрудника;
  • способ авторизации;
  • токен;
  • домен;
  • корректность запроса.

Успешное получение токена само по себе не гарантирует доступ ко всем методам API.

Ошибка 500 Internal Server Error

Если API возвращает:

500 Internal Server Error

и запрос сформирован в соответствии с документацией, необходимо передать пример в техническую поддержку.

Для проверки особенно важны:

  • запрос;
  • ответ;
  • ID объекта;
  • дата и точное время ошибки.

Ошибка 502 Bad Gateway

При получении:

502 Bad Gateway

сначала необходимо проверить:

  • правильность домена;
  • endpoint;
  • формат запроса;
  • авторизацию;
  • передаваемые параметры.

Если корректный запрос стабильно возвращает ошибку, его необходимо направить в поддержку.

Выгрузка данных

API может использоваться для получения доступных данных из 4logist.

Например:

  • заказов;
  • рейсов;
  • запросов;
  • клиентов;
  • перевозчиков;
  • счетов;
  • других сущностей, для которых существуют соответствующие методы.

Выгрузку и сохранение данных в нужном формате выполняет технический специалист клиента.

Частые вопросы

Вы можете настроить нам API?

Интеграция разрабатывается специалистом клиента на основании доступных API-методов.

Можете подсказать, какой метод нам использовать?

Выбор метода зависит от логики интеграции и выполняется разработчиком клиента на основании API-документации.

Можете сказать, какое поле соответствует нашим данным?

Техническая поддержка не выполняет сопоставление полей под индивидуальную интеграцию.

Необходимо изучить доступные методы и фактические ответы API.

Можете предоставить готовый запрос?

Техническая поддержка не формирует готовые curl, скрипты или код интеграции.

Поле есть в 4logist, но его нет в API. Что делать?

Если поле или метод отсутствуют в API, документированного способа получить такие данные нет.

Можно направить запрос на расширение API.

Перед обращением в поддержку

Перед обращением убедитесь, что:

  • используется существующий API-метод;
  • запрос отправляется на актуальный домен;
  • авторизация выполнена корректно;
  • права сотрудника проверены;
  • обязательные параметры переданы;
  • сохранён полный запрос;
  • сохранён полный ответ;
  • известно точное время возникновения ошибки.

Главное

4logist предоставляет доступные API-методы и техническую документацию к ним.

Разработка интеграции, выбор методов, сопоставление данных и настройка внешней системы выполняются специалистом клиента.

Техническая поддержка подключается для проверки конкретных ошибок в работе API.

Было ли это полезно?

0 / 0