REST API JSON / UTF-8

Документация API

Базовый адрес: https://anydata.any-cloud.ru. Все методы принимают и возвращают JSON в UTF-8. Пути совместимы с DaData: подсказки — /suggestions/api/4_1/rs/…, стандартизация — /api/v1/clean/…. Достаточно заменить в клиентской библиотеке базовые URL suggestions.dadata.ru и cleaner.dadata.ru на https://anydata.any-cloud.ru.

Аутентификация

Ключ выдаётся в разделе Ключи. Передаётся в заголовке:

Authorization: Token 0123456789abcdef…
X-Secret: …            # только если для ключа включена проверка секрета

Также принимаются Authorization: Bearer …, заголовок X-Api-Key и параметр ?token=. Ответы содержат CORS-заголовки, так что вызывать API можно прямо из браузера.

Стандартизация (clean)

POST /api/v1/clean/{type}, тело — массив строк (до 100). Типы: address, phone, name, email, passport, birthdate, vehicle.

curl -X POST https://anydata.any-cloud.ru/api/v1/clean/phone \
  -H "Authorization: Token КЛЮЧ" -H "Content-Type: application/json" \
  -d '["8 495 123 45 67 доб 12", "9161234567"]'

[{"source":"8 495 123 45 67 доб 12","type":"Стационарный","phone":"+7 495 123-45-67",
  "country_code":"7","city_code":"495","number":"1234567","extension":"12","provider":null,
  "country":"Россия","region":"Москва","city":"Москва","timezone":"UTC+3","qc_conflict":0,"qc":0}, …]

Тип	Что возвращает	qc
`address`	индекс, регион (с кодами КЛАДР/ISO, федеральный округ, часовой пояс), район, город, населённый пункт, улица, дом, корпус/строение, квартира, `fias_id` и КЛАДР при загруженном ГАР, `fias_level`, `unparsed_parts`, `qc_complete`	0 — разобран, 1 — есть нераспознанные части, 2 — мусор
`phone`	тип (мобильный/стационарный), код страны, код города, номер, добавочный, оператор и регион (по плану нумерации Россвязи), часовой пояс	0 — ок, 1 — код не подтверждён, 2 — не распознан, 3 — несколько номеров
`name`	фамилия, имя, отчество, пол (М/Ж/НД), результат в именительном, родительном, дательном и творительном падежах	0 — ок, 1 — сомнительно, 2 — мусор
`email`	нормализованный адрес, локальная часть, домен, тип (PERSONAL, CORPORATE, ROLE, DISPOSABLE)	0 — ок, 1 — некорректный, 2 — пусто, 3 — одноразовый, 4 — исправлена опечатка
`passport`	серия «45 09», номер	0 — ок, 1 — не распознан, 2 — пусто
`birthdate`	дата в формате ДД.ММ.ГГГГ	0 — ок, 1 — не распознана, 2 — пусто
`vehicle`	марка и модель в верхнем регистре латиницей	0 — марка распознана, 1 — нет, 2 — пусто

Составной запрос: POST /api/v1/clean с телом {"structure": ["NAME", "PHONE", "AS_IS"], "data": [["Иванов Иван", "89161234567", "x"]]}.

Компании и ИП

POST /suggestions/api/4_1/rs/findById/party — по ИНН или ОГРН. Параметры: query, kpp, branch_type (MAIN/BRANCH), type (LEGAL/INDIVIDUAL), count.

POST /suggestions/api/4_1/rs/suggest/party — по названию, ИНН или ОГРН. Параметр status: ["ACTIVE"].

curl -X POST https://anydata.any-cloud.ru/suggestions/api/4_1/rs/findById/party \
  -H "Authorization: Token КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"query": "7736207543"}'

{"suggestions":[{"value":"ООО \"ЯНДЕКС\"","unrestricted_value":"ООО \"ЯНДЕКС\"","data":{
  "inn":"7736207543","kpp":"770401001","ogrn":"1027700229193","type":"LEGAL",
  "name":{"full_with_opf":"ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ \"ЯНДЕКС\"","short_with_opf":"ООО \"ЯНДЕКС\"", …},
  "opf":{"code":"12300","short":"ООО","full":"Общество с ограниченной ответственностью"},
  "management":{"name":"…","post":"ГЕНЕРАЛЬНЫЙ ДИРЕКТОР"},
  "state":{"status":"ACTIVE","registration_date":1032300000000, …}, "branch_type":"MAIN", "region":"г Москва", "source":"egrul"}}]}

Источник — открытый поиск ЕГРЮЛ/ЕГРИП ФНС; карточки кэшируются на 30 дней. Если задан токен DaData, он используется как второй поставщик и отдаёт полные карточки (адрес, ОКВЭД, учредители, финансы) в исходном формате DaData.

