API cho doanh nghiệp

Tài liệu API who.com.vn

Đưa tra cứu tên miền, ngày hết hạn, vòng đời và bản ghi DNS vào hệ thống của anh/chị. Dữ liệu và cách xử lý giống hệt trang who.com.vn, trả về dạng JSON.

Đăng ký dùng API Tải OpenAPI (JSON)

Giới thiệu

Mọi endpoint dùng HTTPS, trả JSON mã hóa UTF-8 (riêng tra nhiều tên miền trả NDJSON và xuất file trả Excel/CSV). Ngày tháng theo lịch Việt Nam (YYYY-MM-DD), thời điểm theo chuẩn ISO 8601 UTC.

Thêm lang=vi hoặc lang=en vào đường dẫn để chọn ngôn ngữ của thông báo lỗi và nhãn vòng đời; mặc định theo header Accept-Language.

Địa chỉ gốc: https://who.com.vn/api/v1

GET/api/v1/whois— Tra cứu tên miền (whois)
GET/api/v1/lifecycle— Vòng đời tên miền
GET/api/v1/dns— Bản ghi DNS
POST/api/v1/whois/bulk— Tra nhiều tên miền
POST/api/v1/whois/export— Xuất file Excel / CSV

Xác thực

HVN cấp cho mỗi doanh nghiệp một khóa API dạng who_live_… sau khi duyệt yêu cầu. Khóa chỉ hiển thị một lần lúc cấp; HVN chỉ lưu bản băm nên không xem lại được — nếu mất, HVN sẽ cấp khóa mới.

Gửi khóa trong header Authorization theo kiểu Bearer:

Authorization

Authorization: Bearer who_live_••••••••••••••••••••••••••••••••

Hoặc dùng header X-API-Key:

X-API-Key

X-API-Key: who_live_••••••••••••••••••••••••••••••••

Chỉ gửi khóa qua header. Khóa đặt trên đường dẫn (query string) bị từ chối với lỗi key_in_query, vì đường dẫn dễ lọt vào nhật ký và header Referer.
Không nhúng khóa vào mã chạy trên trình duyệt hay ứng dụng di động. Gọi API từ máy chủ của anh/chị rồi trả kết quả cho người dùng.
Mỗi khóa chỉ dùng được các chức năng (phạm vi) đã cấp: whois, lifecycle, dns, bulk, export.
Khóa sai, đã thu hồi hoặc hết hạn nhận lỗi 401 invalid_api_key — không tự chuyển về hạn mức dùng chung. Nghi lộ khóa, hãy báo HVN để xoay khóa: khóa cũ hết hiệu lực ngay.

Không có khóa, API vẫn trả lời nhưng dùng chung hạn mức theo địa chỉ IP như người dùng trang web (xem mục Hạn mức).

Các endpoint

Tra cứu tên miền (whois)

GET/api/v1/whois· Phạm vi khóa: whois

Tình trạng, chủ sở hữu (tổ chức), nơi đăng ký, ngày đăng ký, ngày hết hạn, máy chủ tên miền, trạng thái EPP và dữ liệu gốc của một tên miền.

Tham số trên đường dẫn

Tham số	Bắt buộc	Mô tả
`domain`	Có	Tên miền, địa chỉ web hoặc tên không đuôi. Tên không đuôi (ví dụ hvn) được thử với các đuôi phổ biến cùng lúc và trả kind: "expand" kèm danh sách results.
`refresh`	Không	Đặt 1 để bỏ qua bản lưu tạm và tra lại từ nguồn.
`lang`	Không	Ngôn ngữ thông báo: vi hoặc en.

Ví dụ yêu cầu · curl

curl -s "https://who.com.vn/api/v1/whois?domain=hvn.vn" \
  -H "Authorization: Bearer $WHO_API_KEY"

Kết quả trả về · application/json

