API: подсказки по банкам
Что умеет
✔️ Ищет кредитные организации:
- по БИК,
- SWIFT,
- ИНН,
- ИНН + КПП,
- названию,
- адресу до улицы.
✔️ Фильтрует по типу: банки, НКО и филиалы.
✔️ Фильтрует по региону или городу.
✔️ Умеет искать как действующие банки, так и банки на ликвидации.
✔️ Учитывает, где вы находитесь (геолокация до города).
Как вызвать
Чтобы вызвать метод, зарегистрируйтесь и подтвердите почту.
Пример запроса:
curl -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Token ${API_KEY}" \ -d '{ "query": "сбербанк" }' \ https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/bank
// https://github.com/hflabs/dadata-csharp var token = "${API_KEY}"; var api = new SuggestClientAsync(token); var result = await api.SuggestBank("сбербанк");
// https://github.com/ekomobile/dadata // Использует API-ключ из переменной окружения DADATA_API_KEY import ( "context" dadata "github.com/ekomobile/dadata/v2" "github.com/ekomobile/dadata/v2/api/suggest" ) func main() { api := dadata.NewSuggestApi() params := suggest.RequestParams{Query: "сбербанк"} result, err := api.Bank(context.Background(), ¶ms) }
var url = "https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/bank"; var token = "${API_KEY}"; var query = "сбербанк"; var options = { method: "POST", mode: "cors", headers: { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token }, body: JSON.stringify({query: query}) } fetch(url, options) .then(response => response.text()) .then(result => console.log(result)) .catch(error => console.log("error", error));
// https://github.com/hflabs/dadata-php $token = "${API_KEY}"; $dadata = new \Dadata\DadataClient($token, null); $result = $dadata->suggest("bank", "сбербанк");
# https://github.com/hflabs/dadata-py from dadata import Dadata token = "${API_KEY}" dadata = Dadata(token) result = dadata.suggest("bank", "сбербанк")
Укажите при вызове:
Content-Type: application/json
.Accept: application/json
.${API_KEY}
— API-ключ.
Тело запроса передавайте в кодировке UTF-8
.
Параметры запроса
Название | Тип | Обяз.? | По умолч. | Описание |
---|---|---|---|---|
query | string | ✓ | Текст запроса | |
count | number | 10 | Количество результатов (максимум — 20) | |
status | array [string] | Ограничение по статусу банка | ||
type | array [string] | Ограничение по типу банка | ||
locations | array [object] | Ограничение по региону или городу | ||
locations_boost | array [object] | Приоритет города при ранжировании |
Что в ответе
Объект с массивом подсказок в поле suggestions
:
Пример ответа
{
"suggestions": [
{
"value": "СБЕРБАНК РОССИИ",
"unrestricted_value": "СБЕРБАНК РОССИИ",
"data": {
"opf": {
"type": "BANK",
"full": null,
"short": null
},
"name": {
"payment": "ПАО СБЕРБАНК",
"full": null,
"short": "СБЕРБАНК РОССИИ"
},
"bic": "044525225",
"swift": "SABRRUMM012",
"inn": "7707083893",
"kpp": "773601001",
"okpo": null,
"correspondent_account": "30101810400000000225",
"treasury_accounts": null,
"registration_number": "1481",
"payment_city": "г. Москва",
"state": {
"status": "ACTIVE",
"actuality_date": 1564532138000,
"registration_date": 677376000000,
"liquidation_date": null
},
"rkc": null,
"cbr": null,
"address": {
"value": "г Москва, ул Вавилова, д 19",
...
},
"phones": null
}
},
...
]
}
Название | Описание |
---|---|
value | Наименование банка |
unrestricted_value | = value |
data.bic | Банковский идентификационный код (БИК) ЦБ РФ |
data.swift | Банковский идентификационный код в системе SWIFT |
data.inn | ИНН |
data.kpp | КПП |
data.registration_number | Регистрационный номер в ЦБ РФ |
data.correspondent_account | Корреспондентский счет в ЦБ РФ |
data.treasury_accounts | Казначейские счета (для УФК) |
data.name | Наименование |
└ payment | — платежное наименование |
└ full | — не заполняется |
└ short | — краткое наименование |
data.payment_city | Город для платежного поручения (поля справочника Tnp + Nnp). |
data.opf | Тип кредитной организации |
└ type | — код типа:
BANK — банк BANK_BRANCH — филиал банка NKO — небанковская кредитная организация (НКО) NKO_BRANCH — филиал НКО RKC — расчетно-кассовый центр CBR - управление ЦБ РФ (март 2021) TREASURY - управление Казначейства (март 2021) OTHER — другой |
└ full | — не заполняется |
└ short | — не заполняется |
data.cbr | Не заполняется. Заполняется через метод «Банк по идентификатору» |
data.address | Адрес регистрации |
└ value | — адрес одной строкой стандартизован, поэтому может отличаться от записанного в справочнике БИК. |
└ unrestricted_value | — адрес одной строкой (полный, с индексом) стандартизован, поэтому может отличаться от записанного в справочнике БИК. |
└ data | — гранулярный адрес |
└ data.source | — адрес одной строкой как в справочнике БИК |
└ data.qc | — код проверки адреса
0 — адрес распознан уверенно 1 или 3 — требуется ручная проверка |
data.state | Состояние |
└ actuality_date | — дата актуальности сведений |
└ registration_date | — дата регистрации |
└ liquidation_date | — дата ликвидации |
└ status | — статус организации
ACTIVE — действующая LIQUIDATING — ликвидируется LIQUIDATED — ликвидирована |
data.okpo | Не заполняется |
data.phone | Не заполняется |
data.rkc | Не заполняется |
Источники данных:
- Справочник БИК Банка России
- Справочник по кредитным организациям
Коды ответа на запрос
HTTP-код ответа | Описание |
---|---|
200 | Запрос успешно обработан |
400 | Некорректный запрос (невалидный JSON или XML) |
401 | В запросе отсутствует API-ключ |
403 | В запросе указан несуществующий API-ключ Или не подтверждена почта Или исчерпан дневной лимит по количеству запросов |
405 | Запрос сделан с методом, отличным от POST |
413 | Слишком большая длина запроса или слишком много условий |
429 | Слишком много запросов в секунду или новых соединений в минуту |
5xx | Произошла внутренняя ошибка сервиса |
Примеры вызова
Фильтр: действующий / ликвидирован
Приоритет города при ранжировании
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Apps Script -
-
Ограничения
Количество условий в параметрах locations
и locations_boost
— не более 10.
Длина запроса (параметр query
) — не более 300 символов.
Количество запросов в день — в соответствии с тарифным планом.
Максимальная частота запросов — 30 в секунду с одного IP-адреса.
Максимальная частота создания новых соединений — 60 в минуту с одного IP-адреса.
Частые вопросы
Почему не находится банк? Я точно знаю, он должен быть
Скорее всего, он ликвидирован. «Дадата» не подсказывает большинство ликвидированных банков, потому что их нет в справочнике Банка России.
Как часто обновляется справочник банков?
Каждый день. Мы берем его с сайта Банка России.
Подсказки не работают: ошибка 403 Forbidden (Feature SUGGESTIONS disabled for token)
Возможные причины:
- Не подтверждён адрес эл. почты. Проверьте в личном кабинете. Если почта не подтверждена — посмотрите почтовый ящик и папку «спам», там должно быть письмо от «Дадаты».
- В запросе указан неправильный API-ключ. Проверьте в личном кабинете
- Исчерпан лимит запросов на день. Проверьте в личном кабинете
Что будет, если превысить 10 000 бесплатных запросов в день?
Подсказки перестанут подсказывать ツ До начала нового дня, затем снова заработают.
10 000 запросов считаются суммарно по всем видам подсказок: адреса, ФИО, организации, банки, емейлы...
Стоимость
Бесплатно до 10 тысяч запросов в день. Больше — в составе годовой подписки.