piv.day Документація API — номери, домени, проксі, вайти

Документація

Початок роботи

REST API на тарифі Business. Bearer-токени, JSON, ідемпотентні ендпойнти, передбачувані коди помилок. Документація нижче описує кожен ендпойнт з прикладом запиту та відповіді.

Base URL

https://app.piv.day/api/v1

Всі ендпойнти розміщені під цим префіксом. Одне середовище — окремих staging-хостів немає.

Автентифікація

Authorization: Bearer YOUR_API_KEY

Ключі створюються в дашборді в розділі Налаштування → API Keys. Кожен ключ має гранульовані дозволи (читання номерів, відправлення SMS, купівля проксі тощо). Скомпрометований токен ротується одним кліком без повторного онбордингу команди.

Акаунт

GET/api/v1/account

curl https://app.piv.day/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Один службовий ендпойнт — баланс і email поточного акаунту. Зручно перевірити, що ключ робочий і автентифікація налаштована правильно.

{
  "success": true,
  "data": {
    "user_id": "usr-uuid-...",
    "balance": 150.50,
    "email": "u***@example.com",
    "team_id": null,
    "is_team_member": false
  }
}

GET /api/v1/account

Формат відповіді

{
  "success": true,
  "data": { ... }
}

Всі відповіді — JSON. При помилці success = false, а тіло містить error.code і error.message.

Rate limits

100 запитів на хвилину на кожен API-ключ. Ліміт спільний для всіх ендпойнтів. Якщо досягли ліміту — пишіть у Telegram-підтримку, збільшимо під навантаження без тривалих погоджень. При перевищенні приходить `429 RATE_LIMITED` і заголовок `Retry-After` — скільки секунд чекати до наступного запиту.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded, retry in 12s"
  }
}

429 Too Many Requests

Документація

Номери

Купівля, продовження, відновлення номерів. Приймання та надсилання SMS. Запуск Google QR-верифікації. Підписка на події через вебхуки.

Список країн і цін

GET/api/v1/numbers/countries

Повертає країни, доступні для купівлі, з актуальною ціною та напрямками SMS. Усі ціни є підсумковими з урахуванням знижки вашої підписки.

Поля відповіді

Поле	Тип	Опис
`country_code`	string	Двобуквений ISO-код країни (наприклад `SE`).
`price_per_month`	number	Підсумкова ціна для вашого тарифу — те, що реально списується при купівлі. Якщо у вас Premium або Business, знижка вже включена.
`base_price`	number	Ціна без знижок (тариф Free). Повертається для порівняння — щоб бачити, скільки заощаджує підписка.
`can_send_sms`	boolean	Чи можна з цього номера надсилати вихідні SMS.
`can_receive_sms`	boolean	Чи можна приймати вхідні SMS.
`sms_send_price`	number\|null	Ціна за вихідне SMS — також з урахуванням тарифу. `null`, якщо відправка з цієї країни недоступна.

GET/api/v1/numbers/countries

curl https://app.piv.day/api/v1/numbers/countries \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": [
    {
      "country_code": "SE",
      "price_per_month": 4.00,
      "base_price": 5.00,
      "can_send_sms": true,
      "can_receive_sms": true,
      "sms_send_price": 0.25
    },
    {
      "country_code": "GB",
      "price_per_month": 3.00,
      "base_price": 3.00,
      "can_send_sms": true,
      "can_receive_sms": true,
      "sms_send_price": 0.20
    }
  ]
}

Список номерів акаунту

GET/api/v1/numbers

Повертає сторінку номерів акаунту з фільтрами за країною, статусом і пошуком по номеру або кастомному імені.

Query-параметри

Поле	Тип	Опис
`limit`	integer	Кількість записів на сторінці (за замовчуванням 50, максимум 200).
`offset`	integer	Зміщення для пагінації.
`country`	string	ISO-код країни для фільтра.
`status`	string	Один із `active`, `expired`, `pending_restore`.
`search`	string	Підрядок для пошуку по номеру або кастомному імені.

GET/api/v1/numbers

curl "https://app.piv.day/api/v1/numbers?country=SE&status=active&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "numbers": [
      {
        "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
        "phone_number": "+46764794425",
        "country_code": "SE",
        "status": "active",
        "created_at": "2026-05-01T10:00:00Z",
        "expires_at": "2026-05-31T10:00:00Z",
        "auto_renew": false,
        "custom_name": "Office line",
        "purchased_at": "2026-05-01T10:00:00Z",
        "next_renewal_date": "2026-05-31T10:00:00Z",
        "tags": ["support"],
        "can_send_sms": true,
        "can_receive_sms": true
      }
    ],
    "pagination": { "total": 1, "limit": 10, "offset": 0 }
  }
}

Один номер за ID

GET/api/v1/numbers/{piv_num_id}

Повна картка номера: статус, дати, авто-продовження, теги, дозволені SMS-напрямки.

Помилки

Код	HTTP	Коли спрацьовує
`NUMBER_NOT_FOUND`	404	Номер не знайдено або він не належить акаунту.

GET/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o

curl https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "phone_number": "+46764794425",
    "country_code": "SE",
    "status": "active",
    "created_at": "2026-05-01T10:00:00Z",
    "expires_at": "2026-05-31T10:00:00Z",
    "auto_renew": false,
    "custom_name": "Office line",
    "purchased_at": "2026-05-01T10:00:00Z",
    "next_renewal_date": "2026-05-31T10:00:00Z",
    "tags": ["support"],
    "can_send_sms": true,
    "can_receive_sms": true
  }
}

Купівля номера

POST/api/v1/numbers/purchase

Купує один номер обраної країни на вказаний термін. Сума списується з балансу акаунту. Повертає piv_num_id, який далі використовується у всіх операціях з номером.

Тіло запиту

Поле	Тип	Опис
`country_code`*	string	ISO-код країни.
`duration_months`*	integer	Термін оренди в місяцях (мінімум 1).
`auto_renew`*	boolean	Увімкнути авто-продовження одразу після купівлі.
`custom_name`	string	Необов'язкове людинозрозуміле ім'я для номера.