{
  "kind": "single",
  "domain": "hvn.vn",
  "unicode": "hvn.vn",
  "status": "registered",
  "unconfirmed": false,
  "registrant": {
    "type": "organization",
    "name": "Công ty Cổ phần Tập đoàn HVN"
  },
  "registrar": "Công ty TNHH P.A Việt Nam",
  "created_at": "2016-04-18",
  "expires_at": "2030-04-18",
  "updated_at": null,
  "registrar_expires_at": null,
  "nameservers": [
    "art.ns.cloudflare.com",
    "lily.ns.cloudflare.com"
  ],
  "epp_status": [
    "clientTransferProhibited"
  ],
  "dnssec": null,
  "raw": "hvn.vn : Record found !\nDomain : hvn.vn\nStatus : clientTransferProhibited\nIssue Date : 2016-04-18T00:00:00+07:00\nExpired Date : 2030-04-18T00:00:00+07:00\nRegistrar Name : Công ty TNHH P.A Việt Nam\nOwner Name : Công ty Cổ phần Tập đoàn HVN\nDNS : art.ns.cloudflare.com, lily.ns.cloudflare.com",
  "source": "netvn",
  "source_label": "whois.net.vn",
  "fetched_at": "2026-10-05T02:15:08.412Z",
  "cached": false,
  "stale": false,
  "days_left": 1291,
  "age_days": 3822
}

days_left và age_days tính theo ngày hôm nay ở Việt Nam. status là registered, available, unknown hoặc unsupported; unknown nghĩa là nguồn chưa trả lời chắc chắn — hãy thử lại sau, đừng coi là còn trống.

Vòng đời tên miền

GET/api/v1/lifecycle· Phạm vi khóa: lifecycle

Kết quả whois kèm các mốc sau ngày hết hạn (tạm ngừng, hạn cuối gia hạn, chuộc lại, thu hồi) theo quy định của nhóm đuôi tên miền.

Tham số trên đường dẫn

Tham số	Bắt buộc	Mô tả
`domain`	Có	Tên miền đầy đủ, ví dụ hvn.vn.
`lang`	Không	Ngôn ngữ nhãn các mốc: vi hoặc en.

Ví dụ yêu cầu · curl

curl -s "https://who.com.vn/api/v1/lifecycle?domain=hvn.vn" \
  -H "Authorization: Bearer $WHO_API_KEY"

Kết quả trả về · application/json

{
  "whois": {
    "kind": "single",
    "domain": "hvn.vn",
    "unicode": "hvn.vn",
    "status": "registered",
    "unconfirmed": false,
    "registrant": {
      "type": "organization",
      "name": "Công ty Cổ phần Tập đoàn HVN"
    },
    "registrar": "Công ty TNHH P.A Việt Nam",
    "created_at": "2016-04-18",
    "expires_at": "2030-04-18",
    "updated_at": null,
    "registrar_expires_at": null,
    "nameservers": [
      "art.ns.cloudflare.com",
      "lily.ns.cloudflare.com"
    ],
    "epp_status": [
      "clientTransferProhibited"
    ],
    "dnssec": null,
    "raw": "hvn.vn : Record found !\nDomain : hvn.vn\nStatus : clientTransferProhibited\nIssue Date : 2016-04-18T00:00:00+07:00\nExpired Date : 2030-04-18T00:00:00+07:00\nRegistrar Name : Công ty TNHH P.A Việt Nam\nOwner Name : Công ty Cổ phần Tập đoàn HVN\nDNS : art.ns.cloudflare.com, lily.ns.cloudflare.com",
    "source": "netvn",
    "source_label": "whois.net.vn",
    "fetched_at": "2026-10-05T02:15:08.412Z",
    "cached": false,
    "stale": false,
    "days_left": 1291,
    "age_days": 3822
  },
  "lifecycle": {
    "state": "registered",
    "groupId": "vn",
    "anchorDate": "2030-04-18",
    "anchorSource": "registry",
    "ageYears": 10,
    "daysLeft": 1291,
    "currentIndex": -1,
    "currentFromStatus": null,
    "milestones": [
      {
        "key": "suspended",
        "label": "Tạm ngừng hoạt động",
        "desc": "Website và email ngừng hoạt động; vẫn gia hạn được.",
        "period": "Vừa hết hạn",
        "date": "2030-04-19",
        "daysFromToday": 1292,
        "isProjected": true,
        "isCurrent": false
      },
      {
        "key": "renew_deadline",
        "label": "Hạn cuối gia hạn",
        "desc": "Sau mốc này không còn gia hạn được.",
        "period": "Tạm ngừng · chờ gia hạn",
        "date": "2030-05-18",
        "daysFromToday": 1321,
        "isProjected": true,
        "isCurrent": false
      },
      {
        "key": "released",
        "label": "Thu hồi",
        "desc": "Tên miền bị thu hồi và có thể được đăng ký lại.",
        "period": "Chờ thu hồi",
        "date": "2030-05-24",
        "daysFromToday": 1327,
        "isProjected": true,
        "isCurrent": false
      }
    ],
    "note": "Vòng đời mang tính tham khảo; các mốc sau hôm nay là dự kiến."
  }
}

