piv.day
Mở ứng dụng
Quay lại tổng quan APITải xuống .txt
Tài liệu

Bắt đầu

REST API trên gói Business. Token Bearer, JSON, endpoint idempotent, mã lỗi có thể dự đoán. Mỗi endpoint đi kèm ví dụ yêu cầu và phản hồi.

Base URL

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

Tất cả endpoint đều nằm dưới tiền tố này. Một môi trường duy nhất — không có host staging riêng biệt.

Xác thực

Authorization: Bearer YOUR_API_KEY

Khóa được tạo trong dashboard tại Cài đặt → API Keys. Mỗi khóa có quyền hạn chi tiết (đọc số, gửi SMS, mua proxy, v.v.). Token bị lộ được xoay vòng bằng một cú nhấp — không cần onboard lại nhóm.

Tài khoản

GET/api/v1/account
curl https://app.piv.day/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"
Một endpoint tiện ích duy nhất — số dư và email của tài khoản hiện tại. Dùng để xác nhận khóa hoạt động và xác thực được cấu hình đúng.
{
  "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

Định dạng phản hồi

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

Mọi phản hồi đều là JSON. Khi có lỗi, success = false và body chứa error.code và error.message.

Rate limits

100 yêu cầu mỗi phút cho mỗi API key. Giới hạn dùng chung cho tất cả endpoint. Cần thêm dung lượng cho tải cao? Liên hệ hỗ trợ Telegram và chúng tôi sẽ nâng giới hạn. Khi vượt giới hạn, bạn nhận được `429 RATE_LIMITED` và header `Retry-After` — số giây cần chờ trước lần gọi tiếp theo.
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

Tài liệu

Số điện thoại

Mua, gia hạn và khôi phục số. Nhận và gửi SMS. Khởi chạy xác minh Google QR. Đăng ký nhận sự kiện qua webhook.

Danh sách quốc gia và giá

GET/api/v1/numbers/countries

Trả về các quốc gia có thể mua với giá hiện tại và khả năng SMS. Tất cả giá đã bao gồm chiết khấu gói đăng ký của bạn.

Trường phản hồi

TrườngKiểuMô tả
country_codestringMã quốc gia ISO hai chữ cái (ví dụ: SE).
price_per_monthnumberGiá cuối cho gói của bạn — số tiền thực tế được tính khi mua. Chiết khấu Premium / Business đã được áp dụng.
base_pricenumberGiá không có chiết khấu (gói Free). Trả về để so sánh, cho thấy gói đăng ký tiết kiệm được bao nhiêu.
can_send_smsbooleanLiệu số này có hỗ trợ gửi SMS đi hay không.
can_receive_smsbooleanLiệu số này có hỗ trợ nhận SMS vào hay không.
sms_send_pricenumber|nullGiá SMS đi, cũng đã áp dụng chiết khấu gói. null khi gửi không được hỗ trợ từ quốc gia này.
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
    }
  ]
}

Danh sách số của tài khoản

GET/api/v1/numbers

Trả về một trang số tài khoản với bộ lọc theo quốc gia, trạng thái và tìm kiếm theo số hoặc tên tùy chỉnh.

Tham số truy vấn

TrườngKiểuMô tả
limitintegerKích thước trang (mặc định 50, tối đa 200).
offsetintegerĐộ lệch phân trang.
countrystringBộ lọc mã quốc gia ISO.
statusstringMột trong active, expired, pending_restore.
searchstringTìm kiếm chuỗi con theo số điện thoại hoặc tên tùy chỉnh.
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 }
  }
}

Lấy một số theo ID

GET/api/v1/numbers/{piv_num_id}

Bản ghi đầy đủ của số: trạng thái, ngày, tự động gia hạn, thẻ, hướng SMS được phép.

Lỗi

MãHTTPKhi nào kích hoạt
NUMBER_NOT_FOUND404Số không tồn tại hoặc không thuộc tài khoản này.
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
  }
}

Mua một số

POST/api/v1/numbers/purchase

Mua một số ở quốc gia được chọn trong khoảng thời gian nhất định. Chi phí được trừ từ số dư tài khoản. Trả về piv_num_id dùng trong tất cả các thao tác số sau này.

