Инструкция по работе с API v1 BS1 Банк

Данное API позволяет создавать и редактировать платежные реквизиты организаций, а так же создавать счета на оплату в системе "BS1 Банк".

Адрес страницы для обращения к API https://api.money.bs1.org/v1. При интеграции партнерских систем, необходимо учитывать что адрес API может быть изменен, поэтому необходимо заложить возможность быстрой замены адреса на стороне партнера.

Для доступа к API каждому партнеру выдается ключ доступа, который нужно использовать в каждом POST запросе. Ключ не должен использоваться в открытом коде, иначе он будет скомпроментирован и заблокирован. Ответы предоставляются в массиве JSON. Обращения должны поступать исключительно с обработчика партнера и его ip, даже если речь идет об интеграции дескопных или мобильных программ и приложений. Любой ключ в системе имеет последнюю контрольную цифру, поэтому для снижения нагрузки на API, перед запросом необходимо проверять ключ по алгоритму Луна, либо посредством JS на стороне клиента, либо в собственном обработчике перед запросом к API (предоставим готовые скрипты по запросу).

Электронная карточка и ключ организации

Запрос	Тип запроса	Описание
Создание организации	org_add	Электронная карточка организации может использоваться как для заключения договора, и создания других документов, так и для выставления счета, из этого складывается список необходимых параметров для ее заполнения. Поскольку одна организация может иметь несколько счетов в банке, то в системе "BS1 Банк" возможно создание нескольких карточек одной организации с разными платежными реквизитами. Создание одинаковых карточек с одинаковыми реквизитами невозможно. Параметры POST запроса: key - Ключ доступа - обязательный параметр typo - Тип запроса - обязательный параметр inn - ИНН организации (только цифры, мин. 10 симв.) - обязательный параметр ogrn - ОГРН организации (только цифры, мин. 13 симв.) - обязательный параметр kpp - КПП организации (только цифры, мин. 9 симв.) - необязательный параметр okved - Коды ОКВЭД - необязательный параметр okpo - Код ОКПО - необязательный параметр okato - Код ОКАТО - необязательный параметр okogu - Код ОКОГУ - необязательный параметр oktmo - Код ОКТМО - необязательный параметр full_name - Полное наименование - обязательный параметр short_name - Краткое наименование - обязательный параметр adress1 - Юридический адрес - обязательный параметр adress2 - Фактический адрес - обязательный параметр adress3 - Почтовый адрес - обязательный параметр main_name - Должность руководителя (необязательно для ИП) - обязательный параметр main - ФИО руководителя (необязательно для ИП) - обязательный параметр main_doc - Основание действий руководителя (необязательно для ИП) - обязательный параметр phone - Номер телефона (только цифры, мин. 11 симв.) - обязательный параметр email - Email - обязательный параметр bank_acc - Номер счета (только цифры, мин. 20 симв.) - обязательный параметр bik - БИК банка (только цифры, мин. 9 симв.) - обязательный параметр bank - Наименование банка - обязательный параметр ks - Корр. счет (только цифры, мин. 20 симв.) - обязательный параметр nds - Является ли плательщиком НДС (1 или 2) - обязательный параметр В случае ошибки система выдаст "status":"error", в случае успешного запроса, система выдаст ключ организации и пароль для редактирования информации через API. Пример ответа на успешный запрос: {"status":"ok","pass":"578234","key_org":"7816-0000-0017"}.
Редактирование организации	org_edit	Метод редактирования ранее созданной карточки организации при наличии пароля на редактирование, полученного при создании. Редактировать можно все данные кроме ИНН, ключа организации и пароля на редактирование. Параметры POST запроса: key - Ключ доступа - обязательный параметр typo - Тип запроса - обязательный параметр inn - ИНН организации (только цифры, мин. 10 симв.) - обязательный параметр pass - Пароль на редактирование - обязательный параметр key_org - Ключ организации - обязательный параметр ogrn - ОГРН организации (только цифры, мин. 13 симв.) - обязательный параметр kpp - КПП организации (только цифры, мин. 9 симв.) - необязательный параметр okved - Коды ОКВЭД - необязательный параметр okpo - Код ОКПО - необязательный параметр okato - Код ОКАТО - необязательный параметр okogu - Код ОКОГУ - необязательный параметр oktmo - Код ОКТМО - необязательный параметр full_name - Полное наименование - обязательный параметр short_name - Краткое наименование - обязательный параметр adress1 - Юридический адрес - обязательный параметр adress2 - Фактический адрес - обязательный параметр adress3 - Почтовый адрес - обязательный параметр main_name - Должность руководителя (необязательно для ИП) - обязательный параметр main - ФИО руководителя (необязательно для ИП) - обязательный параметр main_doc - Основание действий руководителя (необязательно для ИП) - обязательный параметр phone - Номер телефона (только цифры, мин. 11 симв.) - обязательный параметр email - Email - обязательный параметр bank_acc - Номер счета (только цифры, мин. 20 симв.) - обязательный параметр bik - БИК банка (только цифры, мин. 9 симв.) - обязательный параметр bank - Наименование банка - обязательный параметр ks - Корр. счет (только цифры, мин. 20 симв.) - обязательный параметр nds - Является ли плательщиком НДС (1 или 2) - обязательный параметр В случае ошибки система выдаст "status":"error", в случае успешного запроса, система выдаст ключ организации и пароль для редактирования информации через API. Пример ответа на успешный запрос: {"status":"ok"}.
Запрос информации об организации	org	Пример ключа организации: 7816-0000-0017, где первые 4 цифры обозначают код налогового органа, далее с 5 по 11 цифры ключа это порядковый номер в подсистеме, и последняя цифра контрольная (алгоритм Луна). Параметры POST запроса: key - Ключ доступа - обязательный параметр typo - Тип запроса - обязательный параметр key_org - Ключ организации - обязательный параметр В случае ошибки система выдаст "status":"error", в случае успешного запроса, система выдаст массив данных организации в формате JSON.