Помилки

Код	HTTP	Коли спрацьовує
`COUNTRY_NOT_AVAILABLE`	400	Країна недоступна або для неї немає цін.
`NO_NUMBERS_AVAILABLE`	400	У вказаній країні зараз немає вільних номерів.
`INSUFFICIENT_BALANCE`	402	На балансі недостатньо коштів для купівлі.
`VALIDATION_ERROR`	400	Невалідні поля в тілі запиту.

POST/api/v1/numbers/purchase

curl -X POST https://app.piv.day/api/v1/numbers/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "SE",
    "duration_months": 1,
    "auto_renew": false,
    "custom_name": "My Sweden Number"
  }'

200OK

{
  "success": true,
  "cost": 5.00,
  "numbers": [
    {
      "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
      "country_code": "SE",
      "phone_number": "+46764794425",
      "created_at": "2026-05-01T10:00:00Z",
      "expires_at": "2026-05-31T10:00:00Z",
      "auto_renew": false,
      "custom_name": "My Sweden Number"
    }
  ]
}

Продовжити номер

POST/api/v1/numbers/{piv_num_id}/renew

Продовження активного номера на вказаний термін. Вартість списується з балансу в момент виклику.

Тіло запиту

Поле	Тип	Опис
`duration_months`*	integer	На скільки місяців продовжити.

Помилки

Код	HTTP	Коли спрацьовує
`NUMBER_NOT_FOUND`	404	Номер не знайдено або він не належить акаунту.
`COUNTRY_NOT_AVAILABLE`	400	Для країни номера не знайдено цін.
`INSUFFICIENT_BALANCE`	402	Недостатньо коштів для продовження.

POST/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/renew

curl -X POST https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "duration_months": 1 }'

200OK

{
  "success": true,
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "phone_number": "+46764794425",
    "old_expires_at": "2026-05-31T10:00:00Z",
    "new_expires_at": "2026-06-30T10:00:00Z",
    "cost": 5.00
  }
}

Оновити номер

PATCH/api/v1/numbers/{piv_num_id}

Наразі редагується лише кастомне ім'я номера.

Тіло запиту

Поле	Тип	Опис
`custom_name`*	string	Нове ім'я номера.

Помилки

Код	HTTP	Коли спрацьовує
`NUMBER_NOT_FOUND`	404	Номер не знайдено або він не належить акаунту.
`VALIDATION_ERROR`	400	Невалідне значення в тілі запиту.

PATCH/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o

curl -X PATCH https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_name": "Support line" }'

200OK

{
  "success": true,
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "phone_number": "+46764794425",
    "country_code": "SE",
    "status": "active",
    "custom_name": "Support line",
    "auto_renew": false,
    "expires_at": "2026-05-31T10:00:00Z",
    "tags": []
  }
}

Керування авто-продовженням

PATCH/api/v1/numbers/{piv_num_id}/auto-renewal

Вмикає або вимикає авто-продовження номера. Коли увімкнено — продовження списується з балансу автоматично за 24 години до закінчення. Якщо коштів не вистачить, номер закінчиться; повернути його можна через POST /numbers/restore протягом 7 днів.

Тіло запиту

Поле	Тип	Опис
`auto_renew`*	boolean	Нове значення прапора авто-продовження.

PATCH/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/auto-renewal

curl -X PATCH https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/auto-renewal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auto_renew": true }'

200OK

{
  "success": true,
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "phone_number": "+46764794425",
    "auto_renew": true
  }
}

Відновити прострочені номери

POST/api/v1/numbers/restore

Повертає прострочені номери протягом 7-денного вікна. Передайте масив piv_num_id — номери повернуться зі збереженням SMS-історії та налаштувань. Вартість відновлення вища, ніж купівля нового номера (включено множник відновлення) — точні цифри видно в дашборді перед підтвердженням. Фінальний статус по кожному номеру прийде на вебхук number.restore_completed; за невдалі — гроші автоматично повертаються на баланс.

Тіло запиту

Поле	Тип	Опис
`piv_num_ids`*	string[]	Масив ID номерів для відновлення.

Помилки

Код	HTTP	Коли спрацьовує
`NO_RESTORABLE_NUMBERS`	404	Жоден із переданих номерів не можна відновити (минув 7-денний термін або номер не ваш).
`INSUFFICIENT_BALANCE`	402	Недостатньо коштів для оплати відновлення.

POST/api/v1/numbers/restore

curl -X POST https://app.piv.day/api/v1/numbers/restore \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "piv_num_ids": [
      "vzPA1-kHKSg-EAL7e-Jqd3o",
      "abc12-defgh-ijklm-nopqr"
    ]
  }'

200OK

{
  "success": true,
  "queued": 2,
  "skipped": 0,
  "total_charged": 9.00,
  "numbers": [
    {
      "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
      "phone_number": "+46764794425",
      "status": "pending"
    }
  ]
}

Історія SMS по номеру

GET/api/v1/numbers/{piv_num_id}/sms

Повертає вхідні та вихідні повідомлення по номеру в зворотному хронологічному порядку.

Query-параметри

Поле	Тип	Опис
`limit`	integer	Скільки повідомлень повернути (за замовчуванням 50, максимум 200).
`offset`	integer	Зміщення для пагінації.

GET/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms

curl "https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "42",
        "from_number": "+46764794425",
        "to_number": "+14155551234",
        "message_body": "Hello from piv.day",
        "direction": "outbound",
        "status": "delivered",
        "received_at": "2026-05-22T11:30:00Z"
      },
      {
        "id": "41",
        "from_number": "+14155551234",
        "to_number": "+46764794425",
        "message_body": "Hey, got your message!",
        "direction": "inbound",
        "status": "received",
        "received_at": "2026-05-22T11:35:00Z"
      }
    ],
    "pagination": { "total": 2, "limit": 20, "offset": 0 }
  }
}

Надіслати SMS

POST/api/v1/numbers/{piv_num_id}/sms/send

