# Hồ sơ chủ thể tên miền

Tên miền `.vn` đã thanh toán mà chủ thể chưa đủ thông tin hoặc chưa đủ hồ sơ (eKYC CCCD, bản khai của tổ chức) thì có đơn nhưng **chưa được đăng ký** với VNNIC: trạng thái `Pending`. Bốn route dưới đây cho phần mềm của khách xem tên miền nào đang chờ, còn thiếu gì, rồi sửa chủ thể; đủ hồ sơ thì Tino tự đăng ký tên miền.

Cập nhật: 2026-10-27.

Tên miền chưa hoàn tất hồ sơ **chưa được giữ chỗ**: người khác vẫn đăng ký được. Theo Thông tư 48/2025/TT-BKHCN, nguyên tắc "đăng ký trước được cấp trước" chỉ áp cho tên miền đã hoàn thành thủ tục và trả phí. Nên báo khách hoàn tất sớm.

## Route và quyền

| Route | Việc | Quyền |
| --- | --- | --- |
| [`GET /v1/domains/pending`](/docs/api/get-domains-pending) | Tên miền chưa kích hoạt và việc còn phải làm | `domains:registrant` |
| [`GET /v1/domains/{id}/registrant`](/docs/api/get-domains-id-registrant) | Chủ thể và tình trạng hồ sơ của một tên miền đang chờ | `domains:registrant` |
| [`PUT /v1/domains/{id}/registrant`](/docs/api/put-domains-id-registrant) | Lưu chủ thể (khai mới hoặc dùng chủ thể của tên miền khác); Tino thử đăng ký ngay | `domains:registrant` |
| [`GET /v1/registrants`](/docs/api/get-registrants) | Chủ thể của các tên miền đang chạy, để chọn lại | `domains:registrant` |

Cả bốn route cần `domains:registrant` (Xem và hoàn tất hồ sơ chủ thể tên miền đang chờ đăng ký): quyền này chỉ có ở [token API cá nhân](/docs/personal-tokens) có giới hạn IP; ứng dụng OAuth và máy chủ MCP không bao giờ được quyền này. Route trả đủ dữ liệu chủ thể của chính khách (CCCD, ngày sinh, số điện thoại, địa chỉ): không ghi các trường này vào log.

eKYC và nộp bản khai làm ở Client Area của Tino (tino.vn), không qua API.

## Tên miền đang chờ

`GET /v1/domains/pending`, tên miền cũ trước:

```json
{
  "domains": [
    {
      "id": 200001,
      "name": "example.vn",
      "status": "Pending",
      "subject_type": "ind",
      "ready": false,
      "actions": [{ "code": "ekyc", "message": "Chủ thể cần eKYC CCCD trong tài khoản này" }],
      "reason": "Chưa eKYC CCCD 001******001"
    }
  ]
}
```

| Trường | Nghĩa |
| --- | --- |
| `subject_type` | `ind` cá nhân · `org` tổ chức · `hkd` hộ kinh doanh |
| `ready` | `true`: đủ hồ sơ, Tino đang đăng ký (vài phút) |
| `actions` | việc khách còn phải làm (bảng dưới); rỗng mà `ready: false` là bản khai đã nộp, đang chờ Tino duyệt |
| `reason` | lý do lần đăng ký gần nhất chưa được; có thể `null`. Số giấy tờ (dãy 9–13 chữ số) trong câu được che, chỉ giữ 3 số đầu và 3 số cuối |

Không có tên miền nào: `{"domains": []}`. Tên miền đăng ký xong thì biến khỏi danh sách này và chuyển `Active` ở `GET /v1/domain`.

## Việc còn phải làm

| `actions[].code` | Việc |
| --- | --- |
| `fields` | Thiếu hoặc sai các trường trong `fields` (ví dụ `["nationalid", "city"]`): sửa rồi `PUT` |
| `owner_fields` | Như trên, cho chủ hộ của hộ kinh doanh |
| `ekyc`, `owner_ekyc` | Chủ thể (hoặc chủ hộ) cần eKYC đúng CCCD đã khai, trong chính tài khoản này |
| `ekyc_name`, `owner_ekyc_name` | Họ tên đã khai khác tên trên eKYC: sửa đúng như CCCD rồi `PUT` |
| `ekyc_other_account`, `owner_ekyc_other_account` | CCCD đã eKYC ở tài khoản Tino khác: dùng chủ thể khác hoặc liên hệ Tino |
| `declaration` | Tổ chức: nộp bản khai đã ký (hoặc ký số hồ sơ tổ chức) ở Client Area |

## Xem chủ thể

`GET /v1/domains/{id}/registrant`:

