# piv.day API Reference

Full reference for the piv.day REST API: every endpoint, request body, response shape, error code and webhook. Exported from https://piv.day/api/docs for use with AI assistants.

---

## Getting started

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

**200 OK**
```
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

## 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.

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| `country_code` | string | Mã quốc gia ISO hai chữ cái (ví dụ: `SE`). |
| `price_per_month` | number | Giá 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_price` | number | Giá 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_sms` | boolean | Liệu số này có hỗ trợ gửi SMS đi hay không. |
| `can_receive_sms` | boolean | Liệu số này có hỗ trợ nhận SMS vào hay không. |
| `sms_send_price` | number\|null | Giá 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. |

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

**200 OK**
```json
{
  "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.

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `limit` | integer | Kích thước trang (mặc định 50, tối đa 200). |
| `offset` | integer | Độ lệch phân trang. |
| `country` | string | Bộ lọc mã quốc gia ISO. |
| `status` | string | Một trong `active`, `expired`, `pending_restore`. |
| `search` | string | Tìm kiếm chuỗi con theo số điện thoại hoặc tên tùy chỉnh. |

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

**200 OK**
```json
{
  "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.

**Errors**

| Code | HTTP | When it fires |
| --- | --- | --- |
| `NUMBER_NOT_FOUND` | 404 | Số không tồn tại hoặc không thuộc tài khoản này. |

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

**200 OK**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `country_code` * | string | Mã quốc gia ISO. |
| `duration_months` * | integer | Thời hạn thuê tính bằng tháng (tối thiểu 1). |
| `auto_renew` * | boolean | Bật tự động gia hạn ngay sau khi mua. |
| `custom_name` | string | Tên tùy chọn dễ đọc cho số. |

**Errors**

| Code | HTTP | When it fires |
| --- | --- | --- |
| `COUNTRY_NOT_AVAILABLE` | 400 | Quốc gia không khả dụng hoặc không có giá. |
| `NO_NUMBERS_AVAILABLE` | 400 | Hiện không có số trống tại quốc gia được yêu cầu. |
| `INSUFFICIENT_BALANCE` | 402 | Số dư không đủ để mua. |
| `VALIDATION_ERROR` | 400 | Các trường không hợp lệ trong nội dung yêu cầu. |

**curl**
```bash
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"
  }'
```

**200 OK**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `duration_months` * | integer | Số tháng cần thêm. |

**Errors**

| Code | HTTP | When it fires |
| --- | --- | --- |
| `NUMBER_NOT_FOUND` | 404 | Số không tồn tại hoặc không thuộc tài khoản này. |
| `COUNTRY_NOT_AVAILABLE` | 400 | Không tìm thấy giá cho quốc gia của số. |
| `INSUFFICIENT_BALANCE` | 402 | Không đủ tiền để gia hạn. |

**curl**
```bash
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 }'
```

**200 OK**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `custom_name` * | string | Tên mới cho số. |

**Errors**

| Code | HTTP | When it fires |
| --- | --- | --- |
| `NUMBER_NOT_FOUND` | 404 | Số không tồn tại hoặc không thuộc tài khoản này. |
| `VALIDATION_ERROR` | 400 | Giá trị không hợp lệ trong nội dung yêu cầu. |

**curl**
```bash
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" }'
```

**200 OK**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `auto_renew` * | boolean | Giá trị cờ tự động gia hạn mới. |

**curl**
```bash
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 }'
```

**200 OK**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `piv_num_ids` * | string[] | Mảng ID số cần khôi phục. |

**Errors**

| Code | HTTP | When it fires |
| --- | --- | --- |
| `NO_RESTORABLE_NUMBERS` | 404 | Khô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_BALANCE` | 402 | Không đủ tiền để thực hiện khôi phục. |

**curl**
```bash
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"
    ]
  }'
```