Nội dung yêu cầu

TrườngKiểuMô tả
country_code*stringMã quốc gia ISO.
duration_months*integerThời hạn thuê tính bằng tháng (tối thiểu 1).
auto_renew*booleanBật tự động gia hạn ngay sau khi mua.
custom_namestringTên tùy chọn dễ đọc cho số.

Lỗi

MãHTTPKhi nào kích hoạt
COUNTRY_NOT_AVAILABLE400Quốc gia không khả dụng hoặc không có giá.
NO_NUMBERS_AVAILABLE400Hiện không có số trống tại quốc gia được yêu cầu.
INSUFFICIENT_BALANCE402Số dư không đủ để mua.
VALIDATION_ERROR400Các trường không hợp lệ trong nội dung yêu cầu.
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"
    }
  ]
}

Gia hạn số

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

Gia hạn một số đang hoạt động trong khoảng thời gian nhất định. Chi phí được trừ tại thời điểm gọi API.

Nội dung yêu cầu

TrườngKiểuMô tả
duration_months*integerSố tháng cần thêm.

Lỗi

MãHTTPKhi nào kích hoạt
NUMBER_NOT_FOUND404Số không tồn tại hoặc không thuộc tài khoản này.
COUNTRY_NOT_AVAILABLE400Không tìm thấy giá cho quốc gia của số.
INSUFFICIENT_BALANCE402Không đủ tiền để gia hạn.
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
  }
}

Cập nhật số

PATCH/api/v1/numbers/{piv_num_id}

Hiện tại chỉ có thể cập nhật tên tùy chỉnh.

Nội dung yêu cầu

TrườngKiểuMô tả
custom_name*stringTên mới cho số.

Lỗi

MãHTTPKhi nào kích hoạt
NUMBER_NOT_FOUND404Số không tồn tại hoặc không thuộc tài khoản này.
VALIDATION_ERROR400Giá trị không hợp lệ trong nội dung yêu cầu.
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": []
  }
}

Quản lý tự động gia hạn

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

Bật hoặc tắt tự động gia hạn số. Khi bật, gia hạn được trừ tự động 24 giờ trước khi hết hạn. Nếu số dư không đủ, số sẽ hết hạn; bạn có thể lấy lại qua POST /numbers/restore trong vòng 7 ngày.

Nội dung yêu cầu

TrườngKiểuMô tả
auto_renew*booleanGiá trị cờ tự động gia hạn mới.
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
  }
}

Khôi phục số hết hạn

POST/api/v1/numbers/restore

Khôi phục các số hết hạn trong cửa sổ 7 ngày. Truyền một mảng piv_num_id — các số trở lại với lịch sử SMS và cài đặt được giữ nguyên. Chi phí khôi phục cao hơn mua số mới (bao gồm hệ số khôi phục) — số liệu chính xác hiển thị trong dashboard trước khi xác nhận. Trạng thái cuối cùng của mỗi số đến qua webhook number.restore_completed; hoàn tiền cho các số thất bại được ghi có tự động.

Nội dung yêu cầu

TrườngKiểuMô tả
piv_num_ids*string[]Mảng ID số cần khôi phục.

Lỗi

MãHTTPKhi nào kích hoạt
NO_RESTORABLE_NUMBERS404Không có số nào trong các số được cung cấp có thể khôi phục (cửa sổ 7 ngày đã qua hoặc chúng không phải của bạn).
INSUFFICIENT_BALANCE402Không đủ tiền để thực hiện khôi phục.
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"
    }
  ]
}

Lịch sử SMS theo số

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

Trả về tin nhắn đến và đi của số theo thứ tự thời gian ngược.

Tham số truy vấn

TrườngKiểuMô tả
limitintegerSố lượng tin nhắn cần trả về (mặc định 50, tối đa 200).
offsetintegerĐộ lệch phân trang.
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 }
  }
}

Gửi SMS

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

Có sẵn cho các quốc gia cho phép gửi đi (ví dụ: CA, GB, SE). Chi phí tin nhắn được trừ tại thời điểm gửi.

Nội dung yêu cầu