Банки

POST /suggestions/api/4_1/rs/findById/bank — по БИК, SWIFT, корсчёту или регистрационному номеру. suggest/bank — по названию или началу БИК.

curl -X POST https://anydata.any-cloud.ru/suggestions/api/4_1/rs/findById/bank \
  -H "Authorization: Token КЛЮЧ" -H "Content-Type: application/json" -d '{"query": "044525225"}'

{"suggestions":[{"value":"ПАО Сбербанк","unrestricted_value":"ПАО Сбербанк","data":{
  "opf":{"type":"BANK"},"name":{"payment":"ПАО Сбербанк"},"bic":"044525225","swift":"SABRRUMM",
  "correspondent_account":"30101810400000000225","registration_number":"1481","payment_city":"г Москва",
  "state":{"status":"ACTIVE", …},"address":{"value":"117312, г Москва, ул Вавилова, д 19", …}}}]}

Адреса

POST /suggestions/api/4_1/rs/suggest/address — подсказки по строке; параметр locations ([{"kladr_id": "77"}] или [{"region": "Московская"}]) ограничивает регион. Первой подсказкой идёт разобранный вариант введённой строки; при загруженном ГАР добавляются объекты справочника. findById/address — по fias_id (нужен ГАР). Отдельные уровни: suggest/region, suggest/city, suggest/street.

curl -X POST https://anydata.any-cloud.ru/api/v1/clean/address \
  -H "Authorization: Token КЛЮЧ" -H "Content-Type: application/json" \
  -d '["Московская область, г. Химки, ул. Ленина, д.1, к.2, кв. 5"]'

[{"source":"…","result":"Московская обл, г Химки, ул Ленина, д 1, к 2, кв 5","postal_code":null,
  "country":"Россия","country_iso_code":"RU","federal_district":"Центральный",
  "region_kladr_id":"5000000000000","region_iso_code":"RU-MOS","region_with_type":"Московская обл","region_type":"обл","region":"Московская",
  "city_with_type":"г Химки","city":"Химки","street_with_type":"ул Ленина","street_type":"ул","street":"Ленина",
  "house_type":"д","house":"1","block_type":"к","block":"2","flat_type":"кв","flat":"5",
  "fias_level":"9","timezone":"UTC+3","qc_complete":0,"qc":0, …}]

ФИО, e-mail, страны, валюты

suggest/fio — разбор строки на фамилию/имя/отчество с полом (gender: MALE/FEMALE/UNKNOWN).
suggest/email — нормализация и тип адреса.
suggest/country, findById/country — ISO 3166 (коды alfa2/alfa3/цифровой, телефонный код).
suggest/currency, findById/currency — ISO 4217.
suggest/fms_unit, findById/fms_unit — коды подразделений (после загрузки справочника).

Проверка реквизитов

GET /api/v1/validate/{type}?value=… или POST с телом {"value": "…"} / массивом строк. Типы: inn, ogrn (и ОГРНИП), snils, kpp, bik, okpo, account и corr_account (нужен bik).

curl "https://anydata.any-cloud.ru/api/v1/validate/inn?value=7707083893" -H "Authorization: Token КЛЮЧ"
{"source":"7707083893","value":"7707083893","kind":"inn_legal","valid":true}

curl -X POST https://anydata.any-cloud.ru/api/v1/validate/account -H "Authorization: Token КЛЮЧ" \
  -H "Content-Type: application/json" -d '{"value":"40702810…","bik":"044525225"}'

Ошибки и лимиты

Ошибки возвращаются в формате DaData: {"family":"CLIENT_ERROR","reason":"Forbidden","message":"…"}. Коды: 400 — некорректный запрос, 401 — нет ключа, 403 — неверный/отключённый ключ или нет X-Secret, 404 — неизвестный справочник, 413 — больше 100 записей, 429 — исчерпан суточный лимит ключа.

Служебные методы: GET /api/v1/status — состояние справочников, GET /api/v1/stat/date?date=YYYY-MM-DD — статистика по ключу, GET /api/v1/profile/balance, GET /api/v1/version.

Совместимость с DaData

Поддерживаются: suggest/party, findById/party, suggest/bank, findById/bank, suggest/address, findById/address, suggest/fio, suggest/email, suggest/country, suggest/currency, suggest/fms_unit, clean/*, составной clean, profile/balance, stat/date, version. Метод iplocate/address отвечает {"location": null}. Геокоординаты, метро, налоговая инспекция не заполняются (null).

Примеры для библиотек: Python dadata — Dadata(token, secret), затем client._suggestions_url = "https://anydata.any-cloud.ru/suggestions/api/4_1/rs/"; PHP/JS — подмените базовый URL в настройках клиента.