API

Данное описание является предварительным и может меняться. Все изменения будут отражены на данной странице. По всем вопросам "боевой" эксплуатации АПИ - просим связываться по телефону + 7 499 670-1111 (Александр)

Общие принципы

Работа с API производится по адресу https://amelkina.ru/api.php при помощи POST запросов по протоколу https

Запросы и ответы кодируются в utf-8

Запросы

Все параметры запросов размещаются в POST-переменных.

Двоичные данные (файлы) должны быть закодированы в base64

XML файлы уведомлений перед отправкой должны быть зашифрованы при помощи открытого ключа сертификата транспортного шифрования.

Любой запрос имеет как минимум два обязательных параметра:

  • clientGUID - VARCHAR(128) - Уникальный ключ разработчика. Выдается по запросу конкретному разработчику. В случае обнаружения ДДОС атаки или иных "проблемных" запросов - ключ, с использованием которого была произведена данная атака - будет заблокирован и потребует замены. Ключ не привязан к конкретному пользователю (банку) и может использоваться разработчиком для автоматизации взаимодействия разных пользователей с сервисом.
  • action - VARCHAR(128) - наименование выполняемой функции

Все остальные параметры зависят от выполняемой функции и описываются в соответствующих разделах.

Ответы

Ответы возвращаются в формате JSON в объекте с 4 обязательными полями:

  • result - Результат выполнения функции. boolean. true - функция выполнена успешно.
  • errorCode - Код ошибки при наличии. Зполняется только при result != true. Важно! код ошибки может быть равен нулю Это НЕ означает успешного выполнения, просто источник ошибки не имеет присвоенного кода ошибки.
  • errorMessage - Текст ошибки при наличии. Заполняется только при result != true.
  • data - Результат выполнения функции (если есть). В случае двоичных данных - кодируется в base64

Пример ответа сервера в случае ошибки:

{"result":false,"errorCode":-1,"errorMessage":"\u041d\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043d\u0430\u044f \u043e\u0448\u0438\u0431\u043a\u0430","data":null}

Пример ответа сервера в случае нормального выполнения:

{"result":true,"errorCode":null,"errorMessage":null,"data":777}

Функции

usersSignatureChallenge - Инициализация авторизации/регистрации посредством ЭП

Параметры: нет

Возвращаемое значение: {"key":"f90...17cb","random":"19e65...ad87"} - Идентификатор случайной строки и сама случайная строка.

Важно! Время жизни (TTL) выданной ключевой пары 2 минуты, поэтому данную функцию следует вызывать непосредственно перед подписыванием, после инициализации крипто-библиотек и т.п.

usersSignatureRegister - Регистрация посредством ЭП

Параметры:

key VARCHAR(255) Идентификатор случайной строки Key полученный с помощью функции usersSignatureChallenge()
signature BLOB Отделенная подпись случайной строки полученной с помощью функции usersSignatureChallenge(). Должно быть закодировано в base64.
email VARCHAR(255) E-mail пользователя
idRole VARCHAR(16) Роль пользователя. На данный момент должно всегда быть "bank"
orgName VARCHAR(255) Полное наименование огранизации
orgINN VARCHAR(20) ИНН огранизации
orgKPP VARCHAR(20) КПП огранизации
phoneNumber VARCHAR(255) Номер телефона
phoneCode VARCHAR(255) Добавочный номер / контактное лицо

Возвращаемое значение: ssid - VARCHAR(255) - идентификатор сессии.

Идентификатор сессии должен быть сохранен клиентом до окончания сеанса работы (сессии) для вызова всех остальных функций API.

usersSignatureLogin - Авторизация посредством ЭП

Параметры:

  • key - VARCHAR(255) - Идентификатор случайной строки полученный с помощью функции usersSignatureChallenge()
  • signature - BLOB - Отделенная подпись случайной строки полученной с помощью функции usersSignatureChallenge(). Должно быть закодировано в base64.

Возвращаемое значение: ssid - VARCHAR(255) - идентификатор сессии.

Идентификатор сессии должен быть сохранен клиентом до окончания работы для вызова всех остальных функций API.

usersLogin - Авторизация по логину и паролю

Параметры:
  • login - VARCHAR(255) - Логин
  • password - VARCHAR(255) - Пароль
  • salt - VARCHAR(255) - Случайная строка (соль) используемая для повышения криптографического качества идентификатора сессии. Может быть установлена в NULL (в этом случае соль будет сгенерирована с использованием встроенных функций mysql)
Возвращаемое значение: ssid - VARCHAR(255) - идентификатор сессии. Идентификатор сессии должен быть сохранен клиентом до окончания работы для вызова всех остальных функций API.
 