```json
{
  "domain": { "id": 200001, "name": "example.vn", "status": "Pending" },
  "subject_type": "ind",
  "registrant": {
    "firstname": "Van A", "lastname": "Nguyen", "companyname": "", "taxid": "", "householdsid": "",
    "nationalid": "001090000001", "birthday": "1990-01-01", "gender": "M", "email": "user@example.com",
    "phonenumber": "0900000001", "country": "VN", "state": "Thành phố Hồ Chí Minh", "city": "Phường Bến Thành", "ward": "",
    "address1": "123 Example Street", "address2": "", "postcode": "", "position": ""
  },
  "owner": null,
  "dossier": { "ekyc": "required", "declaration": "not_needed" },
  "actions": [{ "code": "ekyc", "message": "Chủ thể cần eKYC CCCD trong tài khoản này" }],
  "reason": "Chưa eKYC CCCD 001******001",
  "ready": false
}
```

- `state`, `city` là **tên** tỉnh / thành và phường / xã (danh mục sau sáp nhập), không phải mã.
- `owner`: chủ hộ (họ tên, CCCD…) khi `subject_type` là `hkd`; VNNIC xét eKYC của chủ hộ. Loại khác: `null`.
- `dossier.ekyc`: `ok` · `required` · `name_mismatch` · `other_account` · `not_needed` (tổ chức, đuôi không phải `.vn`).
- `dossier.declaration` (tổ chức): `accepted` · `pending` (đã nộp, chờ duyệt) · `cancelled` (bị từ chối) · `none` · `not_needed`. `dossier.signature`: `ok` (đã ký số hồ sơ tổ chức theo mã số thuế) · `none`.

## Dùng lại chủ thể cũ

`GET /v1/registrants` trả chủ thể của các tên miền **đang chạy** của khách, mới trước, mỗi người / tổ chức một dòng:

```json
{
  "registrants": [
    { "from_domain_id": 200002, "domain": "example.com.vn", "subject_type": "ind", "registrant": { "…": "như trên" }, "owner": null, "ready": true, "actions": [] }
  ]
}
```

`ready: true`: chủ thể đã eKYC (hoặc đã ký số) trong tài khoản này, dùng cho tên miền mới là đăng ký được ngay. Tổ chức chỉ có bản khai giấy ở tên miền cũ thì `ready: false`, `actions` có `declaration`: bản khai gắn với từng tên miền, phải nộp lại.

## Lưu chủ thể

`PUT /v1/domains/{id}/registrant`, body JSON, một trong hai dạng:

```json
{ "from_domain_id": 200002 }
```

```json
{
  "registrant": {
    "firstname": "Van A", "lastname": "Nguyen", "nationalid": "001090000001", "phonenumber": "0900000001",
    "state": "Thành phố Hồ Chí Minh", "city": "Phường Bến Thành", "address1": "123 Example Street",
    "email": "user@example.com", "birthday": "1990-01-01", "gender": "M", "country": "VN"
  },
  "owner": null
}
```

- Gửi **đủ các trường** của chủ thể: trường không gửi coi như để trống; trường lạ bị bỏ qua.
- Bắt buộc với `.vn`: `firstname`, `lastname`, `nationalid`, `phonenumber`, `state`, `city`, `address1`; tổ chức thêm `companyname`, `taxid`; hộ kinh doanh thêm `householdsid` và `owner` (chủ hộ: `firstname`, `lastname`, `nationalid`). Đuôi khác: `firstname`, `lastname`, `email`, `phonenumber`, `address1`, `city`, `country`.
- Lưu xong Tino thử đăng ký ngay và trả hồ sơ mới (cùng dạng `GET`); đọc lại `actions`, `ready` để biết bước tiếp theo. Không gọi lại thì hệ thống tự thử khoảng 5 phút một lần.
- Chỉ dùng cho tên miền đang chờ. Đổi chủ thể tên miền đã `Active`: [`PUT /v1/domain/{id}/contact`](/docs/api/put-domain-id-contact).

## Lỗi

Lỗi dạng `{"error": ["<câu tiếng Việt>"]}`, hiện thẳng cho khách được.

| HTTP | Câu | Khi nào |
| --- | --- | --- |
| 403 | `insufficient_scope` | token thiếu quyền `domains:registrant` (token của ứng dụng OAuth, hoặc token cá nhân không chọn quyền này) |
| 404 | Không tìm thấy tên miền chờ đăng ký | tên miền đã `Active`, đã huỷ, hoặc không phải của khách |
| 422 | Tên miền không tồn tại hoặc đã kích hoạt | `PUT` vào tên miền không còn chờ |
| 422 | Thiếu city (… các trường) | thiếu trường bắt buộc |
| 422 | Trường state không hợp lệ | giá trị không phải chuỗi hoặc dài quá 255 ký tự |
| 422 | Hộ kinh doanh cần thông tin chủ hộ (owner) | hộ kinh doanh thiếu `owner` |
| 422 | Không dùng được chủ thể của tên miền #N | `from_domain_id` không phải tên miền đang chạy của khách |