TrườngKiểuMô tả
to_number*stringSố người nhận theo định dạng quốc tế (E.164).
message_body*stringNội dung tin nhắn. Hỗ trợ GSM-7 và UCS-2.

Lỗi

MãHTTPKhi nào kích hoạt
NUMBER_NOT_FOUND404Số không tồn tại hoặc không thuộc tài khoản này.
NUMBER_EXPIRED403Số đã hết hạn.
NUMBER_NOT_ACTIVE400Số đang ở trạng thái không cho phép gửi.
INSUFFICIENT_BALANCE402Không đủ tiền để gửi.
INVALID_MESSAGE_FORMAT400Nội dung tin nhắn vượt quá độ dài cho phép hoặc chứa ký tự bị cấm.
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"
  }
}

Chạy xác minh Google QR

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

Bắt đầu xác minh Google QR bằng URL được cung cấp. Kết quả — thành công hay thất bại — đến qua webhook verify.completed hoặc verify.failed. Chi phí được trừ khi tác vụ được xếp hàng.

Nội dung yêu cầu

TrườngKiểuMô tả
gv_url*stringURL xác minh Google đầy đủ (lấy từ trang Google).

Lỗi

MãHTTPKhi nào kích hoạt
NUMBER_NOT_FOUND404Số không tồn tại hoặc không phải của bạn.
NUMBER_NOT_ACTIVE400Số không ở trạng thái hoạt động.
SMS_DISABLED400Gửi SMS bị vô hiệu hóa cho số này.
INSUFFICIENT_BALANCE402Không đủ tiền cho xác minh.
PROXY_DEAD502Proxy không khả dụng — số dư đã được hoàn trả.
QUEUE_FULL503Hàng đợi đầy, thử lại sau — số dư đã được hoàn trả.
SERVER_UNAVAILABLE503Máy chủ tự động hóa không khả dụng — số dư đã được hoàn trả.
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"
}
Tài liệu

Proxy

IPv6 dân cư tại hàng chục quốc gia. Mua hàng loạt, gia hạn, Restore giữ nguyên login và mật khẩu, xuất theo định dạng bạn cần.

Danh sách máy chủ

GET/api/v1/proxy/servers

Danh sách máy chủ proxy khả dụng kèm giá.

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
      }
    ]
  }
}

Danh sách đơn hàng

GET/api/v1/proxy/orders

Danh sách các đơn hàng proxy của bạn với bộ lọc theo trạng thái hoặc tìm kiếm.

Tham số truy vấn

TrườngKiểuMô tả
limitintegerKích thước trang. Mặc định 100, tối đa 500.
offsetintegerĐộ lệch phân trang.
statusstringLọc theo trạng thái: active, expired.
searchstringTìm kiếm trong các đơn hàng.
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 }
  }
}

Lấy một đơn hàng

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

Lấy chi tiết một đơn hàng cụ thể, bao gồm danh sách thông tin xác thực proxy.

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"
        }
      ]
    }
  }
}

Mua proxy

POST/api/v1/proxy/purchase

Mua proxy trên máy chủ đã chọn. Một yêu cầu tạo một đơn hàng với N proxy (tối đa 500). Không có đơn hàng hàng loạt — gọi lại phương thức nếu cần thêm.

Nội dung yêu cầu

TrườngKiểuMô tả
server_id*stringID máy chủ từ GET /proxy/servers.
quantity*integerSố lượng proxy cần mua (1–500).
months*integerThời hạn thuê tính bằng tháng (1–12).

Lỗi

MãHTTPKhi nào kích hoạt
INSUFFICIENT_BALANCE402Không đủ số dư.
NOT_FOUND404Không tìm thấy máy chủ proxy hoặc máy chủ không hoạt động.
VALIDATION_ERROR400Nội dung yêu cầu không hợp lệ.
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"
        }
      ]
    }
  }
}

Gia hạn đơn hàng

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

Gia hạn đơn hàng proxy đang hoạt động thêm một số tháng.

Nội dung yêu cầu

TrườngKiểuMô tả
months*integerSố tháng cần thêm.
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 đơn hàng hết hạn

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

