piv.day
У застосунок
До огляду APIЗавантажити .txt
Документація

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

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_codestringДвобуквений ISO-код країни (наприклад SE).
price_per_monthnumberПідсумкова ціна для вашого тарифу — те, що реально списується при купівлі. Якщо у вас Premium або Business, знижка вже включена.
base_pricenumberЦіна без знижок (тариф Free). Повертається для порівняння — щоб бачити, скільки заощаджує підписка.
can_send_smsbooleanЧи можна з цього номера надсилати вихідні SMS.
can_receive_smsbooleanЧи можна приймати вхідні SMS.
sms_send_pricenumber|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-параметри

ПолеТипОпис
limitintegerРозмір сторінки. За замовчуванням 100, максимум 100.
offsetintegerЗміщення для пагінації.
countrystringISO-код країни для фільтра.
statusstringОдин із active, expired, cancelled, pending.
searchstringПідрядок для пошуку по номеру або кастомному імені.
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_FOUND404Номер не знайдено або він не належить акаунту.
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*stringISO-код країни.
duration_months*integerТермін оренди в місяцях (мінімум 1).
auto_renew*booleanУвімкнути авто-продовження одразу після купівлі.
custom_namestringНеобов'язкове людинозрозуміле ім'я для номера.

Помилки

КодHTTPКоли спрацьовує
COUNTRY_NOT_AVAILABLE400Країна недоступна або для неї немає цін.
NO_NUMBERS_AVAILABLE400У вказаній країні зараз немає вільних номерів.
INSUFFICIENT_BALANCE402На балансі недостатньо коштів для купівлі.
VALIDATION_ERROR400Невалідні поля в тілі запиту.
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_FOUND404Номер не знайдено або він не належить акаунту.
COUNTRY_NOT_AVAILABLE400Для країни номера не знайдено цін.
INSUFFICIENT_BALANCE402Недостатньо коштів для продовження.
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_FOUND404Номер не знайдено або він не належить акаунту.
VALIDATION_ERROR400Невалідне значення в тілі запиту.
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_NUMBERS404Жоден із переданих номерів не можна відновити (минув 7-денний термін або номер не ваш).
INSUFFICIENT_BALANCE402Недостатньо коштів для оплати відновлення.
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-параметри

ПолеТипОпис
limitintegerСкільки повідомлень повернути. За замовчуванням 100, максимум 100.
offsetintegerЗміщення для пагінації.
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_FOUND404Номер не знайдено або він не належить акаунту.
NUMBER_EXPIRED403Номер вже закінчився.
NUMBER_NOT_ACTIVE400Номер зараз у стані, що не дозволяє відправку.
INSUFFICIENT_BALANCE402Недостатньо коштів для відправки.
INVALID_MESSAGE_FORMAT400Тіло повідомлення перевищує допустиму довжину або містить заборонені символи.
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. Вартість списується з балансу в момент запуску.

Тіло запиту

ПолеТипОпис
target_url*stringПовний URL Google-верифікації акаунту. Має починатися з https://accounts.google.com.
proxy*stringРядок підключення до проксі для задачі автоматизації. Будь-який формат, який приймає автоматизаційний сервер (наприклад socks5://user:pass@host:port).

Помилки

КодHTTPКоли спрацьовує
VALIDATION_ERROR400Некоректне тіло запиту (немає target_url/proxy або URL не починається з accounts.google.com).
INSUFFICIENT_PERMISSIONS403API-ключ не має дозволу can_send_sms / can_run_verifications.
PERMISSION_DENIED403Учасник команди не має дозволу verification.run або sms.send.
NUMBER_NOT_FOUND404Номер не знайдено або він не ваш.
NUMBER_NOT_ACTIVE400Номер не в активному статусі.
SMS_DISABLED400Відправка SMS вимкнена для цього номера.
INSUFFICIENT_BALANCE402Недостатньо коштів для верифікації.
PROXY_DEAD502Проксі недоступний — баланс повернено.
QUEUE_FULL503Сервер зайнятий, спробуйте пізніше — баланс повернено.
SERVER_UNAVAILABLE503Сервер автоматизації недоступний — баланс повернено.
GO_SERVER_ERROR503Автоматизаційний сервер повернув несподівану помилку. Списання повернуто на баланс.
INTERNAL_ERROR500Внутрішня помилка.
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 '{
    "target_url": "https://accounts.google.com/signin/v2/challenge/...",
    "proxy": "socks5://user:[email protected]:1080"
  }'
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-параметри

