API Федеральная Таможенная Служба (ФТС)

Документация по работе с API Федеральная Таможенная Служба (ФТС)

Алгоритм получения результата запроса с помощью нашего сервиса достаточно прост и практически одинаков для всех видов ресурсов.
Получите ваш персональный ключ API в настройках вашего аккаунта.
для каждого пользователя генерируется уникальный аутентификационный токен, мы называем "персональный ключ API". Это строка из 32 символов, которая выглядит примерно так:
53ba1b7a55abbа14aa97eff3a5220792
Этот ключ используется для всех ваших запросов к api-cloud.

История изменений/обновлений API

Предупреждение Установите таймаут (TIMEOUT) ожидания минимум 120 секунд, иначе вы можете не получить результат, ваш код может прерваться не дождавшись ответа

HTTPS GET запрос: https://api-cloud.ru/api/fts/v2/fts.php
Обязательно использовать HTTPS протокол, иначе запросы будут дублироваться при перенаправлении с HTTP на HTTPS.
Обязательно использовать GET запрос, иначе мы не увидим параметры, которые вы передаете.

type Обязательно	Описание	Параметры в запросе Обязательно
	В одном запросе возможно отправить только 1 тип
auto	Информация о таможенном оформлении легковых автомобилей, ввезенных на территории государств-членов Евразийского экономического союза	Обязательные vin - VIN номер Разрешено: /^[\dA-HJ-NPR-Z]{17}$/i token - персональный ключ API

Токен (token) можно передавать в заголовках (headers). Указываем в заголовке Token: ВАШ_ТОКЕН

Пример отправки GET запроса на PHP:

function get_rez($url) {
		$ch = curl_init($url);
		curl_setopt($ch, CURLOPT_RETURNTRANSFER,true);
		curl_setopt($ch,CURLOPT_TIMEOUT,120); // Таймаут необходим, поскольку 30 секунд может не хватить и вы не получите ответ 
		$res = curl_exec($ch);
		curl_close($ch);
		return $res;
	}

  $data = [
    'type' => 'Тип запроса (type)',
    ...
    Необходимы для запроса параметры
    ...
    'token' => 'Токен',
    ];

    // Структурированная ссылка для GET запроса
    $url = 'https://api-cloud.ru/api/fts/v2/fts.php?' . http_build_query($data);

    $data = get_rez($url); // Результат ответа (JSON)

Сервер вернёт результат обработки или код ошибки, если что-то пошло не так.
Сервер возвращает ответ в формате JSON.

Обратите внимание, что скорость загрузки результата зависит напрямую от ресурса источника
При подсчете количества запросов будут приняты к учету только те запросы, которы вернули "status": 200 и "status": 404, т.е. получили результат.

Максимальное количество попыток соединения 3 раза. Если в результате этих попыток ресурс не вернет ответа, то API CLOUD вернет ответ {"status":404, "error":"TIME_MAX_CONNECT", "errormsg":"Достигнуто максимальное количество коннектов, при которых ресурс не вернул результата"}

Примеры запросов

Информация о таможенном оформлении легковых автомобилей, ввезенных на территории государств-членов Евразийского экономического союза

Пример запроса успешного запроса HTTP GET на URL нашего API

https://api-cloud.ru/api/fts/v2/fts.php?type=auto&vin=VF34C5FWF22270236&token=53ba1b7a55abbB014aa97eff3a522079

	
{
  "status": 200, // Статус ответа
  "count": 1, // Количество записей в result
  // Массив с результатами
  "result": [
    {
      "VIN": {
        "title": "Номер VIN",
        "value": "WAUZZZF21KN038396"
      },
      "country": {
        "title": "Страна ввоза",
        "value": null,
        "img": null
      },
      "model": {
        "title": "Модель",
        "value": "AUDI"
      },
      "shassi": {
        "title": "Номер шасси",
        "value": "—"
      },
      "kuzov": {
        "title": "Номер кузова",
        "value": "WAUZZZF21KN038396"
      },
      "date": {
        "title": "Дата выпуска в свободное обращение",
        "value": "2019-04-09 14:37:38"
      }
    }
  ],
  "inquiry": {
    "price": 0.3,
    "balance": 527.67,
    "credit": 20000,
    "speed": 4,
    "attempts": 1
  }
}

Данные в базе ФТС отсутствуют

