Покупки через API — оплата с баланса и ссылка на доплату

Скрипт или ИИ-агент может покупать по ключу API, но платит только с баланса организации. Если на балансе не хватает денег, API не отказывает, а возвращает ссылку для человека: он доплачивает ровно недостачу картой или счётом на IBAN, и заказ сразу уходит в работу. Агент сам узнаёт об оплате и продолжает.

Сейчас так можно заказать SSL-сертификат (право ssl.order) продлить домен (право domain.renew) и зарегистрировать новый (право domain.register), см. ключи API. То же агент может делать через MCP с ключом.

Как это работает

1. Агент заказывает сертификат: POST /v1/ssl/certificates с полем "if_short": "pay_link".
2. Если на балансе хватает денег, сумма списывается сразу. Ответ — 201, сертификат уходит на проверку домена.
3. Если денег не хватает, ничего не списывается и не резервируется. Ответ — 402 с кодом payment_required и ссылкой payment_url.
4. Агент передаёт ссылку человеку: в чат, письмом, сообщением.
5. Человек открывает ссылку без входа в кабинет, видит состав заказа и сумму к оплате и платит картой или счётом на IBAN.
6. Деньги зачисляются на баланс, и с баланса сразу оплачивается заказ.
7. Агент видит, что заказ оплачен (через GET /v1/orders/{id} или вебхук), и работает дальше: ждёт выпуска, забирает файлы сертификата.

Без if_short API ведёт себя как раньше: при нехватке отвечает 402 balance_short и заказ не создаёт.

Заказ со ссылкой на доплату

curl -X POST https://api.zrazu.com/v1/ssl/certificates \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: 0b7c6e1a-3f42-4d8e-9a51-2c6f0e9d7b10" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "…", "mode": "vat", "domain": "example.com.ua",
       "csr": "-----BEGIN CERTIFICATE REQUEST-----…", "dcv_method": "dns",
       "if_short": "pay_link"}'

Ответ, когда денег не хватает:

{
  "error": { "code": "payment_required", "message": { "uk": "…", "en": "…" } },
  "amount_due": 22500,
  "payment_url": "https://vse.zrazu.com/pay-link/…/",
  "expires_at": "2026-11-16T12:00:00Z",
  "order": { "id": "…", "number": "202611-48271", "status": "awaiting_payment", "amount_due": 22500, "items": [ … ] },
  "certificate": { "id": "…", "status": "unpaid", … }
}

Суммы — в копейках. amount_due — это заказ минус живые деньги на балансе; бонусы сюда не входят.

Ссылка на доплату

• Ссылка действует 72 часа. Страница показывает состав заказа, сумму к оплате и продавца. Данных вашей организации на ней нет.
• Картой: к сумме добавляется комиссия банка, кнопка показывает полную сумму. Счётом на IBAN: счёт выписывается на недостачу, номер счёта совпадает с номером заказа.
• Сумма пересчитывается каждый раз, когда страницу открывают. Если баланс тем временем пополнили, доплатить нужно меньше.
• Если ссылку потеряли или срок истёк, новую выдаёт POST /v1/orders/{id}/payment-link. Прежняя ссылка этого заказа после этого перестаёт действовать. Пока человек платит картой, новая ссылка не выдаётся: ответ — 409 payment_in_progress.
• Если баланс пополнили другим способом (в кабинете, переводом), агент сам оплачивает заказ: POST /v1/orders/{id}/pay. Если денег снова не хватает, ответ — 402. Пока прежняя ссылка действует, новой нет (payment_url — null): человек платит по той же.
• Оплачивать и выдавать ссылки ключ может только для заказов, которые сделал сам. Заказа из кабинета или другого ключа для него не существует (404).

Ссылка — это право доплатить именно этот заказ. Передавайте её тем, кому доверяете: по сумме к оплате видно, сколько примерно лежит на балансе.

Как агент узнаёт, что оплата пришла

Опрос — основной способ для ИИ-агентов. Ассистенты в чате не принимают входящих запросов, поэтому спрашивают сами:

curl -H "Authorization: Bearer zr_live_..." "https://api.zrazu.com/v1/orders/{id}?wait=60"

С wait (до 60 секунд) ответ приходит, как только заказ изменился, или через wait секунд, если ничего не произошло. Повторяйте запрос в цикле. Одновременно ждать можно до 3 запросов на ключ и до 10 на организацию; сверх этого — 429 too_many_waits, тогда спрашивайте без wait.

Читать заказ может ключ с правом ssl.read, ssl.order или billing.read.

Вебхук — для серверных интеграций. Если в организации настроен вебхук, ZRAZU отправляет события order.paid, order.fulfilled и order.cancelled по заказам, для которых выдавали ссылку. В теле запроса, в поле data, — event_id и заказ в том же виде, что в GET /v1/orders/{id}. Запрос подписан так же, как другие вебхуки (X-Zrazu-Signature). Если ваш сервер не ответил, ZRAZU повторяет событие с паузой, которая растёт до часа. Поэтому событие может прийти дважды: отличайте повторы по event_id. События не отправляются, если у вебхука выключена категория «Деньги».

Продление домена

Ключу нужно право domain.renew. Продление оформляется отдельным заказом и в корзину кабинета не попадает.

curl -X POST https://api.zrazu.com/v1/domains/example.com.ua/renew \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"years": 1, "expires_at": "2027-03-14", "if_short": "pay_link"}'