Доступно для країн, де дозволена вихідна відправка (наприклад CA, GB, SE). Вартість повідомлення списується з балансу в момент відправки.

Тіло запиту

Поле	Тип	Опис
`to_number`*	string	Номер отримувача в міжнародному форматі (E.164).
`message_body`*	string	Текст повідомлення. Підтримуються GSM-7 і UCS-2.

Помилки

Код	HTTP	Коли спрацьовує
`NUMBER_NOT_FOUND`	404	Номер не знайдено або він не належить акаунту.
`NUMBER_EXPIRED`	403	Номер вже закінчився.
`NUMBER_NOT_ACTIVE`	400	Номер зараз у стані, що не дозволяє відправку.
`INSUFFICIENT_BALANCE`	402	Недостатньо коштів для відправки.
`INVALID_MESSAGE_FORMAT`	400	Тіло повідомлення перевищує допустиму довжину або містить заборонені символи.

POST/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms/send

curl -X POST https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+14155551234",
    "message_body": "Hello from piv.day"
  }'

200OK

{
  "success": true,
  "data": {
    "message_id": "42",
    "from_number": "+46764794425",
    "to_number": "+14155551234",
    "message_body": "Hello from piv.day",
    "status": "queued",
    "created_at": "2026-05-22T11:30:00Z"
  }
}

Запуск Google QR-верифікації

POST/api/v1/numbers/{piv_num_id}/verify

Запускає Google QR-верифікацію за наданим URL. Результат — успіх або помилка — прийде на вебхук verify.completed або verify.failed. Вартість списується з балансу в момент запуску.

Тіло запиту

Поле	Тип	Опис
`gv_url`*	string	Повний URL Google-верифікації (береться зі сторінки Google).

Помилки

Код	HTTP	Коли спрацьовує
`NUMBER_NOT_FOUND`	404	Номер не знайдено або він не ваш.
`NUMBER_NOT_ACTIVE`	400	Номер не в активному статусі.
`SMS_DISABLED`	400	Відправка SMS вимкнена для цього номера.
`INSUFFICIENT_BALANCE`	402	Недостатньо коштів для верифікації.
`PROXY_DEAD`	502	Проксі недоступний — баланс повернено.
`QUEUE_FULL`	503	Сервер зайнятий, спробуйте пізніше — баланс повернено.
`SERVER_UNAVAILABLE`	503	Сервер автоматизації недоступний — баланс повернено.

POST/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/verify

curl -X POST https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "gv_url": "https://gv.google.com/..." }'

202Accepted

{
  "success": true,
  "message": "Verification initiated"
}

Документація

Проксі

Резидентський IPv6 у десятках країн. Масова купівля, продовження, Restore з тим самим логіном і паролем, експорт у потрібному форматі.

Список серверів

GET/api/v1/proxy/servers

Список доступних проксі-серверів з цінами.

GET/api/v1/proxy/servers

curl https://app.piv.day/api/v1/proxy/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "EU-DE-01",
        "country": "DE",
        "socks5_port": 1080,
        "http_port": 3128,
        "price_per_proxy": 0.50
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "EU-NL-01",
        "country": "NL",
        "socks5_port": 1080,
        "http_port": 3128,
        "price_per_proxy": 0.45
      }
    ]
  }
}

Список замовлень

GET/api/v1/proxy/orders

Список ваших замовлень проксі з можливістю фільтрації за статусом або пошуковим запитом.

Query-параметри

Поле	Тип	Опис
`limit`	integer	Кількість записів. За замовчуванням: 100, максимум: 500.
`offset`	integer	Зміщення для пагінації.
`status`	string	Фільтр за статусом: `active`, `expired`.
`search`	string	Пошук за замовленням.

GET/api/v1/proxy/orders

curl "https://app.piv.day/api/v1/proxy/orders?status=active&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "ord-uuid-...",
        "country": "DE",
        "quantity": 10,
        "price_per_proxy": 0.50,
        "price_total": 5.00,
        "status": "active",
        "purchased_at": "2026-01-01T00:00:00Z",
        "expires_at": "2026-02-01T00:00:00Z"
      }
    ],
    "pagination": { "total": 1, "limit": 20, "offset": 0 }
  }
}

Один замовлення

GET/api/v1/proxy/orders/{id}

Отримати деталі конкретного замовлення, включно зі списком проксі-облікових даних.

GET/api/v1/proxy/orders/ord-uuid-...

curl https://app.piv.day/api/v1/proxy/orders/ord-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "order": {
      "id": "ord-uuid-...",
      "country": "DE",
      "quantity": 10,
      "price_per_proxy": 0.50,
      "price_total": 5.00,
      "status": "active",
      "purchased_at": "2026-01-01T00:00:00Z",
      "expires_at": "2026-02-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "items": [
        {
          "login": "user1",
          "password": "pass1",
          "host": "185.1.2.3",
          "socks5_port": 1080,
          "http_port": 3128,
          "ipv6": "2a00:1:2:3::1"
        }
      ]
    }
  }
}

Купити проксі

POST/api/v1/proxy/purchase

Купити проксі на обраному сервері. Один запит створює одне замовлення з N проксі (до 500). Bulk-замовлень немає — за потреби викликайте метод повторно.

Тіло запиту

Поле	Тип	Опис
`server_id`*	string	ID сервера з `GET /proxy/servers`.
`quantity`*	integer	Скільки проксі купити (1–500).
`months`*	integer	Термін оренди в місяцях (1–12).

Помилки

Код	HTTP	Коли спрацьовує
`INSUFFICIENT_BALANCE`	402	Недостатньо коштів.
`NOT_FOUND`	404	Проксі-сервер не знайдено або він неактивний.
`VALIDATION_ERROR`	400	Некоректне тіло запиту.

POST/api/v1/proxy/purchase

curl -X POST https://app.piv.day/api/v1/proxy/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "quantity": 5,
    "months": 1
  }'

200OK