**200 OK**
```json
{
  "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.

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `limit` | integer | Số lượng tin nhắn cần trả về (mặc định 50, tối đa 200). |
| `offset` | integer | Độ lệch phân trang. |

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

**200 OK**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `to_number` * | string | Số người nhận theo định dạng quốc tế (E.164). |
| `message_body` * | string | Nội dung tin nhắn. Hỗ trợ GSM-7 và UCS-2. |

**Errors**

| Code | HTTP | When it fires |
| --- | --- | --- |
| `NUMBER_NOT_FOUND` | 404 | Số không tồn tại hoặc không thuộc tài khoản này. |
| `NUMBER_EXPIRED` | 403 | Số đã hết hạn. |
| `NUMBER_NOT_ACTIVE` | 400 | Số đang ở trạng thái không cho phép gửi. |
| `INSUFFICIENT_BALANCE` | 402 | Không đủ tiền để gửi. |
| `INVALID_MESSAGE_FORMAT` | 400 | Nội dung tin nhắn vượt quá độ dài cho phép hoặc chứa ký tự bị cấm. |

**curl**
```bash
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"
  }'
```

**200 OK**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `gv_url` * | string | URL xác minh Google đầy đủ (lấy từ trang Google). |

**Errors**

| Code | HTTP | When it fires |
| --- | --- | --- |
| `NUMBER_NOT_FOUND` | 404 | Số không tồn tại hoặc không phải của bạn. |
| `NUMBER_NOT_ACTIVE` | 400 | Số không ở trạng thái hoạt động. |
| `SMS_DISABLED` | 400 | Gửi SMS bị vô hiệu hóa cho số này. |
| `INSUFFICIENT_BALANCE` | 402 | Không đủ tiền cho xác minh. |
| `PROXY_DEAD` | 502 | Proxy không khả dụng — số dư đã được hoàn trả. |
| `QUEUE_FULL` | 503 | Hàng đợi đầy, thử lại sau — số dư đã được hoàn trả. |
| `SERVER_UNAVAILABLE` | 503 | Máy chủ tự động hóa không khả dụng — số dư đã được hoàn trả. |

**curl**
```bash
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/..." }'
```

**202 Accepted**
```json
{
  "success": true,
  "message": "Verification initiated"
}
```

## 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á.

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

**200 OK**
```json
{
  "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.

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `limit` | integer | Kích thước trang. Mặc định 100, tối đa 500. |
| `offset` | integer | Độ lệch phân trang. |
| `status` | string | Lọc theo trạng thái: `active`, `expired`. |
| `search` | string | Tìm kiếm trong các đơn hàng. |

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

**200 OK**
```json
{
  "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.

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

**200 OK**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `server_id` * | string | ID máy chủ từ `GET /proxy/servers`. |
| `quantity` * | integer | Số lượng proxy cần mua (1–500). |
| `months` * | integer | Thời hạn thuê tính bằng tháng (1–12). |

**Errors**

| Code | HTTP | When it fires |
| --- | --- | --- |
| `INSUFFICIENT_BALANCE` | 402 | Không đủ số dư. |
| `NOT_FOUND` | 404 | Không tìm thấy máy chủ proxy hoặc máy chủ không hoạt động. |
| `VALIDATION_ERROR` | 400 | Nội dung yêu cầu không hợp lệ. |

**curl**
```bash
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
  }'