Khôi phục lại đơn hàng proxy hết hạn mà không cần mua lại. Tên đăng nhập, mật khẩu, địa chỉ IPv6, quốc gia và liên kết — đều như cũ. Thời hạn gia hạn thêm 1 tháng. Không cần cấu hình lại antidetect.

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"
  }
}

Xuất danh sách proxy

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

Xuất thông tin xác thực proxy của đơn hàng dưới dạng danh sách văn bản (login:password@host:port).

Tham số truy vấn

TrườngKiểuMô tả
formatstringĐịnh dạng xuất: socks5, http hoặc both (mặc định 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
  }
}
Tài liệu

Tên miền

Tìm kiếm và đăng ký không cần KYC, Cloudflare và SSL tự động, quản lý bản ghi DNS và nameserver qua API.

Danh sách tên miền

GET/api/v1/domains

Danh sách các tên miền đã đăng ký của bạn với tùy chọn lọc.

Tham số truy vấn

TrườngKiểuMô tả
limitintegerSố bản ghi mỗi trang. Mặc định 100, tối đa 500.
offsetintegerĐộ lệch phân trang.
statusstringTrạng thái tên miền: active, pending, expired.
cloudflarestringLọc theo trạng thái Cloudflare: true hoặc false.
auto_renewstringLọc theo tự động gia hạn: true hoặc false.
searchstringTìm kiếm theo tên miền.
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 }
  }
}

Đăng ký tên miền

POST/api/v1/domains

Đăng ký tên miền mới. Yêu cầu bất đồng bộ — trả về queue_id để theo dõi. Cloudflare BẬT: không truyền nameservers; có thể tùy chọn truyền dns_records và ssl_mode. Cloudflare TẮT: không truyền dns_records hoặc ssl_mode; nameservers bắt buộc (tối thiểu 2). Chúng tôi không bao giờ tiết lộ nameserver của Cloudflare.

Nội dung yêu cầu

TrườngKiểuMô tả
domain*stringTên miền cần đăng ký, ví dụ: mysite.com.
period*integerThời hạn đăng ký tính theo năm (1–10).
cloudflare*booleanKết nối tên miền với Cloudflare tự động.
auto_renew*booleanBật tự động gia hạn.
ssl_modestringflexible | full | strict. Chỉ khi cloudflare: true.
nameserversstring[]Bắt buộc khi cloudflare: false (≥2 NS). Không được dùng khi cloudflare: true.
dns_recordsobject[]Bản ghi DNS ban đầu. Chỉ khi cloudflare: true.

Lỗi

MãHTTPKhi nào kích hoạt
DOMAIN_NOT_AVAILABLE400Tên miền không khả dụng để đăng ký.
INSUFFICIENT_BALANCE402Không đủ số dư.
VALIDATION_ERROR400Nội dung yêu cầu không hợp lệ.
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"
    }
  }
}

Trạng thái hàng đợi đăng ký

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

Kiểm tra trạng thái của một mục trong hàng đợi đăng ký hoặc gia hạn tên miền. Khi trạng thái là completed, phản hồi đã chứa đầy đủ thông tin tên miền — không cần gọi thêm /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 — thông tin đầy đủ
{
  "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 }
      ]
    }
  }
}

Lấy thông tin một tên miền

GET/api/v1/domains/{id}

Lấy đầy đủ thông tin về tên miền đã đăng ký. Trường nameservers chỉ có khi 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 }
      ]
    }
  }
}

Gia hạn tên miền

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

Gia hạn đăng ký tên miền. Trả về queue_id để theo dõi.

Nội dung yêu cầu

TrườngKiểuMô tả
period*integerSố năm cần gia hạn thêm.
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"
  }
}

Bật/tắt tự động gia hạn

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

Bật hoặc tắt tự động gia hạn cho tên miền.

Nội dung yêu cầu

TrườngKiểuMô tả
auto_renew*booleanGiá trị cờ mới.
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
  }
}

Bản ghi DNS của tên miền

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

Danh sách bản ghi DNS của tên miền (qua 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
      }
    ]
  }
}

Thêm bản ghi DNS

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

Tạo bản ghi DNS mới.

Nội dung yêu cầu