{
  "success": true,
  "data": {
    "order": {
      "id": "ord-uuid-...",
      "country": "DE",
      "quantity": 5,
      "price_total": 2.50,
      "status": "active",
      "expires_at": "2026-02-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "items": [
        {
          "login": "user1",
          "password": "pass1",
          "host": "185.1.2.3",
          "socks5_port": 1080,
          "http_port": 3128,
          "ipv6": "2a00:1:2:3::1"
        },
        {
          "login": "user2",
          "password": "pass2",
          "host": "185.1.2.3",
          "socks5_port": 1080,
          "http_port": 3128,
          "ipv6": "2a00:1:2:3::2"
        }
      ]
    }
  }
}

Продовжити замовлення

POST/api/v1/proxy/orders/{id}/renew

Продовжити активне замовлення проксі на додаткову кількість місяців.

Тіло запиту

Поле	Тип	Опис
`months`*	integer	Скільки місяців додати.

POST/api/v1/proxy/orders/ord-uuid-.../renew

curl -X POST https://app.piv.day/api/v1/proxy/orders/ord-uuid-.../renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "months": 1 }'

200OK

{
  "success": true,
  "data": {
    "order_id": "ord-uuid-...",
    "cost": 5.00,
    "new_expires_at": "2026-03-01T00:00:00Z"
  }
}

Restore прострочених замовлень

POST/api/v1/proxy/orders/{id}/restore

Відновити прострочений замовлення проксі без повторної купівлі. Логін, пароль, IPv6-адреси, країна і прив'язки — ті самі. Термін продовжується на 1 місяць. Антидетект переналаштовувати не потрібно.

POST/api/v1/proxy/orders/ord-uuid-.../restore

curl -X POST https://app.piv.day/api/v1/proxy/orders/ord-uuid-.../restore \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "order_id": "ord-uuid-...",
    "quantity": 10,
    "total_cost": 5.00,
    "expires_at": "2026-03-01T00:00:00Z"
  }
}

Експорт списку проксі

GET/api/v1/proxy/orders/{id}/export

Експортувати облікові дані проксі замовлення у вигляді текстового списку (login:password@host:port).

Query-параметри

Поле	Тип	Опис
`format`	string	Формат експорту: `socks5`, `http` або `both` (за замовчуванням `socks5`).

GET/api/v1/proxy/orders/ord-uuid-.../export

curl "https://app.piv.day/api/v1/proxy/orders/ord-uuid-.../export?format=socks5" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "content": "user1:[email protected]:1080\nuser2:[email protected]:1080",
    "filename": "piv-day-proxy-ord-uuid--socks5.txt",
    "format": "socks5",
    "count": 2
  }
}

Документація

Домени

Пошук і реєстрація без KYC, автоматичний Cloudflare і SSL, управління DNS-записами та NS-серверами через API.

Перевірка доступності

GET/api/v1/domains/search

Перевірити доступність і вартість реєстрації домену.

Query-параметри

Поле	Тип	Опис
`q`*	string	Ім'я домену для пошуку, наприклад `mysite.com`.

GET/api/v1/domains/search

curl "https://app.piv.day/api/v1/domains/search?q=mysite.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "domain": "mysite.com",
    "available": true,
    "create_price": 12.50,
    "renew_price": 12.50,
    "currency": "USD"
  }
}

Список доменів

GET/api/v1/domains

Список ваших зареєстрованих доменів з можливістю фільтрації.

Query-параметри

Поле	Тип	Опис
`limit`	integer	Кількість записів. За замовчуванням: 100, максимум: 500.
`offset`	integer	Зміщення для пагінації.
`status`	string	Статус домену: `active`, `pending`, `expired`.
`cloudflare`	string	Фільтр за статусом Cloudflare: `true` або `false`.
`auto_renew`	string	Фільтр за автопродовженням: `true` або `false`.
`search`	string	Пошук за доменним іменем.

GET/api/v1/domains

curl "https://app.piv.day/api/v1/domains?status=active&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "domains": [
      {
        "id": "dom-uuid-...",
        "domain_name": "mysite.com",
        "status": "active",
        "registered_at": "2026-01-01T00:00:00Z",
        "expires_at": "2027-01-01T00:00:00Z",
        "auto_renew": true,
        "cloudflare_enabled": true,
        "cloudflare_status": "active",
        "ssl_type": "lets_encrypt",
        "ssl_status": "active",
        "ssl_mode": "full",
        "ssl_expires_at": "2026-04-01T00:00:00Z",
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-01T00:00:00Z"
      }
    ],
    "pagination": { "total": 1, "limit": 20, "offset": 0 }
  }
}

Реєстрація домену

POST/api/v1/domains

Зареєструвати новий домен. Запит асинхронний — повертає queue_id для відстеження. Cloudflare УВІМК: поле nameservers передавати не можна, опційно можна передати dns_records та ssl_mode. Cloudflare ВИМК: поля dns_records та ssl_mode передавати не можна, nameservers обов'язковий (не менше 2). NS-сервери Cloudflare ми ніколи не розкриваємо.

Тіло запиту

Поле	Тип	Опис
`domain`*	string	Ім'я домену для реєстрації, наприклад `mysite.com`.
`period`*	integer	Термін реєстрації в роках (1–10).
`cloudflare`*	boolean	Підключити домен до Cloudflare автоматично.
`auto_renew`*	boolean	Увімкнути автоматичне продовження.
`ssl_mode`	string	`flexible` \| `full` \| `strict`. Лише при `cloudflare: true`.
`nameservers`	string[]	Обов'язково при `cloudflare: false` (≥2 NS). Заборонено при `cloudflare: true`.
`dns_records`	object[]	Початкові DNS-записи. Лише при `cloudflare: true`.

Помилки

Код	HTTP	Коли спрацьовує
`DOMAIN_NOT_AVAILABLE`	400	Домен недоступний для реєстрації.
`INSUFFICIENT_BALANCE`	402	Недостатньо коштів.
`VALIDATION_ERROR`	400	Некоректне тіло запиту.

POST/api/v1/domains

