# Gắn tên miền riêng

`POST /service/@id/builder/sites/@site/domains` · TinoPage Builder, token đăng nhập của chủ dịch vụ

Gắn một tên miền vào website: HTTP 201, tên miền ở trạng thái `pending` kèm bản ghi DNS khách cần đặt (`dns`). Với tên miền gốc, `dns` có thêm CNAME cho `www`. Website chưa đăng trả 409 `SITE_NOT_PUBLISHED`; hết số tên miền: 409 `LIMIT_EXCEEDED` (`details.key: domains_per_site`); tên miền đang gắn website khác: 409 `DOMAIN_TAKEN`; không phải tên miền: 422 `VALIDATION_FAILED`.

## HTTP request

| Mục | Giá trị |
| --- | --- |
| URL | `https://api.tino.vn/service/@id/builder/sites/@site/domains` |
| Method | `POST` |
| Xác thực | token đăng nhập của chủ dịch vụ TinoPage Builder (`Authorization: Bearer <token>`); gateway `/v1` chưa mở TinoPage Builder |
| Content-Type | `application/json` |

## Tham số

| Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `id` | đường dẫn | int | có | ID dịch vụ TinoPage Builder |
| `site` | đường dẫn | string | có | ID website (UUID, `id` ở danh sách website) |
| `hostname` | body | string | có | Tên miền cần gắn (1–253 ký tự), vd `example.vn` hoặc `banhang.example.vn`; TinoPage Builder tự bỏ `https://`, đường dẫn, chữ hoa |
| `idempotency_key` | body | string | không | 8–64 ký tự `A-Za-z0-9._:-`: gửi lại cùng khoá và cùng nội dung thì nhận lại kết quả lần trước, không làm lại |

## Example request

```bash
curl -X POST "https://api.tino.vn/service/100003/builder/sites/5b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e/domains" \
  -H "Authorization: Bearer $TINO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "hostname": "banhang.example.vn",
  "idempotency_key": "them-ten-mien-0001"
}'
```

`$TINO_TOKEN` là token đăng nhập của chủ dịch vụ TinoPage Builder. Tham số đường dẫn trong ví dụ là giá trị mẫu.

SDK ([SDK & Ví dụ](/docs/sdk)): chưa có hàm riêng, dùng `client.request("POST", "/service/@id/builder/sites/@site/domains")`.

## Example response

```json
{
 "data": {
  "hostname": "banhang.example.vn",
  "status": "pending",
  "ssl_status": "pending",
  "txt_ok": false,
  "cname_ok": false,
  "dns": [
   {
    "type": "CNAME",
    "name": "banhang",
    "value": "dns.tino.page"
   },
   {
    "type": "TXT",
    "name": "_tino-verify.banhang",
    "value": "tino-site-verify=4b6d0e2a7c914f3e8a5b1c2d9e0f7a6b"
   }
  ],
  "error": "",
  "checked_at": "0001-01-01T00:00:00Z",
  "url": "https://banhang.example.vn",
  "owner_verified": false,
  "check_count": 0
 }
}
```

Mẫu dựng theo API của TinoPage Builder (Tino chuyển tiếp nguyên câu trả lời trong `data`), giá trị là ví dụ.