TrườngKiểuMô tả
type*stringLoại bản ghi: A, AAAA, CNAME, MX, TXT, v.v.
name*stringTên bản ghi, ví dụ: @ hoặc subdomain.
content*stringGiá trị bản ghi.
ttlintegerTTL tính bằng giây (1 = tự động).
proxiedbooleanProxy qua 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
    }
  }
}

Cập nhật bản ghi DNS

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

Cập nhật bản ghi DNS hiện có theo ID. Chỉ các trường được truyền vào mới bị ghi đè.

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" }'

Xóa bản ghi DNS

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

Xóa bản ghi DNS theo 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"

Bật Cloudflare

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

Bật Cloudflare cho tên miền. Chúng tôi không trả về nameserver của Cloudflare — việc ủy quyền được thiết lập từ phía chúng tôi. Việc tắt Cloudflare qua endpoint này không được hỗ trợ.

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"
  }
}

Đặt nameserver

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

Đặt nameserver tùy chỉnh cho tên miền.

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 }
    ]
  }
}
Tài liệu

Whites

Tạo white-page theo niche và tier. Mỗi site là duy nhất. Đổi domain và liên hệ mà không cần tạo lại.

Danh sách tier

GET/api/v1/whites/tiers

Các tier tạo có sẵn kèm giá. price là giá mỗi lần tạo đã được áp dụng cho tài khoản của bạn (đã tính gói đăng ký), một con số duy nhất. quality: "premium" tốn kém hơn (tính tại thời điểm tạo). Blog chỉ có ở v2_tier3: 3 bài viết đầu tiên được bao gồm, mỗi bài thêm (tối đa 20) được tính phí theo 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
      }
    ]
  }
}

Danh sách white

GET/api/v1/whites

Danh sách các job tạo của bạn kèm bộ lọc.

Tham số truy vấn

TrườngKiểuMô tả
limitintegerKích thước trang. Mặc định 100, tối đa 500.
offsetintegerOffset phân trang.
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 }
  }
}

Bắt đầu tạo

POST/api/v1/whites

Đưa job tạo white-page vào hàng đợi. Thanh toán được trừ ngay lập tức. Trạng thái cuối cùng đến qua webhook white.completed / white.failed hoặc có thể kiểm tra qua GET /whites/{id}.

Nội dung yêu cầu

TrườngKiểuMô tả
name*stringTên job (2–20 ký tự).
tier_key*stringv2_tier1 | v2_tier2 | v2_tier3.
niche*stringNiche của site (tối đa 25 ký tự).
country*stringMã quốc gia (ISO 3166-1 alpha-2).
language*stringNgôn ngữ chính của site (ISO 639-1).
qualitystringstandard | premium (mặc định standard).
languagesstring[]Danh sách ngôn ngữ. Ngôn ngữ đầu tiên được bao gồm trong giá; mỗi ngôn ngữ thêm sẽ tính phí.
domainstringDomain đầy đủ (vd. example.com). Không tự động điền.
emailstringEmail đầy đủ (vd. [email protected]). Không tự động điền.
phonestringSố điện thoại liên hệ.
addressstringĐịa chỉ công ty.
legal_namestringTên pháp lý.
style_hintstringPhong cách thiết kế (Random, Minimal, Corporate, v.v.).
keywordsstring[]Từ khóa SEO.
banned_wordsstring[]Các từ bị cấm trong nội dung.
blog_countintegerSố bài viết blog 3–20. Chỉ dành cho v2_tier3. Các bài viết ngoài 3 bài sẽ tính phí thêm.
contacts_modestringsame | template.
contacts_templatestringTemplate trang liên hệ (khi contacts_mode=template).
facebookstringURL đầy đủ trang Facebook.
instagramstringURL đầy đủ hồ sơ Instagram.
linkedinstringURL đầy đủ hồ sơ LinkedIn.
youtubestringURL đầy đủ kênh YouTube.
tiktokstringURL đầy đủ hồ sơ TikTok.

Lỗi

MãHTTPKhi nào kích hoạt
INSUFFICIENT_BALANCE402Số dư không đủ.
INVALID_TIER400Không tìm thấy tier với key đó.
VALIDATION_ERROR400Body request không hợp lệ.
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"
    }
  }
}

Lấy một white

GET/api/v1/whites/{id}