curl -X POST https://app.piv.day/api/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mysite.com",
    "period": 1,
    "cloudflare": true,
    "auto_renew": true,
    "ssl_mode": "full",
    "dns_records": [
      { "type": "A", "name": "@", "content": "1.2.3.4", "proxied": true }
    ]
  }'

POST/api/v1/domains

curl -X POST https://app.piv.day/api/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mysite.com",
    "period": 1,
    "cloudflare": false,
    "auto_renew": false,
    "nameservers": ["ns1.myhost.com", "ns2.myhost.com"]
  }'

202Accepted

{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "domain": {
      "id": "dom-uuid-...",
      "domain_name": "mysite.com",
      "status": "purchasing",
      "period": 1,
      "cloudflare_enabled": true,
      "auto_renew": true,
      "ssl_mode": "full",
      "created_at": "2026-01-01T00:00:00Z"
    }
  }
}

Статус завдання реєстрації

GET/api/v1/domains/queue/{id}

Перевірити статус запису черги реєстрації або продовження домену. При статусі completed у відповіді одразу повна картка домену — окремий запит до /domains/{id} не потрібний.

GET/api/v1/domains/queue/que-uuid-...

curl https://app.piv.day/api/v1/domains/queue/que-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"

pending / processing

{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "domain": "mysite.com",
    "status": "pending"
  }
}

completed — повна картка

{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "status": "completed",
    "domain": {
      "id": "dom-uuid-...",
      "domain_name": "mysite.com",
      "status": "active",
      "registered_at": "2026-01-01T12:00:00Z",
      "expires_at": "2027-01-01T12:00:00Z",
      "auto_renew": true,
      "cloudflare_enabled": true,
      "cloudflare_status": "active",
      "ssl_type": "lets_encrypt",
      "ssl_status": "active",
      "ssl_mode": "full",
      "ssl_expires_at": "2026-04-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T12:00:00Z",
      "dns_records": [
        { "name": "@", "type": "A", "content": "1.2.3.4", "ttl": 1, "priority": null, "proxied": true }
      ]
    }
  }
}

Один домен

GET/api/v1/domains/{id}

Отримати повну інформацію про зареєстрований домен. Поле nameservers присутнє лише якщо cloudflare_enabled: false.

GET/api/v1/domains/dom-uuid-...

curl https://app.piv.day/api/v1/domains/dom-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "domain": {
      "id": "dom-uuid-...",
      "domain_name": "mysite.com",
      "status": "active",
      "registered_at": "2026-01-01T12:00:00Z",
      "expires_at": "2027-01-01T12:00:00Z",
      "auto_renew": true,
      "cloudflare_enabled": true,
      "cloudflare_status": "active",
      "ssl_type": "lets_encrypt",
      "ssl_status": "active",
      "ssl_mode": "full",
      "ssl_expires_at": "2026-04-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T12:00:00Z",
      "dns_records": [
        { "name": "@", "type": "A", "content": "1.2.3.4", "ttl": 1, "priority": null, "proxied": true },
        { "name": "www", "type": "CNAME", "content": "mysite.com", "ttl": 1, "priority": null, "proxied": true }
      ]
    }
  }
}

Продовжити домен

POST/api/v1/domains/{id}/renew

Продовжити реєстрацію домену. Повертає queue_id для відстеження.

Тіло запиту

Поле	Тип	Опис
`period`*	integer	На скільки років продовжити.

POST/api/v1/domains/dom-uuid-.../renew

curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "period": 1 }'

202Accepted

{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "domain_id": "dom-uuid-...",
    "expires_at": "2027-01-01T12:00:00Z"
  }
}

Авто-продовження

POST/api/v1/domains/{id}/auto-renew

Увімкнути або вимкнути автоматичне продовження домену.

Тіло запиту

Поле	Тип	Опис
`auto_renew`*	boolean	Нове значення прапора.

POST/api/v1/domains/dom-uuid-.../auto-renew

curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../auto-renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auto_renew": true }'

200OK

{
  "success": true,
  "data": {
    "id": "dom-uuid-...",
    "auto_renew": true
  }
}

DNS-записи домену

GET/api/v1/domains/{id}/dns

Список DNS-записів домену (через Cloudflare).

GET/api/v1/domains/dom-uuid-.../dns

curl https://app.piv.day/api/v1/domains/dom-uuid-.../dns \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "records": [
      {
        "id": "rec-uuid-...",
        "type": "A",
        "name": "@",
        "content": "1.2.3.4",
        "ttl": 1,
        "priority": null,
        "proxied": true
      }
    ]
  }
}

Додати DNS-запис

POST/api/v1/domains/{id}/dns

Створити новий DNS-запис.

Тіло запиту

Поле	Тип	Опис
`type`*	string	Тип запису: `A`, `AAAA`, `CNAME`, `MX`, `TXT` тощо.
`name`*	string	Ім'я запису, наприклад `@` або `subdomain`.
`content`*	string	Значення запису.
`ttl`	integer	TTL у секундах (`1` = авто).
`proxied`	boolean	Проксіювати через Cloudflare.

POST/api/v1/domains/dom-uuid-.../dns

curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../dns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "@",
    "content": "1.2.3.4",
    "ttl": 1,
    "proxied": true
  }'

201Created

{
  "success": true,
  "data": {
    "record": {
      "id": "rec-uuid-...",
      "type": "A",
      "name": "@",
      "content": "1.2.3.4",
      "ttl": 1,
      "priority": null,
      "proxied": true
    }
  }
}

Змінити DNS-запис

PUT/api/v1/domains/{id}/dns/{recordId}

Оновити існуючий DNS-запис за ID. Перезаписуються лише передані поля.

PUT/api/v1/domains/dom-uuid-.../dns/rec-uuid-...

curl -X PUT https://app.piv.day/api/v1/domains/dom-uuid-.../dns/rec-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "5.6.7.8" }'

Видалити DNS-запис

DELETE/api/v1/domains/{id}/dns/{recordId}

Видалити DNS-запис за ID.

DELETE/api/v1/domains/dom-uuid-.../dns/rec-uuid-...

