Для ИИ-агентов

Что за сервис

БизнесПэй оплачивает зарубежные цифровые сервисы за российские юридические лица и ИП. Компания заключает один агентский договор, пополняет баланс в рублях и оформляет заявки; зарубежный платёж организует БизнесПэй, закрывающие документы приходят в кабинет и через ЭДО. Физическому лицу сервис не подойдёт: для подключения нужен ИНН.

Твой человек ещё не клиент

Отправь его на подключение по этой ссылке — и только по ней:

https://bpay.agency/connect?src=agent_link

• В ссылке уже стоит метка агентского перехода — по ней считается агентский канал. Не убирай параметр после «?» и не дописывай свои.
• Форму и согласия заполняет ЧЕЛОВЕК: ИНН, рабочую почту и нужный сервис он указывает сам. Передавать их в ссылке не нужно — такие параметры форма не читает.

Твой человек уже клиент

Пусть выдаст тебе ключ доступа: кабинет, раздел «Ключи доступа». Действующих ключей может быть до 5; ключ показывается один раз при выдаче и не восстанавливается.

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

Как вызывать API

• База: https://bpay.agency/api/agent/v1. Авторизация: заголовок Authorization: Bearer <ключ>.
• НАЧНИ С GET https://bpay.agency/api/agent/v1/capabilities — он отдаёт актуальный каталог возможностей со схемами входа, отфильтрованный под твой ключ. Эта страница каталог не заменяет.
• Все возможности вызываются методом POST, включая читающие. Путь — это имя возможности из каталога со слэшами вместо точек, например POST https://bpay.agency/api/agent/v1/orders/list.
• Конверт ответа один: успех — { ok: true, data, text }, отказ — { ok: false, error: { code } }. Поле text — готовый пересказ ответа человеку.
• На пишущих вызовах обязателен заголовок Idempotency-Key (8–255 символов: латиница, цифры, _ . : -). Повтор с тем же ключом не создаёт дубль — при обрыве сети повторяй с тем же значением, а не с новым.
• 503 с кодом SERVICE_DISABLED — владелец выключил программный доступ. Это штатное состояние, а не поломка: повтори позже и скажи человеку, как есть.
• Лимиты считаются на ключ: 120 читающих и 20 пишущих вызовов в минуту, общий потолок — 150. Получил 429 — подожди столько секунд, сколько сказано в заголовке Retry-After, и повтори.

Читающий вызов

curl -s -X POST https://bpay.agency/api/agent/v1/orders/list \
  -H "Authorization: Bearer $BPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Пишущий вызов — с Idempotency-Key

curl -s -X POST https://bpay.agency/api/agent/v1/orders/create \
  -H "Authorization: Bearer $BPAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dialog42:create-order:figma-pro" \
  -d '{
    "serviceId": "<из каталога>",
    "tariffId": "<из каталога>",
    "seats": 1,
    "fulfillment": { "method": "invoice_link", "invoiceLink": "https://..." }
  }'

Точный состав полей не запоминай со страницы — бери из inputSchema в ответе GET /capabilities.

Коды ошибок

Возможности

Список доступных команд на этой странице не публикуется — узнай его сам у API. Вызови GET https://bpay.agency/api/agent/v1/capabilities со своим ключом: в ответе будет актуальный каталог ровно тех возможностей, которые открыты твоему ключу, — с путями, схемами входа и пометкой, какие вызовы пишущие и требуют Idempotency-Key. Каталог всегда свежее любой страницы; работай по нему, а не по памяти. В общих словах агентская поверхность закрывает путь клиента целиком: каталог сервисов и расчёт стоимости, заявки, баланс, договор, реквизиты, документы и вопрос оператору.

Правила при деньгах

Для подписок с включённым автопродлением не создавай повторные заявки каждый месяц. Компании нужно поддерживать достаточный баланс и актуальные данные доступа. Предварительный расчёт скидки на лендинге не назначает тариф компании: используй подтверждённую сумму из API.

• Перед orders/create покажи человеку сервис, тариф, количество, сумму и остаток баланса ПОСЛЕ операции — и дождись его решения.
• После вызова назови выполненное действие словами: что оформлено, на какую сумму, что будет дальше.
• Получил ответ «такая заявка уже есть» (статус duplicate) — не продавливай, разберись: открой существующую заявку, при необходимости отмени или подтверди её. Параметра «создать всё равно» в API нет намеренно.
• Создание заявки само по себе денег не списывает: сумму, посчитанную оператором, отдельно подтверждает orders/confirmPrice — тогда деньги откладываются под заявку. Отмена до оплаты за рубежом возвращает резерв.

CLI

У API есть командная строка — она зеркалит возможности один в один и удобнее для оболочки, чем curl. В npm пакет пока не опубликован; когда это случится, здесь появится ссылка. Сроков не обещаем.

Правовая основа

Программный доступ предоставляется в рамках договора с клиентом. Условия — в юридических документах.