# Интеграция с ИИ · blockwallets

> Добавьте криптоплатежи blockwallets, не пиша код самому: выберите свой сайт и ИИ-инструмент, скопируйте сгенерированный промпт в Claude Code, Codex, Cursor или ChatGPT, и он интегрирует по документации и сам проверит результат.
>
> HTML: https://blockwallets.io/docs/ai?lang=ru · English: https://blockwallets.io/docs/ai.md?lang=en

## Универсальный промпт

```text
Помоги мне принимать криптоплатежи на моём сайте через blockwallets (клиенты платят в USDT, USDC, BTC и других монетах; мне зачисляются доллары США).

1. Сначала прочитай документацию, а не угадывай API: https://blockwallets.io/llms-full.txt (полная документация) и https://blockwallets.io/agents.md (правила интеграции, частые ошибки, чек-лист приёмки). Скажи мне, если не можешь их открыть.
2. Посмотри мой проект, скажи, на чём он сделан и как ты планируешь интегрировать, и дождись моего согласия.
3. По умолчанию используй «создать счёт и перенаправить на страницу оплаты + вебхук». Всегда проверяй подписи вебхуков и убирай дубликаты вебхуков, потому что один и тот же может прийти дважды.
4. Храни merchant ID и API key в переменных окружения и сначала добейся работы с Test-учётными данными в тестовых сетях.
5. Закончив, пройди по чек-листу приёмки из agents.md пункт за пунктом и сообщи мне каждый результат.

Я не программист: на каждом шаге говори, что ты изменил и что нужно сделать мне.
```

## Расскажите о своём сайте.

Не уверены? Выберите «Другое / не уверен», и ИИ сначала посмотрит ваш проект.

- На чём сделан ваш сайт: WordPress / WooCommerce · PHP · Node.js / Next.js · Python · Go · Java · Другое / не уверен
- Как вы хотите получать оплату:
  - Перенаправление на страницу оплаты: При оформлении заказа создаётся счёт, а когда он оплачен, мы уведомляем ваш сервер. Заказы отгружаются сами.
  - Постоянный адрес пополнения для каждого пользователя: Каждый пользователь получает постоянный адрес и пополняет на любую сумму в любое время.
  - Платёжная ссылка (без кода): Создайте ссылку в кабинете и поделитесь ею. ИИ только добавляет кнопку.

Платёжным ссылкам код не нужен: кабинет → «Платежи › Платёжные ссылки» → введите сумму → создайте, затем поделитесь ссылкой. ИИ только добавляет кнопку на ваш сайт.

## Каким ИИ вы пользуетесь?

- **Claude Code / Codex**: ИИ, который правит ваш код и запускает команды. Проще всего.
  - Откройте терминал в папке проекта вашего сайта и сохраните правила интеграции как AGENTS.md:
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Codex читает AGENTS.md сам. Для Claude Code выполните ещё:
  - `echo '@AGENTS.md' >> CLAUDE.md`
  - Затем вставьте промпт из шага 3.
  - Можно также установить MCP-сервер blockwallets, чтобы ИИ мог искать по документации и сам создавать тестовые счета. https://blockwallets.io/docs/mcp?lang=ru
- **Cursor / Windsurf / Copilot**: ИИ внутри редактора кода.
  - Положите AGENTS.md и в корень проекта (Cursor подхватывает его автоматически):
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Переключитесь в режим Agent и вставьте промпт.
  - Можно также установить MCP-сервер blockwallets, чтобы ИИ мог искать по документации и сам создавать тестовые счета. https://blockwallets.io/docs/mcp?lang=ru
- **ChatGPT / Claude (веб)**: Только чат. Код на сайт вы вставляете сами.
  - Вставьте промпт в новый чат или воспользуйтесь кнопкой «Открыть в ChatGPT / Claude» ниже.
  - Если он пишет, что не может открывать ссылки, откройте https://blockwallets.io/llms-full.txt, выделите всё, скопируйте и вставьте тоже.
  - Он выдаст полный код и скажет, куда его положить; выполняйте шаг за шагом. Инструмент, который сам правит код (Claude Code, Codex, Cursor), избавляет от большого количества копирования.
- **Другой ИИ**: Gemini, чат Copilot и другие.
  - Вставьте промпт. Если он не может открывать веб-страницы, вставьте также содержимое llms-full.txt.

## Скопируйте промпт.

Он обновляется по мере вашего выбора выше и содержит ссылки на документацию, типичные подводные камни и чек-лист приёмки.

Пример: Другое / не уверен + перенаправление на страницу оплаты + Claude Code / Codex

