Документация по работе с API Федеральная налоговая служба
Алгоритм получения результата запроса с помощью нашего сервиса достаточно прост и практически одинаков для всех видов ресурсов.
Получите ваш персональный ключ API в настройках вашего аккаунта.
для каждого пользователя генерируется уникальный аутентификационный токен, мы называем "персональный ключ API". Это строка из 32 символов, которая выглядит примерно так:
53ba1b7a55abbа14aa97eff3a5220792
Этот ключ используется для всех ваших запросов к api-cloud.
Отправьте запрос HTTP GET на URL нашего API: https://api-cloud.ru/api/nalog.php с персональным ключом API и параметрами.
Сервер вернёт результат обработки или код ошибки, если что-то пошло не так.
Сервер возвращает ответ в формате JSON
Базовая цена запроса: 0.6 руб.
История изменений/обновлений
| type (тип) | Описание | Параметры в запросе |
|---|---|---|
| В одном запросе возможно отправить только 1 тип | ||
| inn | Поиск ИНН физического лица |
Обязательные lastname - Фамилия Разрешено: латиница, цифры, знак "-" firstname - Имя Разрешено: латиница, цифры, знак "-" birthdate - Дата рождения Разрешено: цифры, знак "." serianomer - Серия и номер паспорта (без пробелов) Разрешено: цифры token - персональный ключ API Дополнительные secondname - Отчество Разрешено: латиница, цифры, знак "-" |
| npd new! | Проверить статус налогоплательщика налога на профессиональный доход (самозанятого) |
Обязательные inn - ИНН физического лица Разрешено: цифры (валидация номера) token - персональный ключ API Дополнительные date - Дата, на которую производить проверку (формат 15.02.2024). Если параметр не передан, то производим поиск на сегодняшний день. Разрешено: цифры, знак "." (валидация корректной даты) |
Обратите внимание, что скорость загрузки результата зависит напрямую от ресурса источника
При подсчете количества запросов будут приняты к учету только те запросы, которы вернули "status": 200 и "status": 404, т.е. получили результат.
При подсчете количества запросов будут приняты к учету только те запросы, которы вернули "status": 200 и "status": 404, т.е. получили результат.
Максимальное количество попыток соединения 3 раза. Если в результате этих попыток ресурс не вернет ответа, то API CLOUD вернет ответ {"status":404, "error":"TIME_MAX_CONNECT", "errormsg":"Достигнуто максимальное количество коннектов, при которых ресурс не вернул результата"}
Примеры запросов
Поиск ИНН физического лица
Пример запроса "Поиск ИНН физического лица" HTTP GET на URL нашего API
Пример успешного запроса по типу inn с сайта Федеральная налоговая служба в формате JSON
https://api-cloud.ru/api/nalog.php?type=inn&firstname=ФАМИЛИЯ&lastname=ИМЯ&secondname=ОТЧЕСТВО&birthdate=**.03.19**&serianomer=99999999&token=53ba1b7a55abbB014aa97eff3a522079
Есть данные об ИНН
{
"status":200,
"found" => true,
"inn":"****1095****",
// Информация о запросе
"inquiry": {
"price": 0.8, // Списание за запрос
"balance": 100462.11, // Баланс после текущего запроса
"speed": 1, // Скорость запроса
"attempts": 1 // Попыток
}
}
ИНН не найден
{
"status":200,
"found": false,
"message":"Информация об ИНН не найдена",
// Информация о запросе
"inquiry": {
"price": 0.8, // Списание за запрос
"balance": 100462.11, // Баланс после текущего запроса
"speed": 1, // Скорость запроса
"attempts": 1 // Попыток
}
}
Сервис ФНС временно не доступен или ведутся технические работы
{"status":404,"message":"Сервис ФНС временно не доступен или ведутся технические работы"}
Проверить статус налогоплательщика налога на профессиональный доход (самозанятого)
Пример запроса "Проверить статус налогоплательщика налога на профессиональный доход (самозанятого)" HTTP GET на URL нашего API
Пример успешного запроса по типу npd с сайта Федеральная налоговая служба в формате JSON
https://api-cloud.ru/api/nalog.php?type=npd&inn=111111111111&token=53ba1b7a55abbB014aa97eff3a522079
ИНН является налогоплательщиком на профессиональный доход
{
"status": 200, // Статус ответа
"found": true, // Результат поиска
"inn": "111111111111", // ИНН по которому производили поиск
"date": "13.02.2022", // Дата на которую производили поиск
"NPD": 1, // Статус НПД (1 - является налогоплательщиком на профессиональный доход)
"message": "111111111111 является плательщиком налога на профессиональный доход", // Текстовое уведомление
"inquiry": {
"price": 0.6,
"balance": 10033.7,
"speed": 23,
"attempts": 1
}
}
ИНН НЕ является налогоплательщиком на профессиональный доход
{
"status": 200, // Статус ответа
"found": true, // Результат поиска
"inn": "111111111111", // ИНН по которому производили поиск
"date": "13.02.2022", // Дата на которую производили поиск
"NPD": 0, // Статус НПД (0 - НЕ является налогоплательщиком на профессиональный доход)
"message": "111111111111 не является плательщиком налога на профессиональный доход", // Текстовое уведомление
"inquiry": {
"price": 0.6,
"balance": 10033.7,
"speed": 23,
"attempts": 1
}
}
История изменений API Федеральная налоговая служба
| дата | что изменилось |
|---|---|
| 16.02.2024 | Появился новый тип запроса "npd". |
| 26.01.2024 | Добавлен новый обработчик ошибки при некорректной передаче даты рождения. |
| 17.08.2023 | Адаптация под источник |
| 15.03.2023 | 1. Скорректировали обязательные параметры запроса. Отчество исключено из обязательных. |
| 23.10.2022 | В массив inquiry добавили ключ balance. Вывод текущего баланса после запроса, позволит не отправлять дополнительные запросы на проверку баланса. |
| 14.06.2022 | Поиск ИНН физического лица, пофиксили сбои в работе, ускорили работу. |
| 06.04.2022 | Переработан алгоритм получения ИНН |
| 28.03.2022 | Переработан алгоритм. Изменение вывода у первоисточника. |
| 21.03.2022 | В случае проведения технических работ на стороне ФНС или недоступности будет выведена ошибка |
| 18.11.2021 | Информация о запросе в массиве inquiry |
Возможные коды ошибок
| код (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 |
| 500 | MISSING_REQUIRED_TYPE_PARAMETER Отсутствует параметр type |
| 499 | WRONG_TOKEN_KEY Вы указали значение параметра token в неверном формате, ключ должен содержать 32 символа. |
| 498 | TOKEN_NO_MONEY Для выполнения запроса недостаточно средств, пополните баланс. |
| 460 | NO_REQUIRED_PARAMETERS Отсутствуют обязательные параметры |
| 456 | MAX_LIMIT Превышено количество одновременных соединений (потоки) |
| 404 | TIME_MAX_CONNECT Достигнуто максимальное количество коннектов, при которых ресурс не вернул результата. Повторите попытку позже. |
| 123 | IP_NOT_REGISTERED_IN_THE_SYSTEM Сработала защита IP. Текущий IP не совпадает с заданным в ЛК |
| 115 | MISSING_MANDATORY_PARAMETERS Отсутствуют обязательные параметры |
| 111 | PARAMETER_CONFLICT Вы указали параметры, которые конфликтуют между собой. Например VIN и regNumber. Необходимо указать либо VIN либо regNumber, что-то одно. |
| 102 | MISSING_REQUIRED_secondname_PARAMETER Неверно указан параметр lastname |
| 101 | MISSING_REQUIRED_lastname_PARAMETER Отсутствует параметр lastname или указан неверно |
| 100 | MISSING_REQUIRED_firstname_PARAMETER Отсутствует параметр firstname или указан неверно |
| 015 | DATE_ERROR Ошибка значения переданной даты |
| 012 | MISSING_DATE_PARAMETER Ошибка в переданном параметре date |
| 011 | MISSING_REQUIRED_inn_PARAMETER Параметр inn передан с ошибками или не соответствует маске |
| 010 | MISSING_INN_PARAMETER Отсутствует обязательный параметр inn |
| 005 | TEST_TIME_OFF Закончился период тестирования |
| 001 | API_SUSPENDED Работа этого API временно приостановлена. Мы уже в курсе проблемы и занимаемся решением. Повторите запрос позже. |
{"error":"503","message":"TOKEN_NOT_REGISTERED_IN_THE_SYSTEM"}