```

**200 OK**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `months` * | integer | Số tháng cần thêm. |

**curl**
```bash
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 }'
```

**200 OK**
```json
{
  "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.

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

**200 OK**
```json
{
  "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).

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `format` | string | Định dạng xuất: `socks5`, `http` hoặc `both` (mặc định `socks5`). |

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

**200 OK**
```json
{
  "success": true,
  "data": {
    "content": "user1:pass1@1.2.3.4:1080\nuser2:pass2@1.2.3.4:1080",
    "filename": "piv-day-proxy-ord-uuid--socks5.txt",
    "format": "socks5",
    "count": 2
  }
}
```

## 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.

### Kiểm tra tính khả dụng

`GET /api/v1/domains/search`

Kiểm tra xem tên miền có khả dụng không và chi phí đăng ký là bao nhiêu.

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `q` * | string | Tên miền cần tra cứu, ví dụ: `mysite.com`. |

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

**200 OK**
```json
{
  "success": true,
  "data": {
    "domain": "mysite.com",
    "available": true,
    "create_price": 12.50,
    "renew_price": 12.50,
    "currency": "USD"
  }
}
```

### 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.

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `limit` | integer | Số bản ghi mỗi trang. Mặc định 100, tối đa 500. |
| `offset` | integer | Độ lệch phân trang. |
| `status` | string | Trạng thái tên miền: `active`, `pending`, `expired`. |
| `cloudflare` | string | Lọc theo trạng thái Cloudflare: `true` hoặc `false`. |
| `auto_renew` | string | Lọc theo tự động gia hạn: `true` hoặc `false`. |
| `search` | string | Tìm kiếm theo tên miền. |

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

**200 OK**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `domain` * | string | Tên miền cần đăng ký, ví dụ: `mysite.com`. |
| `period` * | integer | Thời hạn đăng ký tính theo năm (1–10). |
| `cloudflare` * | boolean | Kết nối tên miền với Cloudflare tự động. |
| `auto_renew` * | boolean | Bật tự động gia hạn. |
| `ssl_mode` | string | `flexible` \| `full` \| `strict`. Chỉ khi `cloudflare: true`. |
| `nameservers` | string[] | Bắt buộc khi `cloudflare: false` (≥2 NS). Không được dùng khi `cloudflare: true`. |
| `dns_records` | object[] | Bản ghi DNS ban đầu. Chỉ khi `cloudflare: true`. |

**Errors**

| Code | HTTP | When it fires |
| --- | --- | --- |
| `DOMAIN_NOT_AVAILABLE` | 400 | Tên miền không khả dụng để đăng ký. |
| `INSUFFICIENT_BALANCE` | 402 | Không đủ số dư. |
| `VALIDATION_ERROR` | 400 | Nội dung yêu cầu không hợp lệ. |

**Cloudflare BẬT**
```bash
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 }
    ]
  }'
```

**Cloudflare TẮT — NS riêng**
```bash
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"]
  }'