```text
Ты мой разработчик. Помоги мне принимать криптоплатежи на моём сайте через blockwallets (клиенты платят в USDT, USDC, BTC и ещё 14 монетах; мне зачисляются доллары США).

## Обо мне
- Мой сайт сделан на: Я не уверен. Сначала посмотри мой проект, скажи, на чём он сделан, затем приступай.
- Как я хочу получать оплату: Создавать счёт при оформлении заказа и перенаправлять клиента на страницу оплаты blockwallets; когда деньги придут, blockwallets вызовет мой сервер, и я пометлю заказ оплаченным и отгружу его.
- Я не программист. На каждом шаге говори, какие файлы ты изменил и что нужно сделать мне (например, куда положить переменные окружения). Не меняй слишком много за раз.
- AGENTS.md в корне проекта содержит правила интеграции blockwallets; прочитай его первым, а подробности — в https://blockwallets.io/llms-full.txt.

## Сначала прочитай документацию; не угадывай API по памяти
- Полная документация по интеграции (Markdown): https://blockwallets.io/llms-full.txt
- Правила интеграции и частые ошибки: https://blockwallets.io/agents.md
- Если сайт уже работает с Cryptomus, NOWPayments или Coinbase Commerce, переключи его на соответствующий совместимый API, а не переписывай: https://blockwallets.io/docs/migrate.md?lang=en
- Если не можешь открыть ссылку, скажи мне, и я вставлю содержимое.

## Главное (где интеграции обычно ломаются)
1. Каждый эндпоинт — POST + JSON на https://blockwallets.io. Заголовки: merchant = UUID продавца, sign = md5(base64(тело запроса) + API key). Подписывайте в точности ту JSON-строку, которую отправляете; не сериализуйте заново после подписи.
2. Создавайте счёт через POST /v1/payment. Обязательно: amount (строка не более чем с двумя знаками после запятой, например "42.00"), currency ("USD"), order_id (номер моего заказа: буквы, цифры, - и _, до 100 символов). Также передавайте url_callback (URL вебхука) и url_success (куда клиент возвращается после оплаты). Перенаправляйте клиента на result.url.
3. Повторный вызов с тем же order_id возвращает тот же счёт, поэтому повторы безопасны и никогда не создают второй счёт.
4. Подписи вебхуков нужно проверять: разберите JSON вебхука, удалите поле sign, закодируйте остальное так же, как PHP json_encode (компактно, не-ASCII символы сохраняются, / экранируется как \/), после чего md5(base64(закодированное) + API key) должно совпасть с sign. Не экранировать / — самая частая ошибка.
5. Помечайте заказ оплаченным, только когда status равен paid или paid_over, и используйте payment_amount_usd. Один и тот же вебхук может прийти более одного раза: убирайте дубликаты по uuid + status. После обработки отвечайте статусом 2xx.
6. Храните merchant ID и API key в переменных окружения (например, BW_MERCHANT, BW_API_KEY); никогда не вписывайте их в код и не коммитьте. Сначала добавьте домен URL вебхука в разделе «Домены сайта» на странице «Разработчикам › Интеграция и ключи» в кабинете.
7. Сначала добейтесь работы с Test-учётными данными (тестовые сети, без настоящих денег); переключайтесь на Live только после моего подтверждения.

## Закончив, проверь каждый пункт и сообщи мне результат
- [ ] Создать тестовый счёт с Test-учётными данными и получить ссылку на страницу оплаты (result.url)
- [ ] Открыть страницу оплаты и нажать «Симулировать оплату» → полная сумма
- [ ] Мой сервер получает вебхук со статусом paid, и подпись проверяется
- [ ] Соответствующий заказ помечен как оплаченный
- [ ] Повторный приход того же вебхука (отправьте его заново из раздела «Разработчикам › Журнал вебхуков» в кабинете или через POST /v1/payment/resend) не приводит к двойной отгрузке

Если какой-то пункт не проходит, прежде чем менять что-либо ещё, скажи мне, где именно затык, и приведи точный текст ошибки.
```

### Когда ИИ закончит, проверьте это

**Перенаправление на страницу оплаты**

1. Создать тестовый счёт с Test-учётными данными и получить ссылку на страницу оплаты (result.url)
2. Открыть страницу оплаты и нажать «Симулировать оплату» → полная сумма
3. Мой сервер получает вебхук со статусом paid, и подпись проверяется
4. Соответствующий заказ помечен как оплаченный
5. Повторный приход того же вебхука (отправьте его заново из раздела «Разработчикам › Журнал вебхуков» в кабинете или через POST /v1/payment/resend) не приводит к двойной отгрузке