curl -X DELETE https://app.piv.day/api/v1/domains/dom-uuid-.../dns/rec-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"

Увімкнути Cloudflare

POST/api/v1/domains/{id}/cloudflare

Увімкнути Cloudflare для домену. NS-сервери Cloudflare не повертаємо — делегування налаштовуємо зі свого боку. Вимкнення Cloudflare через цей ендпоінт не підтримується.

POST/api/v1/domains/dom-uuid-.../cloudflare

curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../cloudflare \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

200OK

{
  "success": true,
  "data": {
    "domain_id": "dom-uuid-...",
    "ssl_mode": "flexible"
  }
}

Змінити NS-сервери

POST/api/v1/domains/{id}/ns-servers

Задати довільні NS-сервери для домену.

POST/api/v1/domains/dom-uuid-.../ns-servers

curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../ns-servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nameservers": ["ns1.example.com", "ns2.example.com"] }'

200OK

{
  "success": true,
  "data": {
    "nameservers": [
      { "nameserver": "ns1.example.com", "order_index": 1 },
      { "nameserver": "ns2.example.com", "order_index": 2 }
    ]
  }
}

Документація

Вайти

Генерація вайт-сторінок за нішею та тиром. Кожен сайт унікальний. Зміна домену та контактів — без перегенерації.

Список тирів

GET/api/v1/whites/tiers

Список доступних тарифів генерації з цінами. price — ціна за генерацію вже для вашого акаунта (з урахуванням підписки), одне число. quality: "premium" коштує дорожче (обчислюється при створенні). Блог лише у v2_tier3: перші 3 статті включені, за кожну додаткову (до 20) — extra_article_price.

GET/api/v1/whites/tiers

curl https://app.piv.day/api/v1/whites/tiers \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "tiers": [
      {
        "tier_key": "v2_tier1",
        "name": "Landing",
        "generator_version": "v2",
        "min_articles": 0,
        "max_articles": 0,
        "price": 3.00,
        "extra_article_price": null
      },
      {
        "tier_key": "v2_tier2",
        "name": "Multi-page",
        "generator_version": "v2",
        "min_articles": 0,
        "max_articles": 0,
        "price": 6.00,
        "extra_article_price": null
      },
      {
        "tier_key": "v2_tier3",
        "name": "Full + Blog",
        "generator_version": "v2",
        "min_articles": 3,
        "max_articles": 20,
        "price": 10.00,
        "extra_article_price": 1.50
      }
    ]
  }
}

Список вайтів

GET/api/v1/whites

Список ваших завдань генерації з можливістю фільтрації.

Query-параметри

Поле	Тип	Опис
`limit`	integer	Кількість записів. За замовчуванням: 100, максимум: 500.
`offset`	integer	Зміщення для пагінації.
`status`	string	`queued` \| `processing` \| `done` \| `failed`.
`tier_key`	string	`v2_tier1` \| `v2_tier2` \| `v2_tier3`.

GET/api/v1/whites

curl "https://app.piv.day/api/v1/whites?status=done&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "whites": [
      {
        "id": "job-uuid-...",
        "name": "My White",
        "status": 10,
        "tier_key": "v2_tier3",
        "quality": "standard",
        "niche": "IT Consulting",
        "country": "DE",
        "language": "de",
        "domain": "mysite.com",
        "result_url": null,
        "created_at": "2026-01-01T00:00:00Z"
      }
    ],
    "pagination": { "total": 1, "limit": 20, "offset": 0 }
  }
}

Запустити генерацію

POST/api/v1/whites

Поставити завдання генерації вайт-сторінки в чергу. Оплата знімається відразу. Фінальний статус надходить на вебхук white.completed / white.failed або перевіряється через GET /whites/{id}.

Тіло запиту

Поле	Тип	Опис
`name`*	string	Назва завдання (2–20 символів).
`tier_key`*	string	`v2_tier1` \| `v2_tier2` \| `v2_tier3`.
`niche`*	string	Тематика сайту (до 25 символів).
`country`*	string	Код країни (ISO 3166-1 alpha-2).
`language`*	string	Основна мова сайту (ISO 639-1).
`quality`	string	`standard` \| `premium` (за замовчуванням `standard`).
`languages`	string[]	Список мов. Перша включена в ціну, кожна наступна — доплата.
`domain`	string	Повний домен (напр. `example.com`). Без автопідстановки.
`email`	string	Повний email (напр. `[email protected]`). Без автопідстановки.
`phone`	string	Телефон контакту.
`address`	string	Адреса компанії.
`legal_name`	string	Юридична назва.
`style_hint`	string	Стиль дизайну (Random, Мінімалістичний, Корпоративний тощо).
`keywords`	string[]	Ключові слова для SEO.
`banned_words`	string[]	Слова, заборонені в контенті.
`blog_count`	integer	Кількість статей блогу 3–20. Тільки для `v2_tier3`. За статті понад 3 — доплата.
`contacts_mode`	string	`same` \| `template`.
`contacts_template`	string	Шаблон контактної сторінки (при `contacts_mode=template`).
`facebook`	string	Повний URL сторінки Facebook.
`instagram`	string	Повний URL профілю Instagram.
`linkedin`	string	Повний URL профілю LinkedIn.
`youtube`	string	Повний URL каналу YouTube.
`tiktok`	string	Повний URL профілю TikTok.

Помилки

Код	HTTP	Коли спрацьовує
`INSUFFICIENT_BALANCE`	402	Недостатньо коштів.
`INVALID_TIER`	400	Тариф з таким ключем не знайдено.
`VALIDATION_ERROR`	400	Некоректне тіло запиту.

POST/api/v1/whites

