Оплаты сайта и чтение финансов через API

Регистрация оплаты, уже принятой внешним сайтом. AXKED учитывает сумму в финансах и балансе ученика, не списывает деньги в банке и не формирует повторный чек. Создание нового платежа у банка этим методом не выполняется.

Порядок подключения

1. Директор создаёт отдельное подключение для сайта и выдаёт права, перечисленные ниже.
2. Сервер сайта получает OAuth-токен по инструкции авторизации.
3. Получите параметры учёта через GET /api/v2/payments/options и выберите счёт для поступлений.
4. Найдите ученика по телефону или email, при нескольких детях дайте выбрать нужного и сохраните его ID.
5. После подтверждения оплаты вашим банком отправьте её в AXKED через POST /api/v2/payments.
6. Сохраните ID операции из ответа; при необходимости проверьте результат по тому же payment_id.

Для заявок и уведомлений об их изменении используется отдельная интеграция заявок с сайта.

Разрешения

• students:search - поиск ID ребёнка;
• payments:read - параметры учёта и проверка платежей этого подключения;
• payments:write - регистрация уже полученной оплаты.

Эти права директор выбирает отдельно в «Настройки → Общие → Доступ к REST API». Ранее выданные подключения автоматически их не получают.

Параметры учёта

GET /api/v2/payments/options
Scope: payments:read

Возвращаются balance_mod, dif_balance, use_finance_type, список scores с ID/названием/валютой и finance_types с ID/названием/score_id. Это параметры своей компании; остатки счетов не передаются.

Регистрация

POST /api/v2/payments
Scope: payments:write
Content-Type: application/json

{
  "payment_id": "SITE-2026-00125",
  "student_id": 12345,
  "score_id": 32,
  "sum": "5000.00",
  "date": "2026-10-22",
  "comment": "Оплата обучения на сайте"
}

Обязательны payment_id - существующий номер платежа сайта, student_id, score_id, положительная sum до двух знаков после точки и дата YYYY-MM-DD не позднее текущей. Передавайте непустой номер строкой, без пробелов по краям; значение 0 не допускается. Необязательны comment (до 2000 символов) и month в принятом в AXKED формате месяца.

Если компания использует типы оплаты, передайте finance_type_id, связанный с выбранным счётом. При раздельном балансе обязателен gos_id из поиска ученика. Для баланса в занятиях или единицах (balance_mod=1/3) требуется положительное count, для почасового баланса (balance_mod=2) - count_h и/или count_min от 0 до 59. Для денежного баланса (balance_mod=0) достаточно суммы.

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

Ответ и повторы

Пример успешного ответа для суммы 5000 без комиссии и общего денежного баланса. Все ID вымышлены.

{
  "data": {
    "id": 90001,
    "payment_id": "SITE-2026-00125",
    "source": "Сайт V2:42",
    "student_id": 12345,
    "score_id": 32,
    "finance_type_id": null,
    "gos_id": null,
    "sum": 5000,
    "date": "2026-10-22",
    "refund_sum": 0
  },
  "replayed": false
}

Первый успешный запрос возвращает HTTP 201, replayed=false и объект data: id финансовой операции, payment_id, source, student_id, score_id, finance_type_id, gos_id, sum, date, refund_sum.

Сайт не задаёт компанию или источник: они определяются по OAuth-подключению. Номер сохраняется в существующее payment_id, источник - Сайт V2:ID подключения. Название подключения, перевыпуск секрета и получение нового токена не меняют источник.

Повтор того же платежа через то же подключение возвращает HTTP 200 и replayed=true, без нового зачисления. Номер с другим учеником, суммой, счётом, типом оплаты, группой или количеством единиц возвращает HTTP 409. При повторе сохраняются первоначальные дата и комментарий. Используйте одно подключение для одного сайта и сохраняйте его при перевыпуске секрета. Новый OAuth-клиент считается новым источником. После удаления финансовой операции её номер больше не защищает от повторного зачисления. Не отправляйте одну оплату одновременно через V2, Тильду и банковский callback.