• years — от 1 до 10. Срок домена после продления не может уходить дальше чем на 9 лет от сегодняшнего дня.
• expires_at — обязателен: текущая дата окончания из GET /v1/domains. Если у нас она уже другая, домен продлили раньше, и API отвечает 409 expiry_mismatch: дважды вы не заплатите. Поле необязательное, но советуем его передавать.
• mode — vat или no_vat. Нужен, только если домен ещё не оплачивали у нас (например, его только что перенесли). Иначе продлевает тот же продавец, что и в прошлый раз.
• Если денег хватает, ответ — 201, заказ в статусе paid. Новый срок появится в GET /v1/domains, как только реестр подтвердит продление; fulfilled в заказе станет true.
• Если денег не хватает, всё как для SSL: без if_short — 402 balance_short и заказа нет; с "if_short": "pay_link" — 402 со ссылкой.

Регистрация домена

Ключу нужно право domain.register. Регистрация оформляется отдельным заказом и в корзину кабинета не попадает.

1. Возьмите владельца домена из списка GET /v1/contacts/owners: id, вид (person или org), имя, complete (есть ли полный почтовый адрес) и authority (подтверждены ли в кабинете полномочия в отношении этого лица). Почты и телефона там нет. Нового владельца ключ не создаёт: запись добавляет человек в кабинете, в «Контактах». Владельца потом ключом не сменить, поэтому выбирайте внимательно.
2. Отправьте запрос без documents_hash. Если реестр требует согласия с документами, API отвечает 409 documents_required: в ответе documents (название, редакция, ссылка) и documents_hash.
3. Прочитайте документы и повторите запрос с этим documents_hash. Повтор с отпечатком — согласие вашей организации с документами реестра в показанных редакциях. Если владелец домена — другое лицо, вы соглашаетесь от его имени и гарантируете, что у вас есть на это полномочия и что он ознакомлен с этими документами. Если документы изменились, вы снова получите documents_required с новым отпечатком.

curl -X POST https://api.zrazu.com/v1/domains/example.com.ua/register \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"years": 1, "owner": "ID_ЗАПИСИ", "mode": "no_vat", "documents_hash": "ОТПЕЧАТОК_ИЗ_ОТВЕТА", "if_short": "pay_link"}'

• years — от 1 до 10.
• owner — обязательный: id записи из GET /v1/contacts/owners.
• mode — обязательный: vat или no_vat.
• Пока не отправлен правильный documents_hash, заказ не создаётся и деньги не списываются.
• Если денег хватает, ответ — 201, заказ в статусе paid. Домен появится в GET /v1/domains, как только реестр его зарегистрирует; fulfilled в заказе станет true.
• Если денег не хватает, всё как для SSL. Человек на странице доплаты видит те же документы и соглашается с ними сам.

Ограничения

• Дневной лимит трат ключа учитывает и заказы, ждущие оплаты.
• Перед оплатой заказ проходит ту же проверку безопасности, что и оплата в кабинете. Если её нужно проверить вручную, статус будет review.
• Оплата POST /v1/orders/{id}/pay заказа регистрации снова проверяет владельца и документы. Если запись владельца убрали из справочника или документы реестра изменились, оплату не примут: оформите заказ заново.
• Неоплаченный заказ остаётся в кабинете в разделе «Заказы». Его можно оплатить там или отменить.

Если не получилось

• `409 documents_required`. Прочитайте documents или покажите их человеку и повторите запрос с documents_hash из этого ответа: повтор означает согласие.
• `422 owner_required`, `owner_not_found`. Передайте owner — id из GET /v1/contacts/owners.
• `422 owner_unconfirmed`. Для записи не подтверждены полномочия: откройте её в «Контактах», отметьте галочку и сохраните.
• `422 owner_incomplete`. У владельца неполный почтовый адрес: дополните его в кабинете или выберите другую запись.
• `409 name_taken`. Имя уже зарегистрировано.
• `409 register_unavailable`. Реестр сейчас не отвечает или регистрация в зоне приостановлена. Попробуйте позже.
• `429 rate_limited`. Ключ, организация или адрес исчерпали долю проверок имён в реестре. Повторите через минуту.
• `409 expiry_mismatch`. Домен уже продлили: проверьте срок в GET /v1/domains.
• `422 mode_required`. Домен ещё не оплачивали у нас: передайте "mode": "vat" или "no_vat".
• `409 order_refused`. Продление не приняли: домен уже продлевается, продление остановлено или срок ушёл бы за 9 лет. Причина — в message.uk.
• `409 renew_unavailable`. Домен сейчас не продлить: он заблокирован, процедура в реестре ещё не завершилась или реестр не отвечает. Попробуйте позже.
• `402 balance_short`. Запрос без "if_short": "pay_link": добавьте поле, чтобы получить ссылку.
• `409 not_awaiting_payment`. Заказ уже оплачен или отменён. Проверьте GET /v1/orders/{id}.
• `409 balance_enough`. На балансе уже хватает денег. Оплатите заказ: POST /v1/orders/{id}/pay.
• `409 payment_in_progress`. Человек как раз платит картой. Дождитесь результата через GET /v1/orders/{id}?wait=60.
• Страница пишет, что ссылка недействительна. Адрес скопировали не полностью. Попросите агента прислать ссылку ещё раз.
• Страница пишет, что ссылка просрочена. Срок истёк или для заказа выдали новую ссылку. Попросите агента прислать последнюю или выдать новую: POST /v1/orders/{id}/payment-link.