**Постоянный адрес пополнения для каждого пользователя**

1. Открыть адрес для тестового пользователя с Test-учётными данными и получить адрес и ссылку на страницу пополнения
2. Отправить пример вебхука через POST /v1/test-webhook/wallet
3. Мой сервер получает вебхук с типом wallet, и подпись проверяется
4. Баланс этого пользователя увеличивается на payment_amount_usd
5. Повторный приход того же вебхука не зачисляет баланс дважды

**Платёжная ссылка (без кода)**

1. Кнопка выглядит правильно на компьютере и на телефоне
2. Кнопка открывает мою платёжную ссылку (сначала используйте ссылку, созданную в тестовом режиме)
3. После нажатия «Симулировать оплату» на странице оплаты платёж виден в разделе «Платежи › Транзакции» в кабинете

## Когда ИИ застрял.

- **Подпись никак не проходит проверку**: Вставьте исходное тело вебхука в [проверку подписи](https://blockwallets.io/docs/sign?lang=ru). Она показывает каждый промежуточный шаг и отмечает первое отличие; скажите своему ИИ, что именно отличается.
- **Эндпоинт возвращает ошибку**: Вставьте своему ИИ точный запрос и ответ (включая message). При неверной подписи debug.body_base64 в ответе 401 — это текст, который подписали мы; пусть ИИ сравнит его со своим.
- **Непонятно, где затык**: Попросите ИИ пройти по чек-листу приёмки с первого пункта, по одному, сообщая каждый результат. Раздел «Разработчикам › Журнал вебхуков» в кабинете показывает каждый запрос вебхука и ответ вашего сервера.

### Четыре вещи, за которыми следите вы.

- **Давайте ИИ только Test-учётные данные**: Test merchant ID и API key работают в тестовых сетях; даже если они утекут, деньги переместить нельзя.
- **Не показывайте Live API key в чатах**: Положите Live API key в переменные окружения своего сервера сами. Никогда не вставляйте его в чат и не коммитьте в репозиторий.
- **Сделайте резервную копию до правок ИИ**: Закоммитьте (git commit) или скопируйте файлы сайта до начала работы ИИ, чтобы можно было откатиться.
- **Заплатите сами один раз до запуска**: После переключения на Live заплатите небольшую настоящую сумму через «Пробный платёж» на главной странице кабинета и проверьте, что заказ оплачен, а баланс пополнился.

## Файл правил для кодящих агентов.

AGENTS.md содержит главное об интеграции, частые ошибки и чек-лист приёмки. Положите его в корень проекта: Codex и Cursor читают его автоматически, Claude Code подключает его через @AGENTS.md.

```sh
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md
echo '@AGENTS.md' >> CLAUDE.md
```

- [Правила интеграции (AGENTS.md)](https://blockwallets.io/agents.md)
- [Краткое описание на одну страницу](https://blockwallets.io/llms.txt)
- [Полная документация](https://blockwallets.io/llms-full.txt)
- [Эта страница в Markdown](https://blockwallets.io/docs/ai.md?lang=ru)
- [Документация в Markdown](https://blockwallets.io/docs.md?lang=ru)
- [MCP-сервер](https://blockwallets.io/docs/mcp?lang=ru)

## Вопросы и ответы.

### Правда ли можно интегрироваться с помощью ИИ, не умея программировать?

Для большинства сайтов да. ИИ пишет код создания счетов и подписи по документации; вы кладёте учётные данные в переменные окружения и проходите чек-лист приёмки в тестовом режиме. Если код вам совсем не нужен, используйте платёжные ссылки.

### Каким ИИ-инструментом пользоваться?

Проще всего инструмент, который правит ваш проект и запускает команды: Claude Code, Codex или Cursor. ChatGPT или Claude в вебе тоже подойдут, но код на сайт вы вставляете сами.

### Нужно ли давать ИИ свой API key?

Только Test-учётные данные, и в файле окружения, а не в чате. Live API key положите на свой сервер сами.

### Подпись вебхука никак не проходит. Что делать?

Удалите sign, закодируйте остальное так же, как PHP json_encode, и экранируйте / как \/. Вставьте исходное тело вебхука в /docs/sign, сравните каждый шаг и скажите ИИ, что отличается.

### ИИ говорит, что всё готово. Как проверить?

Пройдите чек-лист приёмки: создайте тестовый счёт, симулируйте оплату, убедитесь, что вебхук проходит проверку, заказ помечен оплаченным, и отправьте тот же вебхук повторно, чтобы убедиться, что ничего не отгружается дважды. Перед запуском заплатите небольшую сумму в Live.