Покупки через 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.