ПолеТипОпис
limitintegerРозмір сторінки. За замовчуванням 100, максимум 100.
offsetintegerЗміщення для пагінації.
statusstringФільтр статусу: active, expired, cancelled.
searchstringПошук за замовленням.
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*stringID сервера з GET /proxy/servers.
quantity*integerСкільки проксі купити (1–500).
months*integerТермін оренди в місяцях (1–12).

Помилки

КодHTTPКоли спрацьовує
PERMISSION_DENIED403API-ключ або учасник команди не має дозволу proxy.purchase.
INSUFFICIENT_BALANCE402Недостатньо коштів.
NOT_FOUND404Проксі-сервер не знайдено або він неактивний.
VALIDATION_ERROR400Некоректне тіло запиту.
PURCHASE_FAILED503Не вдалося зв'язатися з проксі-сервером або створити проксі.
INTERNAL_ERROR500Внутрішня помилка.
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 місяць. Антидетект переналаштовувати не потрібно.

Помилки

КодHTTPКоли спрацьовує
NOT_FOUND404Замовлення або проксі-сервер не знайдено.
VALIDATION_ERROR400Відновити можна лише замовлення зі статусом expired.
PURCHASE_FAILED503Не вдалося зв'язатися з проксі-сервером або відновити проксі.
INTERNAL_ERROR500Внутрішня помилка.
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-параметри

ПолеТипОпис
formatstringФормат експорту: 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

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

Query-параметри

ПолеТипОпис
limitintegerРозмір сторінки. За замовчуванням 100, максимум 100.
offsetintegerЗміщення для пагінації.
statusstringСтатус домену: active, pending, expired, failed, cancelled.
cloudflarestringФільтр за статусом Cloudflare: true або false.
auto_renewstringФільтр за автопродовженням: true або false.
searchstringПошук за доменним іменем.
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_modestringflexible | full | strict. Лише при cloudflare: true.
nameserversstring[]Обов'язково при cloudflare: false (≥2 NS). Заборонено при cloudflare: true.
dns_recordsobject[]Початкові DNS-записи. Лише при cloudflare: true.

Помилки

КодHTTPКоли спрацьовує
PERMISSION_DENIED403API-ключ або учасник команди не має дозволу domains.purchase.
DOMAIN_NOT_AVAILABLE400Домен недоступний для реєстрації.
INSUFFICIENT_BALANCE402Недостатньо коштів.
VALIDATION_ERROR400Некоректне тіло запиту.
INTERNAL_ERROR500Внутрішня помилка.
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 для відстеження. Поле expires_at у відповіді — поточна дата реєстрації; фінальна дата після продовження приходить через webhook domain.expires_soon.

Тіло запиту

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

Помилки

КодHTTPКоли спрацьовує
NOT_FOUND404Домен не знайдено.
VALIDATION_ERROR400Некоректне тіло запиту.
DOMAIN_NOT_REGISTERED400Домен ще не зареєстровано у провайдера.
DOMAIN_NOT_ACTIVE400Продовжувати можна лише активні домени.
INTERNAL_ERROR500Внутрішня помилка.
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Значення запису.
ttlintegerTTL у секундах (1 = авто).
priorityintegerПріоритет для MX/SRV-записів. Необов'язковий; ігнорується для типів, де не застосовується.
proxiedbooleanПроксіювати через 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 через цей ендпоінт не підтримується.

Тіло запиту

ПолеТипОпис
enabled*booleantrue — увімкнути Cloudflare для домену. false цим ендпоінтом не підтримується.
ssl_modestringРежим SSL: flexible, full, strict. За замовчуванням flexible.

Помилки

КодHTTPКоли спрацьовує
NOT_FOUND404Домен не знайдено.
VALIDATION_ERROR400Некоректне тіло запиту.
NOT_SUPPORTED400Вимкнення Cloudflare через цей ендпоінт не підтримується.
ALREADY_ENABLED400Cloudflare вже увімкнено для домену.
DOMAIN_NOT_REGISTERED400Домен ще не зареєстровано у провайдера.
CF_ZONE_LOOKUP_FAILED500Зона існує в Cloudflare, але отримати її не вдалося.
CF_ZONE_CREATE_FAILED500Не вдалося створити зону в Cloudflare.
OP_NS_UPDATE_FAILED500Не вдалося оновити nameservers у реєстратора.
DB_UPDATE_FAILED500Не вдалося зберегти зміни в базі.
INTERNAL_ERROR500Внутрішня помилка.
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-сервери для домену.