{
  "status": 200, // Статус ответа 
  "count": 0, // Количество записей в result
  "result": [],  // Пустой массив
  "message": "Данные отсутствуют в базе ФТС",
  "inquiry": {
    "price": 0.3,
    "balance": 527.07,
    "credit": 20000,
    "speed": 3,
    "attempts": 1
  }
}

Поиск не дал результатов, либо ресурс не вернул ответа за отведенный промежуток времени

{"status":404, "error":"TIME_MAX_CONNECT", "errormsg":"Достигнуто максимальное количество коннектов, при которых ресурс не вернул результата"}

История изменений API Федеральная таможенная служба

дата	что изменилось
18.06.2025	Выпустили версию API v2. 1. Новый URL с указанием версии API /fts/v2/fts.php 2. Исправили в выводе структуру. Ранее был просто массив без JSON. Теперь в результате как и положено JSON ответ. 3. Статус ответа 4. Все результаты теперь в массиве result 5. Поправили в kuzov и date title (Заголовок) вместо имени shassi 6. Функционал остался прежним, все изменения направлены на архитектуру ответа. Старая версия API fts по пути /api/fts.php будет доступна до 1 сентября 2025 г.
07.11.2022	В вывод добавили массив country отвечающий за информацию о стране ввоза.
07.11.2022	Обновили код взаимодействия с источником.
27.10.2022	Исправлена ошибка, связанная с неправильным форматом вывода результата.
23.10.2022	В массив inquiry добавили ключ balance. Вывод текущего баланса после запроса, позволит не отправлять дополнительные запросы на проверку баланса.
21.10.2022	1. Исправлен формат вывода ошибки, когда источник не доступен. 2. Вывод заголовка Content-type: application/json; charset=utf-8
10.03.2022	Исправлены мелкие баги. API стал более стабильней.
18.11.2021	Информация о запросе в массиве inquiry Добавлен статус ответа, а так же информация о запросе: Тариф, скорость, количество попыток
22.07.2021	Изменили алгоритм выборки данных. Корректное заполнение значений по ключам.

Возможные коды ошибок

код (error)	Описание ошибки (message)
888	ИМЯ передаваемой переменной: forbidden symbols present В переменной ИМЯ присутствуют запрещенные символы
766	MISSING_MANDATORY_PARAMETER Отсутствуют обязательные параметры
602	TOKEN_NO_ACCESS Нет доступа к запрашиваему методу запроса
504	TOKEN_LOCKED_IN_THE_SYSTEM Переданный токен заблокирован службой качества / автоматической системой
503	TOKEN_NOT_REGISTERED_IN_THE_SYSTEM Переданный токен не зарегистрирован в системе
502	MISSING_REQUIRED_TOKEN_PARAMETER Отсутствует параметр token
501	MISSING_REQUIRED_VIN_PARAMETER Отсутствует параметр vin или указан неверно
500	MISSING_REQUIRED_TYPE_PARAMETER Отсутствует параметр type
499	WRONG_TOKEN_KEY Вы указали значение параметра token в неверном формате, ключ должен содержать 32 символа.
498	TOKEN_NO_MONEY Для выполнения запроса недостаточно средств, пополните баланс.
460	NO_REQUIRED_PARAMETERS Отсутствуют обязательные параметры
456	MAX_LIMIT Превышено количество одновременных соединений (потоки)
405	BLOCKED_REQUEST Источник вернул информацию о заблокированном запросе. Ответ может быть не доступен всегда.
404	TIME_MAX_CONNECT Достигнуто максимальное количество коннектов, при которых ресурс не вернул результата. Повторите попытку позже.
123	IP_NOT_REGISTERED_IN_THE_SYSTEM Сработала защита IP. Текущий IP не совпадает с заданным в ЛК
111	PARAMETER_CONFLICT Вы указали параметры, которые конфликтуют между собой. Например VIN и regNumber. Необходимо указать либо VIN либо regNumber, что-то одно.
15	DATE_ERROR Ошибка значения переданной даты
5	TEST_TIME_OFF Закончился период тестирования
3	TOKEN_BLOCKED_BY_QUALITY_SERVICE Ваш токен заблокирован службой качества. Свяжитесь с технической поддержкой
2	TOKEN_TEHBLOCK Установлена техническая блокировка токена. Включить или выключить можно самостоятельно в настройках безопасности.
1	API_SUSPENDED Работа этого API временно приостановлена. Мы уже в курсе проблемы и занимаемся решением. Повторите запрос позже.

Пример ответа с ошибкой

{"error":"503","message":"TOKEN_NOT_REGISTERED_IN_THE_SYSTEM"}