```

**202 Accepted**
```json
{
  "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}`.

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

**pending / processing**
```json
{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "domain": "mysite.com",
    "status": "pending"
  }
}
```

**completed — thông tin đầy đủ**
```json
{
  "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`.

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

**200 OK**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `period` * | integer | Số năm cần gia hạn thêm. |

**curl**
```bash
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 }'
```

**202 Accepted**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `auto_renew` * | boolean | Giá trị cờ mới. |

**curl**
```bash
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 }'
```

**200 OK**
```json
{
  "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).

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

**200 OK**
```json
{
  "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.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `type` * | string | Loại bản ghi: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, v.v. |
| `name` * | string | Tên bản ghi, ví dụ: `@` hoặc `subdomain`. |
| `content` * | string | Giá trị bản ghi. |
| `ttl` | integer | TTL tính bằng giây (`1` = tự động). |
| `proxied` | boolean | Proxy qua Cloudflare. |

**curl**
```bash
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
  }'
```

**201 Created**
```json
{
  "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 đè.

**curl**
```bash
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.

**curl**
```bash
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ợ.

**curl**
```bash
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 }'
```

**200 OK**
```json
{
  "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.

**curl**
```bash
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"] }'
```

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

## 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`.

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

**200 OK**
```json
{
  "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.

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `limit` | integer | Kích thước trang. Mặc định 100, tối đa 500. |
| `offset` | integer | Offset phân trang. |
| `status` | string | `queued` \| `processing` \| `done` \| `failed`. |
| `tier_key` | string | `v2_tier1` \| `v2_tier2` \| `v2_tier3`. |

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

**200 OK**
```json
{
  "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}`.

**Request body**

| Field | Type | Description |
| --- | --- | --- |
| `name` * | string | Tên job (2–20 ký tự). |
| `tier_key` * | string | `v2_tier1` \| `v2_tier2` \| `v2_tier3`. |
| `niche` * | string | Niche của site (tối đa 25 ký tự). |
| `country` * | string | Mã quốc gia (ISO 3166-1 alpha-2). |
| `language` * | string | Ngôn ngữ chính của site (ISO 639-1). |
| `quality` | string | `standard` \| `premium` (mặc định `standard`). |
| `languages` | string[] | 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í. |
| `domain` | string | Domain đầy đủ (vd. `example.com`). Không tự động điền. |
| `email` | string | Email đầy đủ (vd. `info@example.com`). Không tự động điền. |
| `phone` | string | Số điện thoại liên hệ. |
| `address` | string | Địa chỉ công ty. |
| `legal_name` | string | Tên pháp lý. |
| `style_hint` | string | Phong cách thiết kế (Random, Minimal, Corporate, v.v.). |
| `keywords` | string[] | Từ khóa SEO. |
| `banned_words` | string[] | Các từ bị cấm trong nội dung. |
| `blog_count` | integer | Số 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_mode` | string | `same` \| `template`. |
| `contacts_template` | string | Template trang liên hệ (khi `contacts_mode=template`). |
| `facebook` | string | URL đầy đủ trang Facebook. |
| `instagram` | string | URL đầy đủ hồ sơ Instagram. |
| `linkedin` | string | URL đầy đủ hồ sơ LinkedIn. |
| `youtube` | string | URL đầy đủ kênh YouTube. |
| `tiktok` | string | URL đầy đủ hồ sơ TikTok. |

**Errors**

| Code | HTTP | When it fires |
| --- | --- | --- |
| `INSUFFICIENT_BALANCE` | 402 | Số dư không đủ. |
| `INVALID_TIER` | 400 | Không tìm thấy tier với key đó. |
| `VALIDATION_ERROR` | 400 | Body request không hợp lệ. |

**curl**
```bash
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": "info@techblog-de.com",
    "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"
  }'
```

**200 OK**
```json
{
  "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.

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

**200 OK**
```json
{
  "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`.

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `format` | string | Định dạng archive. Mặc định là `php`. |

**Errors**

| Code | HTTP | When it fires |
| --- | --- | --- |
| `NOT_READY` | 409 | White page đang được tạo — thử lại sau `white.completed`. |

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

**200 OK**
```json
{
  "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.

**curl**
```bash
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": "info@newdomain.com",
    "phone": "+49 30 123456",
    "address": "Berliner Str. 1, Berlin",
    "legal": "My Brand GmbH"
  }'
```

## Webhooks

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.

```
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": { ... }
}
```

**Retries.** 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.

**Security.** 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.

### All events

| Event | When it fires |
| --- | --- |
| `sms.received` | Mộ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_updated` | Một SMS gửi đi đã thay đổi trạng thái — đã giao, thất bại, v.v. |
| `number.restore_completed` | Một Restore hàng loạt đã hoàn thành — tóm tắt cuối cùng đến đây. |
| `verify.completed` | Xá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_soon` | Cò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_soon` | Còn khoảng một tuần trước khi tên miền hết hạn. |
| `white.completed` | Tác vụ tạo White đã hoàn thành thành công. |
| `white.failed` | Tá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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

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

## Error codes

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`.

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

| Code | HTTP | When it fires |
| --- | --- | --- |
| `UNAUTHORIZED` | 401 | Khóa bị thiếu, đã hết hạn hoặc bị thu hồi. |
| `INSUFFICIENT_PERMISSIONS` | 403 | Key không có scope cần thiết cho hành động này. |
| `PERMISSION_DENIED` | 403 | Quyề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_ERROR` | 400 | Nộ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_FOUND` | 404 | Số không tồn tại hoặc không thuộc tài khoản này. |
| `NUMBER_EXPIRED` | 403 | Số đã hết hạn — dùng Restore (trong vòng 7 ngày) hoặc mua số mới. |
| `NUMBER_NOT_ACTIVE` | 400 | Số đang ở trạng thái không cho phép thao tác này. |
| `INSUFFICIENT_BALANCE` | 402 | Không đủ số dư để thực hiện thao tác này. |
| `INVALID_MESSAGE_FORMAT` | 400 | Nội dung SMS quá dài hoặc chứa ký tự không được phép. |
| `COUNTRY_NOT_AVAILABLE` | 400 | Quốc gia không khả dụng để mua hoặc gia hạn. |
| `NO_NUMBERS_AVAILABLE` | 400 | Hiện không có số trống nào ở quốc gia đã chọn. |
| `NO_RESTORABLE_NUMBERS` | 404 | Không có số nào trong danh sách cung cấp có thể được khôi phục nữa. |
| `RATE_LIMITED` | 429 | Đã vượt quá rate limit. Hãy chờ theo thời gian trong header `Retry-After`. |
| `INTERNAL_ERROR` | 500 | Có 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ợ. |