Перейти к содержимому

Инструменты 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»: возвращает пошаговый план под стек, эталонный код и чек-лист самопроверки.

ПараметрЗначения
stacknode-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_urlURL возврата покупателя (обязательный)
session_typeoneStep (по умолчанию) / twoStep
notification_urlURL для callback-уведомлений
receipt_jsonБлок receipt строкой JSON
buyer_idID покупателя для сохранения карты

Живые вызовы 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 суток, выполняется один раз).