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 в течение часа в рабочее время.

Связаться