Lấy trạng thái hiện tại của một job tạo.

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"
    }
  }
}

Tải xuống archive

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

Lấy link ký ngắn hạn đến archive white-page đã hoàn thành. Link có hiệu lực ~5 phút (xem expires_at). Nếu đã hết hạn, gọi lại /download — chúng tôi sẽ cấp link mới. Nếu white page chưa được tạo, trả về 409 NOT_READY.

Tham số truy vấn

TrườngKiểuMô tả
formatstringĐịnh dạng archive. Mặc định là php.

Lỗi

MãHTTPKhi nào kích hoạt
NOT_READY409White page đang được tạo — thử lại sau 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"
  }
}

Đổi domain và liên hệ

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

Cập nhật dữ liệu liên hệ công ty trong white-page mà không cần tạo lại.

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"
  }'
Tài liệu

Webhooks

Đăng ký nhận sự kiện nền tảng: SMS đến, trang web hoàn thành, đơn hàng sắp hết hạn. URL thông báo được đặt trong cấu hình khóa API.

Cách chúng đến

Chúng tôi gửi một POST đơn giản với nội dung JSON đến URL của bạn. Cấu trúc giống nhau cho mọi sự kiện: event_type, timestamp và một khối data. Máy chủ của bạn phải phản hồi với bất kỳ 2xx nào trong vòng 5 giây.

Khi gửi thất bại

Khi nhận được không-2xx hoặc timeout — tối đa 3 lần thử lại với khoảng nghỉ 1s / 2s / 4s. Lịch sử giao hàng đầy đủ nằm ở trang API keys trong dashboard. Nếu cả ba đều thất bại, sự kiện được đánh dấu là failed và có thể gửi lại thủ công.

Bảo mật

Sử dụng endpoint HTTPS. Mỗi yêu cầu đến kèm theo header User-Agent: piv.day-webhook/1.0. URL webhook được cấu hình trong hồ sơ API key.

định dạng yêu cầu
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": { ... }
}

Tất cả sự kiện

Sự kiệnKhi nào kích hoạt
sms.receivedMột người gửi đáng tin cậy vừa nhắn tin đến một trong các số của bạn.
sms.status_updatedMột SMS gửi đi đã thay đổi trạng thái — đã giao, thất bại, v.v.
number.restore_completedMột Restore hàng loạt đã hoàn thành — tóm tắt cuối cùng đến đây.
verify.completedXác minh tài khoản Google đã hoàn tất thành công.
verify.failedĐã xảy ra lỗi — Google không chấp nhận.
proxy.expires_soonCòn khoảng ba ngày cho đơn hàng proxy.
domain.registeredĐơn đăng ký hoàn tất thành công — tên miền đã hoạt động.
domain.failedĐơn hàng không hoàn thành — nguyên nhân phổ biến: tên vừa bị người khác đăng ký.
domain.expires_soonCòn khoảng một tuần trước khi tên miền hết hạn.
white.completedTác vụ tạo White đã hoàn thành thành công.
white.failedTác vụ thất bại — tiền được hoàn lại vào số dư.

SMS đến số của bạn

sms.received

Thường đây là mã xác minh từ các mạng quảng cáo. Payload bao gồm văn bản thô và mã được phát hiện tự động (khi có) để bạn có thể chuyển thẳng vào workflow mà không cần parsing. Tin nhắn từ những người gửi spam đã biết sẽ không được chuyển tiếp.

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"
  }
}

Trạng thái SMS gửi đi đã thay đổi

sms.status_updated

Hữu ích khi bạn gửi xác nhận từ số của mình và cần biết chúng có thực sự đến nơi không. Nếu trạng thái là failed, mã lỗi và tin nhắn của nhà mạng có trong 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
  }
}

Khôi phục số hoàn tất

number.restore_completed

Chứa hai danh sách — số nào đã trở lại và số nào không. Số tiền hoàn lại cho những số thất bại cũng có trong payload. Tiện lợi cho các script thử lại thông minh.

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
  }
}

Xác minh Google QR thành công

verify.completed

Nếu mã SMS đến trong quá trình xử lý, nó đã có ở đây rồi — không cần fetch thêm. captured_phone và captured_message chứa những gì Google đã gửi.

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"
  }
}