Тіло запиту

ПолеТипОпис
nameservers*string[]Список nameservers. Максимум 12 записів.
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-параметри

ПолеТипОпис
limitintegerРозмір сторінки. За замовчуванням 100, максимум 100.
offsetintegerЗміщення для пагінації.
statusstringqueued | processing | done | failed.
tier_keystringv2_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*stringv2_tier1 | v2_tier2 | v2_tier3.
niche*stringНіша сайту. Значення довші за 25 символів мовчки обрізаються.
country*stringКод країни (ISO 3166-1 alpha-2).
language*stringОсновна мова сайту (ISO 639-1).
qualitystringstandard | premium (за замовчуванням standard).
languagesstring[]Список мов. Перша включена в ціну, кожна наступна — доплата.
domainstringПовний домен (напр. example.com). Без автопідстановки.
emailstringПовний email (напр. [email protected]). Без автопідстановки.
phonestringТелефон контакту.
addressstringАдреса компанії.
legal_namestringЮридична назва.
style_hintstringСтиль дизайну. Один із: Random, Минималистичный, Корпоративный, Современный, Элегантный, Технологичный, Креативный, Профессиональный, Стартап стиль, Премиум, Динамичный, Классический, Футуристичный, Дружелюбный, Строгий, Яркий, Нейтральный, Градиентный, Монохромный, Контрастный, Светлый. Будь-яке інше значення мовчки замінюється на Random.
keywordsstring[]Ключові слова для SEO.
banned_wordsstring[]Слова, заборонені в контенті.
blog_countintegerКількість статей блогу 3–20. Тільки для v2_tier3. За статті понад 3 — доплата.
generator_versionstringПеревизначення версії генератора. Просунутий параметр, зазвичай непотрібний.
facebookstringПовний URL сторінки Facebook.
instagramstringПовний URL профілю Instagram.
linkedinstringПовний URL профілю LinkedIn.
youtubestringПовний URL каналу YouTube.
tiktokstringПовний URL профілю TikTok.

Помилки

КодHTTPКоли спрацьовує
PERMISSION_DENIED403API-ключ або учасник команди не має дозволу whites.purchase.
INSUFFICIENT_BALANCE402Недостатньо коштів.
INVALID_TIER400Тариф з таким ключем не знайдено.
VALIDATION_ERROR400Некоректне тіло запиту.
INTERNAL_ERROR500Внутрішня помилка.
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,
    "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-параметри

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

Помилки

КодHTTPКоли спрацьовує
NOT_READY409Вайт ще генерується — повтори запит після 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Коли спрацьовує
UNAUTHORIZED401Ключ відсутній, прострочений або відкликаний.
INSUFFICIENT_PERMISSIONS403У ключа немає необхідного скоупу для цієї дії.
PERMISSION_DENIED403Доступ на рівні акаунту не дозволяє цю дію (наприклад, функцію вимкнено).
VALIDATION_ERROR400Невалідне тіло запиту. Повідомлення пояснює, яке поле і чому.
NUMBER_NOT_FOUND404Номер не існує або не належить акаунту.
NUMBER_EXPIRED403Номер прострочений — використайте Restore (протягом 7 днів) або придбайте новий.
NUMBER_NOT_ACTIVE400Номер перебуває в стані, що не дозволяє цю операцію.
INSUFFICIENT_BALANCE402Недостатньо коштів для виконання операції.
INVALID_MESSAGE_FORMAT400Тіло SMS занадто довге або містить заборонені символи.
COUNTRY_NOT_AVAILABLE400Країна недоступна для купівлі або продовження.
NO_NUMBERS_AVAILABLE400У вибраній країні зараз немає вільних номерів.
NO_RESTORABLE_NUMBERS404Жоден із переданих номерів більше не підлягає відновленню.
RATE_LIMITED429Перевищено rate limit. Зачекайте час, вказаний у заголовку Retry-After.
INTERNAL_ERROR500Щось пішло не так з нашого боку. Якщо повторюється — зверніться до служби підтримки.
Приклад помилки
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough balance: required $5.00, available $1.20"
  }
}

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

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