TMS API (1.0.1)

• API Перевозчика
• API Грузовладельца

Большинство запросов API требуют аутентификации или возвращают общедоступные данные только в том случае, если аутентификация не предусмотрена. Если аутентификация не требуется, это отдельно указано в документации точки. Если информация аутентификации недействительна или отсутствует, TMS вернет сообщение об ошибке с кодом 401.

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

  Authorization: Token YOUR_API_KEY

• 200 OK - Запрос успешно выполнен, и сервер вернул запрашиваемые данные.

• 201 Created - Запрос успешно выполнен, и в результате был создан новый ресурс.

• 204 No Content - Запрос успешно выполнен, но сервер не возвращает никаких данных.

• 401 Unauthorized - Запрос требует аутентификации. Это может означать, что API ключ недействителен или отсутствует.

• 403 Forbidden - Сервер понял запрос, но отказывается его выполнять из-за недостаточных прав доступа.

• 404 Not Found - Запрашиваемый ресурс не найден. Это может означать, что указанный URL неверен.

• 422 Unprocessable Entity - Сервер понимает содержимое запроса, но не может обработать его из-за ошибок. Это означает, что запрос корректен, но не может быть выполнен из-за проблем с логикой или данными, которые он содержит.

• 429 Too Many Requests - Клиент отправил слишком много запросов за определенный период времени. Это означает, что вы достигли лимита запросов API.

При работе с API вы можете столкнуться с ошибками проверки, в этом случае API возвращает ошибку HTTP 422. Подобные ошибки появляются в следующих случаях:

• Ошибка входных данных. Отсутсвует обязательный атрибут, некорректный формат и тд. В таком случае вы получите что-то похожее на

    {
      "code": "DomainErrors::ContractValidationError",
      "errors": {
        "legal_entity": {
          "name": [
            "не может быть пустым"
          ]
        }
      }
    }
  

  DomainErrors::ContractValidationError означает, что произошла ошибка входных данных, а в errors содержится уточнение ошибок, контракт ошибок идентичен контракту входных данных

• Логическая ошибка из-за чего запрос не может быть выполнен. Пример:

    {
      "code": "DomainErrors::OrderingContext::DigitalQueueIsNotAvailableForShipment"
    }
  

  Варианты все варианты кодов ошибок и их значение будут отдельно описаны в рамках конкретной точки API

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

• page - номер страницы, по-умолчанию 1
• items - кол-во объетов на странице, по-умолчанию 20, максимум 100

В ответе в заголовке запроса вы получите информацию для пагинации:

  current-page: 1 // Номер текущей страницы
  page-items: 100 // Кол-во объектов на странице
  total-count: 208 // Общее кол-во объектов
  total-pages: 3 // Общее кол-во страниц

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

• GET /carrier_api/v1/feed (получение списка заказов) - лимит равен 5 запросам в минуту с одним API-токеном
• GET /carrier_api/v1/feed/:id (получение детальной информации о заказе) - на этом эндпойте установлены 2 лимита:
  • 10 запросов в минуту с одним API-токеном для одного конкретного заказа и
  • 500 запросов в минуту с одним API-токеном суммарно для всех заказов

В случае превышения указанных лимитов API возвращает ошибку HTTP 429. По истечению интервала времени лимита счетчики запросов обнуляются.

Для других эндпойнтов API ограничений на количество запросов нет.