Инструменты MCP-сервера
18 инструментов MCP-сервера АТОЛ - документация, планы интеграции, валидация чеков и живые вызовы API.
MCP-сервер не только дает доступ к документации: он умеет выдавать готовые планы интеграции, проверять чеки и вызывать живое API АТОЛ. Инструменты делятся на четыре группы.
Документация
list_products
Обзор платформы: продукты, базовые URL, способы аутентификации и список всех страниц документации. Отправная точка для ассистента. Параметров нет.
search_docs
Полнотекстовый поиск по документации: query (обязательный), product -
фильтр pay / online / kkt-info / mcp. Возвращает страницы с
релевантными фрагментами.
get_page
Полный текст страницы в Markdown по slug (например, pay/api/payments).
list_methods
Все методы API трех продуктов: HTTP-метод, путь, описание, страница
документации. Фильтр product.
get_method
Детальное описание метода по path (+ httpMethod). Для АТОЛ Pay Ecom
возвращает операцию из OpenAPI-спецификации вместе только с теми схемами,
на которые она ссылается (рекурсивно), и страницу документации по теме. Для
остальных продуктов - страницу документации.
get_error_codes
Поиск по справочникам ошибок всех продуктов: query - код
(PAYMENT_EXISTS, ExpiredToken, 421) или фрагмент описания. Индексируются
коды из таблиц страниц ошибок портала (АТОЛ Pay, АТОЛ Онлайн, сервис ККТ и ФН).
Возвращает совпадения: код, описание, продукт и страницу, где код описан.
get_openapi
Полная OpenAPI 3.0 спецификация АТОЛ Pay Ecom (JSON) - для генерации клиентов и типов. Параметров нет.
Планы интеграции и рецепты
start_integration
Вызывается первым при задаче «интегрируй АТОЛ Pay»: возвращает пошаговый план под стек, эталонный код и чек-лист самопроверки.
| Параметр | Значения |
|---|---|
stack | node-express, nextjs, python-fastapi, python-django, php-laravel, php, other |
get_recipe
Рецепт по конкретной теме - markdown с кодом и типичными ошибками. Параметр
topic:
topic | Тема |
|---|---|
payment-link | Регистрация платежа и платежная ссылка |
callback-handler | Обработка уведомлений |
receipt | Фискализация в АТОЛ Pay |
two-stage | Холдирование (двухстадийные платежи) |
subscriptions | Подписки и рекуррентные списания |
saved-card | Оплата по сохраненной карте |
refunds | Возвраты и отмены |
payment-methods | Способы оплаты, СБП, банки |
fiscal-direct | Прямая фискализация через АТОЛ Онлайн v5 |
kkt-monitoring | Мониторинг касс и ФН |
test-mode | Тестовая среда |
go-live-checklist | Перевод в бой |
validate_receipt
Проверка JSON чека до отправки. Параметры: receipt_json - чек строкой JSON,
product - pay (блок receipt регистрации платежа, суммы в копейках;
передайте amount для сверки сумм) или online (полное тело запроса АТОЛ
Онлайн v5, суммы в рублях, поддерживаются коррекции). Возвращает valid,
errors, warnings на русском.
Что валидатор не проверяет
buyer.email проверяется только на длину (не длиннее 64 символов) - формат
адреса не проверяется, потому что и OpenAPI-спека объявляет для этого поля
лишь maxLength. Поэтому пустая строка и заведомо некорректный адрес вроде
не-почта проходят валидацию: чек будет признан корректным, а чек покупателю
не уйдет. Проверяйте формат адреса на своей стороне до вызова.
Помните также, что сам блок buyer необязателен - обязательными спека
объявляет только positions, providerId и sno. Чек без buyer
валидатор пропустит намеренно, это не ошибка.
build_payment_request
Конструктор корректного тела POST /v1/ecom/payments + готовые curl-команды
для sandbox и прода (с заголовком Authorization: Bearer …). Ничего не
отправляет; валидирует receipt, предупреждает о лимите длины orderId и
показывает форму ответа.
| Параметр | Описание |
|---|---|
amount | Сумма в копейках (обязательный) |
order_id | Идентификатор заказа (обязательный) |
return_url | URL возврата покупателя (обязательный) |
session_type | oneStep (по умолчанию) / twoStep |
notification_url | URL для callback-уведомлений |
receipt_json | Блок receipt строкой JSON |
buyer_id | ID покупателя для сохранения карты |
Живые вызовы API
Требуют учетных данных в заголовках подключения - см. настройку. По умолчанию работают на sandbox.
create_payment
Регистрирует платеж через живое API и возвращает ответ с data.paymentUrls.main -
откройте эту ссылку в браузере и проведите тестовую оплату. Боевая среда -
только при X-Atol-Pay-Base-Url + X-Atol-Allow-Live: 1. Параметры те же,
что у build_payment_request, плюс payment_methods - массив
{ paymentType, bankId }; он принимает все типы: card, bank_app, sbp, bnpl,
account, а bankId - объединение перечней из OpenAPI-спеки и документации
АТОЛ (включая 200, которого в спеке нет; на него инструмент возвращает
предупреждение).
check_payment_status
Статус платежа по order_id вместе с расшифровкой числового кода по
таблице статусов (0 - в обработке,
1 - успех, 3 - ошибка без повтора, 4/5 - отмена/возврат, 7/8 - частичные,
11 - ожидает списания, 12 - можно повторить, 255 - карта проверена).
get_receipt_dictionaries
Актуальные словари значений чеков (НДС, способы/предметы расчета, единицы, СНО, типы агентов) - ответ метода словарей. Параметров нет.
get_fiscal_report
Результат обработки документа АТОЛ Онлайн v5 по uuid: статус и реквизиты
фискализации (ФД, ФПД, ссылка ОФД, проверка кодов маркировки). Требует
X-Atol-Online-Login / X-Atol-Online-Pass / X-Atol-Online-Group.
get_kkt_info
Состояние арендованных касс: наполненность ФН, сроки замены, неотправленные
документы, ошибки связи с ОФД. Параметры: serial_number - заводской номер
конкретной кассы (без него - список касс группы), limit (по умолчанию 10,
максимум 100) и offset для постраничного списка. Возвращает объект data
из методов сервиса.
Денежные операции (по умолчанию отключены)
Включаются явно - заголовком X-Atol-Allow-Live: 1 в конфигурации
подключения.
cancel_payment
Отмена/возврат платежа. Параметры: order_id; для частичного возврата -
amount в копейках и positions_json (массив { parentItemId, sum, quantity }
строкой JSON, parentItemId - из refund-items). Без них - полный возврат.
Вид операции сервер АТОЛ определяет сам. На ошибку не повторяйте запрос вслепую -
сначала check_payment_status.
deposit_payment
Списание замороженных (захолдированных) средств двухстадийного платежа по
order_id в статусе 11 (не позднее 7 суток, выполняется один раз).