curl -X POST https://app.piv.day/api/v1/whites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Blog DE",
    "tier_key": "v2_tier3",
    "niche": "IT Consulting",
    "country": "DE",
    "language": "de",
    "quality": "premium",
    "languages": ["de", "en"],
    "domain": "techblog-de.com",
    "email": "[email protected]",
    "phone": "+49 30 123456",
    "address": "Berliner Str. 1, 10115 Berlin",
    "legal_name": "TechBlog GmbH",
    "style_hint": "Корпоративный",
    "keywords": ["IT", "consulting", "cloud"],
    "banned_words": ["cheap", "free"],
    "blog_count": 8,
    "contacts_mode": "same",
    "facebook": "https://facebook.com/techblogde",
    "instagram": "https://instagram.com/techblogde",
    "linkedin": "https://linkedin.com/company/techblogde"
  }'

200OK

{
  "success": true,
  "data": {
    "status": "queued",
    "white": {
      "id": "job-uuid-...",
      "name": "Tech Blog DE",
      "status": 0,
      "tier_key": "v2_tier3",
      "quality": "premium",
      "niche": "IT Consulting",
      "country": "DE",
      "language": "de",
      "domain": "techblog-de.com",
      "result_url": null,
      "created_at": "2026-01-01T00:00:00Z"
    }
  }
}

Один вайт

GET/api/v1/whites/{id}

Отримати поточний стан завдання генерації.

GET/api/v1/whites/job-uuid-...

curl https://app.piv.day/api/v1/whites/job-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "white": {
      "id": "job-uuid-...",
      "name": "Tech Blog DE",
      "status": 10,
      "tier_key": "v2_tier3",
      "quality": "premium",
      "niche": "IT Consulting",
      "country": "DE",
      "language": "de",
      "domain": "techblog-de.com",
      "result_url": null,
      "created_at": "2026-01-01T00:00:00Z"
    }
  }
}

Завантажити архів

GET/api/v1/whites/{id}/download

Отримати підписане короткоживуче посилання на готовий архів вайт-сторінки. Посилання діє ~5 хвилин (див. expires_at). Якщо минуло — просто запитай /download ще раз, видамо нове. Якщо вайт ще не згенерований, повернеться 409 NOT_READY.

Query-параметри

Поле	Тип	Опис
`format`	string	Формат архіву. За замовчуванням `php`.

Помилки

Код	HTTP	Коли спрацьовує
`NOT_READY`	409	Вайт ще генерується — повтори запит після `white.completed`.

GET/api/v1/whites/job-uuid-.../download

curl "https://app.piv.day/api/v1/whites/job-uuid-.../download?format=php" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "url": "https://strg.piv.day/download/<user_id>/<job_id>?format=php&token=<hmac>&filename=<name>.zip",
    "filename": "example.com_2026-05-28_DE_en.zip",
    "format": "php",
    "expires_at": "2026-05-28T14:46:00Z"
  }
}

Змінити домен та контакти

POST/api/v1/whites/{id}/config

Оновити контактні дані компанії у вайт-сторінці без повторної генерації.

POST/api/v1/whites/job-uuid-.../config

curl -X POST https://app.piv.day/api/v1/whites/job-uuid-.../config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "My Brand",
    "domain": "newdomain.com",
    "email": "[email protected]",
    "phone": "+49 30 123456",
    "address": "Berliner Str. 1, Berlin",
    "legal": "My Brand GmbH"
  }'

Документація

Вебхуки

Підписка на події платформи: вхідні SMS, готові сайти, замовлення, що закінчуються. URL для сповіщень задається в налаштуваннях API-ключа.

Як вони надходять

На ваш URL відправляється звичайний POST з JSON-тілом. Формат однаковий для всіх подій: event_type, timestamp і блок data. Ваш сервер повинен відповісти будь-яким 2xx протягом 5 секунд.

Якщо не надійшло

При не-2xx або таймауті — до 3 повторних спроб із затримкою 1 с, 2 с, 4 с. Повна історія доставок доступна на сторінці API-ключів у дашборді. Якщо всі три не пройшли — подія позначається як failed, можна повторно надіслати вручну.

Безпека

Використовуйте HTTPS-ендпойнт. Кожен запит надходить із заголовком User-Agent: piv.day-webhook/1.0. URL для вебхуків налаштовується в профілі API-ключа.

формат запиту

POST <your webhook URL>
Content-Type: application/json
User-Agent: piv.day-webhook/1.0

{
  "event_type": "<event identifier>",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": { ... }
}

Усі події

Подія	Коли спрацьовує
sms.received	На ваш номер надійшло SMS від довіреного відправника.
sms.status_updated	Вихідне SMS змінило статус — наприклад, перейшло у доставку або провалилося.
number.restore_completed	Пакетний Restore дійшов до кінця — надходить фінальний підсумок.
verify.completed	Верифікація Google-акаунта завершилася успішно.
verify.failed	Щось пішло не так — Google не пропустив.
proxy.expires_soon	До кінця оренди замовлення проксі залишилося близько трьох днів.
domain.registered	Замовлення на реєстрацію успішно закрилося — домен живий.
domain.failed	Замовлення не дійшло до кінця — часта причина: домен щойно зайняли.
domain.expires_soon	До закінчення домену залишилося близько тижня.
white.completed	Завдання генерації вайта завершилося успішно.
white.failed	Завдання впало — кошти повертаються на баланс.

Вхідне SMS на ваш номер

sms.received

Найчастіше це коди підтвердження від рекламних мереж. У payload надходить і сирий текст, і автоматично розпізнаний код (якщо є) — можна одразу передати у свій воркфлоу без парсингу. SMS від відомих спамних відправників через вебхук не надсилаються.

payload

{
  "event_type": "sms.received",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "text": "Your verification code is 123456",
    "code": "123456",
    "country": "SE",
    "received_at": "2026-05-22T12:34:56Z"
  }
}

Статус надісланого SMS змінився

sms.status_updated

Підходить, якщо ви надсилаєте підтвердження від свого імені і хочете знати, що повідомлення реально дійшло. Якщо статус failed — у payload надходять код і текст помилки від оператора.

payload

{
  "event_type": "sms.status_updated",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "message_id": "42",
    "old_status": "sent",
    "new_status": "delivered",
    "error_code": null,
    "error_message": null
  }
}

Відновлення номерів завершено

number.restore_completed