Если ответ не получен

1. Проверьте платёж запросом GET /api/v2/payments с исходным payment_id через то же подключение.
2. Если операция найдена, используйте возвращённый результат без нового зачисления.
3. Если операция пока не найдена, повторите исходный POST с тем же номером и параметрами. Защита от повторов действует и при одновременной обработке этих запросов.
4. При 409 сравните параметры с уже зарегистрированным платежом. Не заменяйте номер на новый только для обхода конфликта.

Проверка

GET /api/v2/payments?payment_id=SITE-2026-00125
Scope: payments:read

Ответ содержит data той же операции и отражённую в AXKED сумму возвратов refund_sum. Чужое подключение или неизвестный номер получает 404. Это проверка учёта в AXKED, а не запрос состояния в банке.

Возврат

Метод V2 для передачи возврата с сайта пока отсутствует. Параметр sum при регистрации оплаты должен быть положительным: отрицательная оплата не является способом оформить возврат. Фактический возврат денег выполняйте через свой сайт или банк.

Для отражения возврата по денежному балансу откройте исходную операцию в разделе Финансы → Операции, выберите Возврат и режим списания только с баланса. Можно отразить полный или частичный возврат в пределах оставшейся суммы исходной оплаты. Для этих внешних операций запрос возврата в банк и повторный чек из AXKED не выполняются. Сумму отражённых возвратов можно проверить в поле refund_sum ответа GET.

Текущие границы метода

• Принимается одна сумма оплаты; отдельная сумма, перечисленная банком по рассрочке, не передаётся.
• Оплата пополняет баланс по действующим правилам компании; автоматически купить абонемент или зачислить в группу этим методом нельзя.
• Новое подключение к рабочей компании не создаёт тестовый режим. Проверяйте запись на данных отдельной тестовой компании.

Лимит регистрации - 60 запросов в минуту на IP. Проверка данных возвращает 422, отсутствие прав - 403.

Связанные инструкции

Доступ и разрешения · Выбор ученика · Ошибки и ограничения

Чтение всех финансовых операций

Для аналитики директор отдельно выдаёт finance:read. Это право открывает финансовые операции всей компании, включая операции, не созданные сайтом. Прежнее payments:read по-прежнему позволяет проверять только оплаты своего подключения.

GET /api/v2/finances?date_from=2026-10-01&date_to=2026-10-31&per_page=50
GET /api/v2/finances?date_from=2026-10-01&date_to=2026-10-31&student_id=12345&after_id=100

Обязательны date_from и date_to в формате YYYY-MM-DD. Период - до 31 календарного дня включительно. Для длинного периода последовательно запросите несколько интервалов. Дополнительные фильтры: student_id, branch_id, group_id, finance_type_id, type, operation_type.

Поля операции: id, date, sum, type, operation_type, name, comment, student_id, branch_id, group_id, gos_id, score_from, score_for, score_from_name, score_for_name, score_from_currency, score_for_currency, finance_type_id, finance_type_name, month, value_sum, refund_sum, original_finance_id, created_at, updated_at.

type: 0 - расход, 1 - доход, 2 - перевод. operation_type: 0 - прочая операция, 1 - пополнение баланса, 2 - продажа абонемента, 3 - возврат пополнения. sum - сохранённая сумма финансовой операции; её знак и вид не заменяют историю баланса ученика. Списания за занятия и начисления запрашиваются через историю баланса. Не вычитайте возврат повторно, если уже учитываете отдельную возвратную операцию.

Связи с учеником, группой или филиалом могут быть не заполнены. Удалённый счёт или тип оплаты может не иметь названия. Метод не создаёт оплат, возвратов и чеков. Банковские секреты и данные входа в ответ не включаются.

Переход по страницам: after_id и per_page от 1 до 50, ответ data и meta с has_more, next_after_id. Параметр page здесь не используется. Новые выгрузки вместе ограничены 30 запросами в минуту на подключение, 60 на компанию и одной одновременно выполняемой выгрузкой. При ответе 429 соблюдайте Retry-After.