Xác minh Google QR thất bại

verify.failed

error_code cho bạn biết cụ thể là gì — timeout, từ chối, URL không hợp lệ. Các xác minh thất bại được hoàn tiền vào số dư tự động.

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 sắp hết hạn

proxy.expires_soon

Dành cho những người không tự động gia hạn: bạn thấy trước và quyết định — kéo dài hoặc kết thúc chiến dịch. Kết nối với POST /proxy/orders/{id}/renew để gia hạn hoàn toàn tự động.

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"
  }
}

Tên miền đã được đăng ký

domain.registered

Nếu bạn yêu cầu Cloudflare và SSL khi mua, cả hai đã được kích hoạt — cloudflare_enabled phản ánh trạng thái. Bạn có thể thêm bản ghi DNS hoặc triển khai trang web ngay lập tức.

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
  }
}

Đăng ký tên miền thất bại

domain.failed

Trường error có lý do dễ đọc. Chi phí được hoàn lại vào số dư. Chọn tên khác và thử lại.

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"
  }
}

Tên miền sắp hết hạn

domain.expires_soon

Hữu ích khi tắt tự động gia hạn: bạn có thời gian để gia hạn thủ công trước khi tên miền vào giai đoạn chuộc lại. Cờ auto_renew cho bạn biết có cần can thiệp không.

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 đã được tạo

white.completed

Kho lưu trữ có sẵn qua GET /whites/{id}/download. Nếu White đã có tên miền được đặt, sitemap và các liên hệ đã được kết nối — sẵn sàng để triển khai.

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

Tạo White thất bại

white.failed

Trường error giải thích lý do. Bắt đầu một công việc mới qua POST /whites — không mất tiền.

payload
{
  "event_type": "white.failed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "job_id": "job-uuid-...",
    "name": "My White",
    "error": "Generation failed"
  }
}
Tài liệu tham khảo

Mã lỗi

Mọi lỗi đều có cùng định dạng: HTTP status + trường error.code + thông báo dễ đọc trong error.message.

MãHTTPKhi nào kích hoạt
UNAUTHORIZED401Khóa bị thiếu, đã hết hạn hoặc bị thu hồi.
INSUFFICIENT_PERMISSIONS403Key không có scope cần thiết cho hành động này.
PERMISSION_DENIED403Quyền truy cập cấp tài khoản không cho phép hành động này (ví dụ: tính năng bị tắt).
VALIDATION_ERROR400Nội dung yêu cầu không hợp lệ. Thông báo giải thích trường nào bị lỗi và lý do.
NUMBER_NOT_FOUND404Số không tồn tại hoặc không thuộc tài khoản này.
NUMBER_EXPIRED403Số đã hết hạn — dùng Restore (trong vòng 7 ngày) hoặc mua số mới.
NUMBER_NOT_ACTIVE400Số đang ở trạng thái không cho phép thao tác này.
INSUFFICIENT_BALANCE402Không đủ số dư để thực hiện thao tác này.
INVALID_MESSAGE_FORMAT400Nội dung SMS quá dài hoặc chứa ký tự không được phép.
COUNTRY_NOT_AVAILABLE400Quốc gia không khả dụng để mua hoặc gia hạn.
NO_NUMBERS_AVAILABLE400Hiện không có số trống nào ở quốc gia đã chọn.
NO_RESTORABLE_NUMBERS404Không có số nào trong danh sách cung cấp có thể được khôi phục nữa.
RATE_LIMITED429Đã vượt quá rate limit. Hãy chờ theo thời gian trong header Retry-After.
INTERNAL_ERROR500Có sự cố xảy ra ở phía chúng tôi. Nếu vẫn tiếp diễn — hãy liên hệ bộ phận hỗ trợ.
Ví dụ lỗi
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough balance: required $5.00, available $1.20"
  }
}

Phát hiện lỗi hoặc cần endpoint chưa có? Hỗ trợ trả lời trên Telegram trong vòng một giờ trong giờ làm việc.

Liên hệ hỗ trợ
piv.day Tài liệu API — số điện thoại, tên miền, proxy, white page