Các mốc sau hôm nay mang tính dự kiến (isProjected: true).

Bản ghi DNS

GET/api/v1/dns· Phạm vi khóa: dns

Bản ghi DNS lấy trực tiếp từ máy chủ quản lý tên miền, so sánh với DNS công cộng, kèm nhận xét nhanh (nhà cung cấp email, DNS, SPF).

Tham số trên đường dẫn

Tham số	Bắt buộc	Mô tả
`domain`	Có	Tên miền hoặc tên miền con; một địa chỉ IP sẽ tra bản ghi PTR.
`types`	Không	Các loại bản ghi, cách nhau bởi dấu phẩy: A, AAAA, CNAME, MX, NS, TXT, SOA, CAA, SRV. Bỏ trống để lấy tất cả.
`lang`	Không	Ngôn ngữ thông báo lỗi: vi hoặc en.

Ví dụ yêu cầu · curl

curl -s "https://who.com.vn/api/v1/dns?domain=hvn.vn&types=A,MX,NS" \
  -H "Authorization: Bearer $WHO_API_KEY"

Kết quả trả về · application/json

{
  "host": "hvn.vn",
  "records": [
    {
      "host": "hvn.vn",
      "type": "A",
      "value": "103.124.95.203",
      "ttl": 300
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "aspmx.l.google.com",
      "ttl": 300,
      "priority": 10
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "alt1.aspmx.l.google.com",
      "ttl": 300,
      "priority": 20
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "alt2.aspmx.l.google.com",
      "ttl": 300,
      "priority": 20
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "aspmx2.googlemail.com",
      "ttl": 300,
      "priority": 30
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "aspmx3.googlemail.com",
      "ttl": 300,
      "priority": 30
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "aspmx4.googlemail.com",
      "ttl": 300,
      "priority": 30
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "aspmx5.googlemail.com",
      "ttl": 300,
      "priority": 30
    },
    {
      "host": "hvn.vn",
      "type": "NS",
      "value": "art.ns.cloudflare.com",
      "ttl": 86400
    },
    {
      "host": "hvn.vn",
      "type": "NS",
      "value": "lily.ns.cloudflare.com",
      "ttl": 86400
    }
  ],
  "source": "authoritative",
  "authoritativeServer": "art.ns.cloudflare.com",
  "authoritativeUnavailable": false,
  "diffs": [],
  "hints": {
    "mailProviders": [
      "Google Workspace"
    ],
    "dnsProviders": [
      "Cloudflare"
    ],
    "spf": null,
    "dmarc": null
  },
  "fetched_at": "2026-10-05T02:15:08.412Z",
  "cached": false
}

error.code (nếu có) là nxdomain, dns_failed hoặc private_ip; khi máy chủ quản lý không trả lời, source là public.

Tra nhiều tên miền

POST/api/v1/whois/bulk· Phạm vi khóa: bulk

Gửi một danh sách tên miền, nhận kết quả theo dòng ngay khi từng tên miền được kiểm tra xong.

Tham số trên đường dẫn

Tham số	Bắt buộc	Mô tả
`lang`	Không	Ngôn ngữ thông báo lỗi: vi hoặc en.

Nội dung JSON gửi lên

Trường	Bắt buộc	Mô tả
`domains`	Có	Mảng tên miền. Tên trùng được gộp, tên không hợp lệ được báo trong dòng meta; danh sách bị cắt ở số tối đa mỗi lần.

Ví dụ yêu cầu · curl

curl -s -X POST "https://who.com.vn/api/v1/whois/bulk" \
  -H "Authorization: Bearer $WHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":["hvn.vn","hvn.com.vn","hvn"]}'

Kết quả trả về · application/x-ndjson