Создание электронных платежных поручений

Запрос	Тип запроса	Описание
Создание счета на оплату	pay_add	Создание электронного платежного поручения, для быстрого ввода реквизитов в интегрированных в "BS1 Банк" кредитных учреждениях. В результате успешного запроса, система выдает ключ платежа, который получатель платежа передает плательщику. Параметры POST запроса: key - Ключ доступа - обязательный параметр typo - Тип запроса - обязательный параметр full_name - Полное наименование - обязательный параметр inn - ИНН организации (только цифры, мин. 10 симв.) - обязательный параметр kpp - КПП организации (только цифры, мин. 9 симв.) - необязательный параметр bank_acc - Номер счета (только цифры, мин. 20 симв.) - обязательный параметр bik - БИК банка (только цифры, мин. 9 симв.) - обязательный параметр bank - Наименование банка - обязательный параметр ks - Корр. счет (только цифры, мин. 20 симв.) - обязательный параметр uip - Код УИП - необязательный параметр sum - Сумма - обязательный параметр purpose - Назначение платежа, с комментарием об отсутствии НДС либо сумме НДС - обязательный параметр turn - Очередность платежа (по умолчанию 5) - обязательный параметр day - Срок действия счета (по умолчанию 7, максимум 30) - обязательный параметр email - Емайл получателя (при запросе не выводится, используется только для уведомления об исполнении платежа) - необязательный параметр В случае ошибки система выдаст "status":"error", в случае успешного запроса, система выдаст ключ платежа. Пример ответа на успешный запрос: {"status":"ok","key_pay":"6240-7419-0000-0015"}.
Запрос информации о счете	pay	Данный запрос можно делать с ключом доступа партнера, и параметром "pass", полученном при создании платежа. Банки-партнеры получают доступ к информации в полном объеме без ограничений без параметра "pass". Мы исходим из того, что получатель платежа, создав счет в системе "BS1 Банк" и получив ключ платежа, передает его напрямую без посредников корректным способом. Поэтому наша основная задача, чтобы при вводе плательщиком ключа при оплате, подгружались именно те данные, которые ввел получатель платежа. Чтобы исключить всякий смысл в подмене данных злоумышленниками, ключ платежа содержит данные, которые можно сравнить с данными реквизитов получателя. Для примера, первые 8 цифр ключа 6240-7419-0000-0015, содержат 4 последние цифры ИНН получателя, далее 2 последние цифры БИК банка получателя, и далее 2 последние цифры номера счета в банке получателя. Если каким-то образом, в базе "BS1 Банк" реквизиты получателя были изменены, то при запросе информации по ключу, наша система проводит проверку, сравнивает параметры, и в случае несовпадения, выведет только ошибку pay incorrect. Банки-партнеры обязательно на своей стороне, как серверными скриптами, так и браузерными, должны так же проводить дополнительную проверку по данному алгоритму. С 9 по 15 цифры ключа это порядковый номер в подсистеме, и последняя цифра контрольная (алгоритм Луна). Параметры POST запроса: key - Ключ доступа - обязательный параметр typo - Тип запроса - обязательный параметр key_pay - Ключ платежа - обязательный параметр pass - Пароль (необязательно для банка) - обязательный параметр В случае ошибки система выдаст "status":"error", в случае успешного запроса, система выдаст массив данных организации в формате JSON.

Список возможных системных сообщений

В случае ошибки, система выдает массив JSON с описанием ошибки, например: {"status":"error","msg":"inactive"}, в случае успешной обработки запроса система выдаст {"status":"ok"} и массив запрашиваемых данных.

Сообщение	Описание
inactive	Система неактивна, например закрыта на технические работы. В этом случае рекомендуем предложить пользователям, обратиться позднее.
no key	Не указан ключ доступа.
locked key	Данный ключ доступа по какой-то причине заблокирован.
invalid key	Указан неверный ключ доступа.
no ip access	Если ваши обращения принимаются только с определенных IP, то данная ошибка показывает что IP с которого было обращение не входит в список ваших IP.
no typo	Не указан тип запроса.
wrong typo	Указан неверный тип запроса.
invalid number key_org	Неверное количество символов в параметре key_org
digit in key_org	Неверная контрольная цифра в параметре key_org
invalid number key_pay	Неверное количество символов в параметре key_pay
digit in key_pay	Неверная контрольная цифра в параметре key_pay
no data + параметр	Отсутствует информация по указанному обязательному параметру в запросе.
wrong + параметр	Указан некорректный параметр, например емайл в неправильном формате.
org exist	Организация с такими платежными реквизитами уже есть в базе.
org not exist	Организации с такими платежными реквизитами нет в базе.
wrong pass	Неправильный пароль.
pay exist	Счет с такими параметрами уже есть в базе.
pay not exist	Платежа с такими параметрами нет в базе.
pay incorrect	Данные в ключе и реквизитах несовпадают.
pay expired	Истек срок действия счета на оплату.