usersSelectRowEx - Получить данные пользователя (включая баланс)

Параметры:
  • ssid - VARCHAR(255) - Идентификатор сессии полученный с помощью usersSignatureRegister(...) или usersLogin(...) или usersSignatureLogin (...)
Возвращаемое значение: array - массив данных пользователя

usersLogout - Завершение рабочей сессии.

Параметры:
  • ssid - VARCHAR(255) - Идентификатор сессии полученный с помощью usersSignatureRegister(...) или usersLogin(...) или usersSignatureLogin (...)
Возвращаемое значение: null

certificatesInsert - Регистрация нового сертификата ЭП.

Параметры:
  • ssid - VARCHAR(255) - Идентификатор сессии полученный с помощью usersSignatureRegister(...) или usersLogin(...) или usersSignatureLogin (...)
  • certificate - BLOB - Сертификат. Должно быть закодировано в base64.
  • canLogin - TINYINT(1) - Сертификат может быть использован для авторизации
  • canSign - TINYINT(1) - Сертификат может быть использован для подписывания уведомлений о залогах
Возвращаемое значение: idCertificate - INT - идентификатор зарегистрированного сертификата.
 

pledgesInsert - Создание нового уведомления о залоге.

Параметры:

ssid VARCHAR(255) Идентификатор сессии полученный с помощью usersSignatureRegister(...) или usersLogin(...) или usersSignatureLogin (...)
content LONGBLOB Содержимое уведомления о залоге (XML). Значение должно быть закодировано в base64
signature TEXT Подпись уведомления о залоге. Значение должно быть закодировано в base64
fileName TEXT задаваемый пользователем идентификатор

Возвращаемое значение: idPledge - INT - Идентификатор созданного уведомления

 
 

pledgesSelect - Получение таблицы с данными уведомлений

Параметры:

ssid VARCHAR(255) Идентификатор сессии полученный с помощью usersSignatureRegister(...) или usersLogin(...) или usersSignatureLogin (...)
idPledge INT Фильтр по коду уведомления. Игнорируется если не задан
idNotificationStatus INT Фильтр по коду статуса. Игнорируется если не задан
selectData TINYINT(1) Если равно 1 - будут выбраны поля content и signature. Если не задан или имеет другое значение, то в этих полях будет возвращено NULL. Экономит траффик при выборке списка, когда не требуется содержимое этих полей.
selectReport TINYINT(1) Если равно 1 - будут выбраны поля ReportXML и ReportSIG. Если не задан или имеет другое значение, то в этих полях будет возвращено NULL. Экономит траффик при выборке списка, когда не требуется содержимое этих полей.
limitOffset INT Индекс первой записи выборки (смещение в выражении LIMIT). Использутеся для постаничной выборки.
limitCount INT Количество записей в выборке (количество в выражении LIMIT). Использутеся для постаничной выборки.
fileName TEXT Фильтр по имени файла. Игнорируется если не задан

Возвращаемое значение: JSON объект - Объект содержит поле data типа array of object содержащее данные и поле foundRows содержащее полное количество записей в выборке (результат SELECT FOUND_ROWS())

Данные отфильтрованы в соответствии с заданными параметрами и отсортированы по полю idPledge в обратном порядке (от новых к старым)

 
 

pledgesDelete - Инициировать процесс удаления уведомления

Параметры:

ssid VARCHAR(255) Идентификатор сессии полученный с помощью usersSignatureRegister(...) или usersLogin(...) или usersSignatureLogin (...)
idPledge INT Код уведомления.

Возвращаемое значение: Нет

Важно! Удаление возможно только для уведомлений со статусом 1 и 10

 
 

pledgesErrorsSelect - Получить таблицу ошибок уведомления

Параметры:
  • ssid - VARCHAR(255) - Идентификатор сессии полученный с помощью usersSignatureRegister(...) или usersLogin(...) или usersSignatureLogin (...)
  • idPledge - INT - Код уведомления.
Возвращаемое значение: array of array  
 

notificationStatusesSelect - Получить таблицу расшифровок кодов статуса уведомлений

Параметры: нет

Возвращаемое значение: array of object - Массив записей таблицы кодов статуса уведомлений

 
 

pledgeSigPersonChecksSelect - Получить таблицу результатов проверок подписи уведомления

Параметры:
  • ssid - VARCHAR(255) - Идентификатор сессии полученный с помощью usersSignatureRegister(...) или usersLogin(...) или usersSignatureLogin (...)
  • idPledge - INT - Код уведомления.
Возвращаемое значение: array of array