{"type":"meta","total":2,"truncated":false,"domains":["hvn.vn","hvn.com.vn"],"invalid":[{"input":"hvn","code":"no_tld"}],"invalidCount":1}
{"type":"row","index":1,"input":"hvn.com.vn","result":{"kind":"single","domain":"hvn.com.vn","unicode":"hvn.com.vn","status":"registered","unconfirmed":false,"registrant":{"type":"organization","name":"Công ty Cổ phần Tập đoàn HVN"},"registrar":"Công ty TNHH P.A Việt Nam","created_at":"2019-04-26","expires_at":"2027-04-26","updated_at":null,"registrar_expires_at":null,"nameservers":["ns1.hkda.vn","ns2.hkda.vn","ns3.hkda.vn"],"epp_status":["clientTransferProhibited"],"dnssec":null,"raw":"hvn.com.vn : Record found !\nDomain : hvn.com.vn\nStatus : clientTransferProhibited\nIssue Date : 2019-04-26T00:00:00+07:00\nExpired Date : 2027-04-26T00:00:00+07:00\nRegistrar Name : Công ty TNHH P.A Việt Nam\nOwner Name : Công ty Cổ phần Tập đoàn HVN\nDNS : ns1.hkda.vn, ns2.hkda.vn, ns3.hkda.vn","source":"netvn","source_label":"whois.net.vn","fetched_at":"2026-10-05T02:15:08.412Z","cached":false,"stale":false,"days_left":203,"age_days":2719}}
{"type":"row","index":0,"input":"hvn.vn","result":{"kind":"single","domain":"hvn.vn","unicode":"hvn.vn","status":"registered","unconfirmed":false,"registrant":{"type":"organization","name":"Công ty Cổ phần Tập đoàn HVN"},"registrar":"Công ty TNHH P.A Việt Nam","created_at":"2016-04-18","expires_at":"2030-04-18","updated_at":null,"registrar_expires_at":null,"nameservers":["art.ns.cloudflare.com","lily.ns.cloudflare.com"],"epp_status":["clientTransferProhibited"],"dnssec":null,"raw":"hvn.vn : Record found !\nDomain : hvn.vn\nStatus : clientTransferProhibited\nIssue Date : 2016-04-18T00:00:00+07:00\nExpired Date : 2030-04-18T00:00:00+07:00\nRegistrar Name : Công ty TNHH P.A Việt Nam\nOwner Name : Công ty Cổ phần Tập đoàn HVN\nDNS : art.ns.cloudflare.com, lily.ns.cloudflare.com","source":"netvn","source_label":"whois.net.vn","fetched_at":"2026-10-05T02:15:08.412Z","cached":false,"stale":false,"days_left":1291,"age_days":3822}}
{"type":"done"}

Kết quả có Content-Type application/x-ndjson: mỗi dòng là một đối tượng JSON.
Dòng đầu type: "meta" cho biết số tên miền sẽ kiểm tra (domains theo thứ tự index) và các dòng không hợp lệ. Tiếp theo là một dòng type: "row" cho mỗi tên miền, theo thứ tự xong trước — dùng index để ghép; dòng row có result (như whois) hoặc error. Dòng cuối là type: "done".
Ngắt kết nối giữa chừng sẽ dừng các lượt tra còn lại.

Xuất file Excel / CSV

POST/api/v1/whois/export· Phạm vi khóa: export

Xuất kết quả whois đã có trong bộ nhớ tạm của danh sách tên miền ra file Excel hoặc CSV (tiếng Việt hiển thị đúng). Không kích hoạt lượt tra mới.

Tham số trên đường dẫn

Tham số	Bắt buộc	Mô tả
`lang`	Không	Ngôn ngữ tiêu đề cột: vi hoặc en.

Nội dung JSON gửi lên

Trường	Bắt buộc	Mô tả
`domains`	Có	Mảng tên miền, thường là danh sách vừa tra nhiều tên miền.
`format`	Có	xlsx hoặc csv.

Ví dụ yêu cầu · curl

curl -s -X POST "https://who.com.vn/api/v1/whois/export" \
  -H "Authorization: Bearer $WHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":["hvn.vn","hvn.com.vn"],"format":"xlsx"}' \
  -o who-com-vn.xlsx

Tên miền chưa được tra gần đây sẽ có dòng trống trong file — hãy gọi tra nhiều tên miền trước.

Mã lỗi

Lỗi trả về mã HTTP tương ứng và nội dung JSON gồm error (mã máy đọc), message (theo ngôn ngữ yêu cầu) và retryAfter (giây, nếu có). Cột thông báo dưới đây là nội dung API trả về.