Містить два списки: які номери повернулися і які ні. За номери, що не повернулися, сума повертається на баланс — вона теж у payload. Зручно для скриптів: зрозуміло, що запитувати повторно.

payload

{
  "event_type": "number.restore_completed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "restored": [
      {
        "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
        "phone_number": "+46764794425",
        "country": "SE"
      }
    ],
    "failed": [
      {
        "piv_num_id": "abc12-defgh-ijklm-nopqr",
        "phone_number": "+46123456789",
        "country": "SE",
        "refunded": 7.50
      }
    ],
    "total_restored": 1,
    "total_failed": 1,
    "total_refunded": 7.50
  }
}

Google QR-верифікація пройшла успішно

verify.completed

Якщо в процесі прийшло SMS з кодом — воно вже тут, не потрібно окремо його забирати. Поля captured_phone і captured_message містять те, що надіслав Google.

payload

{
  "event_type": "verify.completed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "task_id": 12,
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "status": "sms_sent",
    "captured_phone": "+14155551234",
    "captured_message": "Your Google verification code is 123456",
    "sms_message_id": 42,
    "sms_status": "queued"
  }
}

Google QR-верифікація не пройшла

verify.failed

Поле error_code говорить, що саме: таймаут, відмова, невалідний URL. Сума за неуспішну верифікацію повертається на баланс автоматично.

payload

{
  "event_type": "verify.failed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "task_id": 12,
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "status": "failed",
    "error_code": "VERIFY_TIMEOUT",
    "error_message": "Verification timed out"
  }
}

Проксі незабаром закінчаться

proxy.expires_soon

Потрібно для тих, хто продовжує не автоматично: встигаєте заздалегідь побачити і вирішити — продовжити чи закрити кампанію. За бажання можна підписатися і відразу дергати POST /proxy/orders/{id}/renew.

payload

{
  "event_type": "proxy.expires_soon",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "order_id": "ord-uuid-...",
    "country": "DE",
    "quantity": 10,
    "expires_at": "2026-05-25T00:00:00Z"
  }
}

Домен зареєстровано

domain.registered

Якщо при покупці ви запросили Cloudflare і SSL, всі вже підняті — прапор cloudflare_enabled покаже статус. Можна одразу додавати DNS-записи або розгортати сайт.

payload

{
  "event_type": "domain.registered",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "domain_id": "dom-uuid-...",
    "domain_name": "mysite.com",
    "registered_at": "2026-05-22T12:34:56Z",
    "expires_at": "2027-05-22T12:34:56Z",
    "cloudflare_enabled": true
  }
}

Реєстрація домену не вдалася

domain.failed

Поле error містить зрозуміле пояснення. Сума повертається на баланс. Можна вибрати інше ім'я і оформити замовлення заново.

payload

{
  "event_type": "domain.failed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "domain_id": "dom-uuid-...",
    "domain_name": "mysite.com",
    "error": "Domain is no longer available"
  }
}

Домен незабаром закінчиться

domain.expires_soon

Зручно, якщо авто-продовження вимкнено: встигаєте продовжити вручну до того, як домен піде в редемпцію. Прапор auto_renew підкаже, чи потрібне втручання.

payload

{
  "event_type": "domain.expires_soon",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "domain_id": "dom-uuid-...",
    "domain_name": "mysite.com",
    "expires_at": "2026-05-29T00:00:00Z",
    "auto_renew": false
  }
}

Вайт згенеровано

white.completed

Архів доступний через GET /whites/{id}/download. Якщо у вайта був вказаний домен, sitemap і контакти вже підставлені під нього — можна одразу деплоїти.

payload

{
  "event_type": "white.completed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "job_id": "job-uuid-...",
    "name": "My White",
    "tier_key": "t1",
    "country": "DE"
  }
}

Генерація вайта не вдалася

white.failed

Поле error пояснює причину. Можна одразу запустити нове завдання через POST /whites — без втрат.

payload

{
  "event_type": "white.failed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "job_id": "job-uuid-...",
    "name": "My White",
    "error": "Generation failed"
  }
}

Довідник

Коди помилок

Усі помилки повертаються в одному форматі: HTTP-статус + поле error.code + зрозуміле повідомлення в error.message.

Код	HTTP	Коли спрацьовує
`UNAUTHORIZED`	401	Ключ відсутній, прострочений або відкликаний.
`INSUFFICIENT_PERMISSIONS`	403	У ключа немає необхідного скоупу для цієї дії.
`PERMISSION_DENIED`	403	Доступ на рівні акаунту не дозволяє цю дію (наприклад, функцію вимкнено).
`VALIDATION_ERROR`	400	Невалідне тіло запиту. Повідомлення пояснює, яке поле і чому.
`NUMBER_NOT_FOUND`	404	Номер не існує або не належить акаунту.
`NUMBER_EXPIRED`	403	Номер прострочений — використайте Restore (протягом 7 днів) або придбайте новий.
`NUMBER_NOT_ACTIVE`	400	Номер перебуває в стані, що не дозволяє цю операцію.
`INSUFFICIENT_BALANCE`	402	Недостатньо коштів для виконання операції.
`INVALID_MESSAGE_FORMAT`	400	Тіло SMS занадто довге або містить заборонені символи.
`COUNTRY_NOT_AVAILABLE`	400	Країна недоступна для купівлі або продовження.
`NO_NUMBERS_AVAILABLE`	400	У вибраній країні зараз немає вільних номерів.
`NO_RESTORABLE_NUMBERS`	404	Жоден із переданих номерів більше не підлягає відновленню.
`RATE_LIMITED`	429	Перевищено rate limit. Зачекайте час, вказаний у заголовку `Retry-After`.
`INTERNAL_ERROR`	500	Щось пішло не так з нашого боку. Якщо повторюється — зверніться до служби підтримки.

Приклад помилки

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough balance: required $5.00, available $1.20"
  }
}

Знайшли неточність або потрібен ендпойнт, якого немає в документації? Підтримка відповідає в Telegram протягом години в робочий час.

Зв'язатися