API

API позволяет разработчикам интегрировать свои приложения с системой Capitalist для загрузки платежей в систему в автоматическом режиме.

Требования

Для работы с API, вы должны иметь статус Проверенного бизнес-пользователя. Доступ к API включается после согласования со Службой поддержки.

Все финансовые операции, осуществляемые через API, подписываются при помощи «сертификата безопасности», поэтому для Вашего аккаунта должна быть активирована опция «Cертификат». Активировать опцию можно на странице Настроек безопасности в разделе Профиль.

Необходимые данные для работы с API

  • Имя пользователя (не e-mail)
  • Пароль
  • Файл сертификата
  • Пароль к файлу сертификата, если он зашифрован
  • Данные массовых платежей в формате CSV

Адрес для запросов

https://api.capitalist.net/

Формат запроса

Запрос к API представляет собой обычный HTTP 1.1 POST запрос, в теле которого передаются необходимые параметры.
Тип содержимого может быть application/x-www-form-urlencoded либо multipart/form-data.

Обязательные параметры запроса

Запрос должен быть отправлен в кодировке UTF-8.
Для сумм в качестве разделителя целой и десятичной частей используется точка «.».

Параметр Описание
login Имя пользователя
operation Имя операции. Например, get_token.

Операции API

На данный момент в API поддерживаются следующие операции:

Операция Описание
Авторизация
get_token Получение атрибутов шифрования.
Проведение платежей
import_batch_advanced Загрузка массового платежа в систему с возможностью выбора способа подтверждения.
process_batch Подтверждение массового платежа.
get_batch_info Получение подробной информации по загруженному массовому платежу.
get_document_fee Подсчет комиссии на основе параметров документа.
get_documents_history Получение истории операций.
documents_search Поиск документов по номеру платежа из вашей системы.
add_payment_notification Отправка получателю уведомления о платеже.
is_verified_account Проверка, верифицирован ли владелец счета.
Работа со счетами
get_accounts Получение списка ваших счетов (кошельков).
create_account Создание вашего счета (кошелька).
get_cashin_requisites Получение реквизитов пополнения счета.
Профиль, регистрация
register_invitee Регистрация нового пользователя.
registration_email_confirm Подтверждение e-mail для нового пользователя — ввод кода подтверждения.
profile_get_verification_code Запрос повторной отправки кода подтверждения на email.
profile_change_email Смена email пользователя.
password_recovery_generate_code Отправка кода подтверждения для смены пароля.
password_recovery Изменение пароля.
Другое
currency_rates Получение обменных курсов.

Формат ответа

По-умолчанию, ответ возвращается в CSV формате (параметры, разделенные точкой с запятой и переносом строк) в кодировке UTF-8.

Выбор формата ответа

На данный момент поддерживается три формата ответа: json, csv и json-lite.

Для получения ответа в более удобном формате, необходимо в запросе передать HTTP заголовок 'x-response-format', например

Заголовок Выбранный формат
x-response-format: json Полноценный JSON с поименованными параметрами
x-response-format: csv CSV, выбирается по-умолчанию
x-response-format: json-lite Структура данных из варианта с CSV, сконвертированная в JSON

В HTTP заголовках ответа возвращается одноименный заголовок ‘x-response-format’, в котором указан реальный формат ответа. Во всех случаях они совпадают.

Обработка ошибок

По-умолчанию (т.е. для формата ответа CSV), первый параметр первой строки ответа всегда является целым числом (далее для удобства будем называть его Кодом ошибки). Если код ошибки равен нулю, значит операция прошла успешно. В противном случае вторым параметром первой строки идет Текст ошибки. Для форматов ответа json и json-lite Код и Текст ошибки передаются в атрибутах code и message.

Коды ошибок

Код Описание
0 Операция прошла успешно
1 Системная ошибка
2 Ошибка выполнения (Необходимо смотреть текст ошибки)
5 Пользователь не найден
10 Ошибка, при попытке расшифровать пароль
15 Передан неверный пароль
16 Превышено количество попыток входа. Повторите через 30 минут
20 Передан неверный токен аутентификации
25 Запрещены запросы информации по пакетным загрузкам с более 1000 записей без постраничной разбивки
110 Ошибка при проверке подписи
111 В данных перевода присутствуют недопустимые символы
112 Превышено ограничение на количество записей в одном массовом платеже
125 Невозможно разобрать переданный файл
130 Не найден счет
131 Нужно передать хотя бы один счет отправителя
132 Передан пустой массовый платеж
135 Недостаточно средств на счете для проведения операций
150 Получен не POST-запрос
151 Неизвестная операция
152 API недоступен пользователю
155 – 160 Ошибки, связанные с регистрацией нового пользователя (операция register_invitee)
155 Пользователь с таким логином уже существует
156 Пользователь с таким адресом электронной почты уже существует
157 Неверный формат логина (логин должен быть длиной от 3 до 16 латинских букв или цифр)
158 Неверный формат адреса электронной почты
159 Неверный формат никнейма (никнейм должкен быть от 3 до 50 латинских букв, цифр, дефисов или знаков подчеркивания)
160 Ошибка в номере телефона (опциональный параметр, должен состоять минимум из 7 цифр, включая международный код страны и населенного пункта)
170 Ошибка создания кошелька
180 Неизвестный способ подтверждения
181 Выбранный способ подтверждения неактивен
182 Отсутствует цифровая подпись
185 Ошибка импорта массового платежа с несколькими записями (см. ошибку 188). Сумма платежа равна нулю. (см. операцию import_batch_advanced)
186 Ошибка импорта массового платежа. Детали необходимо уточнить у Службы поддержки.
187 Ошибка импорта массового платежа по причине временной недоступности одного из типов платежей.
Второй строкой возвращается номер ошибочной записи в батче с нумерацией от нуля.
188 Ошибка импорта массового платежа с одной записью (см. ошибку 185). В качестве текста ошибки возвращается комментарий причины отклонения.
190 – 210 Ошибки на операции get_document_fee
190 Неизвестный тип документа
191 Неизвестный код провайдера услуг
192 Неизвестный тип банковского платежа (Wire)
193 Не указан получатель
194 Счет получателя должен быть вашим
195 Счет для списания должен быть вашим
196 Сумма перевода должна быть больше нуля
197 Не удалось отправить код подтверждения
198 Неверный код подтверждения
200 Счет не существует
202 Переданы неверные данные запроса

Если вы не нашли описание Кода ошибки, пожалуйста, обратитесь в Службу поддержки.

Примеры работы на PHP

Архив доступен для скачивания по адресу

Содержание архива

Код Описание
config.php Конфигурационный файл, подключаемый во всех примерах
директория include Необходимые библиотеки
include/Client.php Основная библиотека подключения
get_accounts.php Пример вызова get_accounts
create_account.php Пример вызова create_account, get_accounts
import_batch_advanced.php Пример вызова import_batch_advanced, get_batch_info, process_batch (MOBILE)
import_batch_advanced_signature.php Пример вызова import_batch_advanced c подписью сертификатом (SIGNATURE).
get_cashin_requisites.php Пример вызова get_cashin_requisites
api_password_recovery.php Пример вызова password_recovery_generate_code, password_recovery
api_registration_confirm.php Пример вызова registration_email_confirm
get_document_fee.php Пример вызова get_document_fee
get_documents_history.php Пример вызова get_documents_history
register_invitee Пример вызова register_invitee
sample-responses.txt Примеры ответов в разных форматах: csv, json-lite, json

API Capitalist v.1.7.15