Mã lỗi	HTTP	Thông báo
`key_in_query`	400	Không gửi khóa API trên đường dẫn; dùng header Authorization: Bearer <khóa>.
`invalid_api_key`	401	Khóa API không hợp lệ, đã bị thu hồi hoặc đã hết hạn.
`scope_denied`	403	Khóa API này không được dùng cho chức năng này.
`rate_limited`	429	Bạn tra cứu quá nhanh, vui lòng thử lại sau 60 giây.
`quota_exceeded`	429	Khóa API đã dùng hết hạn mức của tháng này. Liên hệ HVN để nâng hạn mức.
`bad_request`	400	Yêu cầu không hợp lệ.
`payload_too_large`	413	Dữ liệu gửi lên quá lớn.
`emptyinvalid_charslabel_too_longtoo_longunsupported_tldsuffix_onlyno_tldmultiple_domainsis_ipprivate_ip`	400	Tên miền nhập vào không hợp lệ; message giải thích lý do cụ thể.
`internal`	500	Hệ thống đang gặp sự cố, vui lòng thử lại sau.

Ví dụ lỗi

HTTP/2 401
www-authenticate: Bearer realm="who.com.vn"
content-type: application/json

{
  "error": "invalid_api_key",
  "message": "Khóa API không hợp lệ, đã bị thu hồi hoặc đã hết hạn."
}

Hạn mức

Hạn mức giữ cho nguồn dữ liệu dùng chung ổn định. Vượt hạn mức nhận 429 kèm header Retry-After.

Không có khóa (theo địa chỉ IP, đang áp dụng)

30 lượt tra mỗi phút (whois, vòng đời, DNS). Tên không đuôi thử 6 đuôi phổ biến nên tính 6 lượt.
Tra nhiều tên miền: 5 lần mỗi giờ, tối đa 25 tên miền mỗi lần.
Xuất file: 20 lần mỗi giờ.

Có khóa API

Lượt mỗi phút, lượt mỗi tháng, số lần tra nhiều tên miền mỗi giờ và số tên miền mỗi lần được đặt riêng cho từng khóa theo thỏa thuận với HVN.
Lượt tháng tính theo số tên miền đã tra (một lần tra nhiều tên miền tính theo số tên miền; một lần xuất file tính 1) và đặt lại vào ngày 1 hằng tháng theo giờ Việt Nam. Hết lượt tháng nhận 429 quota_exceeded.
Xuất file: 20 lần mỗi giờ cho mỗi khóa.

Header hạn mức

Khi một yêu cầu có khóa được tính lượt, phản hồi kèm các header sau (kể cả khi bị 429 rate_limited):

Header	Mô tả
`X-RateLimit-Limit`	Số lượt tối đa trong cửa sổ hiện tại (mỗi phút; với tra nhiều tên miền và xuất file là mỗi giờ).
`X-RateLimit-Remaining`	Số lượt còn lại trong cửa sổ hiện tại.
`X-RateLimit-Reset`	Số giây đến khi cửa sổ hiện tại kết thúc.
`X-Quota-Limit`	Lượt tháng của khóa.
`X-Quota-Remaining`	Lượt tháng còn lại.
`Retry-After`	Kèm lỗi 429: số giây nên chờ trước khi thử lại (quota_exceeded: đến đầu tháng sau theo giờ Việt Nam).
`WWW-Authenticate`	Kèm lỗi 401: Bearer realm="who.com.vn".

Dữ liệu cá nhân

API áp dụng cùng chính sách dữ liệu cá nhân với trang web (Nghị định 13/2023/NĐ-CP): với tên miền do cá nhân đứng tên, họ tên và thông tin liên hệ được ẩn theo mặc định — registrant.type là individual, registrant.name là null, và dữ liệu gốc (raw) đã được lược bỏ phần cá nhân. Tên tổ chức vẫn hiển thị.

Mỗi yêu cầu có khóa được ghi nhật ký theo khóa (không ghi tên miền của chủ thể cá nhân) để thống kê mức dùng.

Xem Chính sách dữ liệu

Đăng ký dùng API

Gửi thông tin bên dưới, đội ngũ HVN sẽ liên hệ để thống nhất hạn mức và cấp khóa. Hiện API chưa thu phí.

Liên hệ

Cần tư vấn tích hợp hoặc nâng hạn mức, anh/chị liên hệ HVN GROUP:

Hotline024.9999.7777 Emailkinhdoanh@hvn.vn