BKNS Whois API

REST API tra cứu thông tin WHOIS và kiểm tra khả dụng tên miền.
Hỗ trợ 1.260+ TLD · Dữ liệu .vn từ VNNIC chính thức · Độ trễ < 200ms

Tất cả request qua HTTPS. Phản hồi JSON, encoding UTF-8.

Xác thực

Đính kèm API key vào header X-API-Key trong mọi request. Thiếu key hoặc key sai → HTTP 401.

GET /api/v1/whois?domain=bkns.vn
X-API-Key: bkns_dmo_2376da23bd44858c8390aeeb93065404d21ede1ba2c5d59c0cffc33d6e83c2dd
Content-Type: application/json

X-API-Key: bkns_dmo_2376da23bd44858c8390aeeb93065404d21ede1ba2c5d59c0cffc33d6e83c2dd

Rate Limits

Giới hạn request theo tier. Vượt ngưỡng → 429 Too Many Requests kèm header Retry-After.

X-RateLimit-Limit:     300
X-RateLimit-Remaining:  0
X-RateLimit-Reset:      1711234567
Retry-After:           15

Mã lỗi

So sánh error envelope: v1 và v2

v1 (legacy) trả lỗi dạng phẳng với errorCode. v2 (standard) bọc lỗi trong object error kèm mã BKNS-WHOIS-NNN, message song ngữ, và correlation_id để tra cứu.

{
  "errorCode": "INVALID_DOMAIN",
  "message": "Invalid domain name",
  "statusCode": 400
}

Bảng mã lỗi v2 — BKNS-WHOIS-001 … 014

Mỗi lỗi v2 có mã BKNS-WHOIS-NNN cố định kèm HTTP status tương ứng. Trường error.details.legacyCode (khi có) là mã v1 tương đương, dùng để bắc cầu trong lúc chuyển tiếp — mã này sẽ được gỡ bỏ khi mọi consumer đã đọc error.code.

API v2 & Nâng cấp

BKNS Whois API hiện phục vụ song song hai phiên bản trên cùng một gateway. Chọn phiên bản phù hợp với tích hợp của bạn — không có yêu cầu bắt buộc chuyển đổi.

Hướng dẫn nâng cấp v1 → v2

1. 1

   Bước 1 — Đổi base URL

   Đổi /api/v1 thành /api/v2. Response thành công giữ nguyên 100% — cùng field, cùng cấu trúc phẳng, không bọc trong wrapper success/data — không cần sửa code xử lý phần thành công.

2. 2

   Bước 2 — Cập nhật xử lý lỗi

   Đọc error.code (ví dụ BKNS-WHOIS-001) thay vì errorCode ở cấp cao nhất, và error.message / error.messageEn thay vì message. Dùng bảng mã lỗi ở mục Mã lỗi để map; trong lúc chuyển tiếp, error.details.legacyCode vẫn giữ mã cũ nên bạn có thể so khớp cả hai.

3. 3

   Bước 3 — Request nghiêm ngặt (strict)

   v2 từ chối ngay bất kỳ field query/body lạ nào ngay từ request đầu tiên — trả 400 BKNS-WHOIS-002, không có thời gian ân hạn. Chỉ gửi các tham số đã tài liệu hóa: domain, raw, bypass_cache (bulk: domains). Xóa mọi tham số thừa trước khi chuyển sang v2.

4. 4

   Bước 4 — Mọi thứ khác giữ nguyên

   Xác thực (X-API-Key), rate limit theo tier, và các giá trị status (pending | registered | available | reserved | auction) giống hệt nhau giữa v1 và v2. v2 dùng chung ngân sách rate-limit với v1 — chuyển bề mặt không reset quota của bạn.

GETWHOIS Lookup

Tra cứu thông tin WHOIS đầy đủ: chủ sở hữu, nhà đăng ký, ngày tạo/hết hạn, nameserver, trạng thái EPP.

Cũng khả dụng tại /api/v2/whois với error envelope chuẩn hóa (v2) — xem hướng dẫn nâng cấp v1 → v2

{
  "domain": "bkns.vn",
  "tld": "vn",
  "status": "registered",
  "cached": true,
  "cacheTtlRemaining": null,
  "data": {
    "registrant": {
      "name": "Công ty Cổ phần Giải pháp Mạng Bạch Kim"
    },
    "registrar": {
      "name": "Công ty cổ phần giải pháp mạng Bạch Kim"
    },
    "nameservers": ["ns1.bkdns.vn", "ns2.bkdns.vn", "ns3.bkdns.vn"],
    "dates": {
      "created": "2010-06-24T17:00:00.000Z",
      "updated": null,
      "expiry": "2030-06-24T17:00:00.000Z",
      "renewalDeadline": null
    },
    "domainStatus": ["clientTransferProhibited"],
    "dnssec": false
  }
}

GETDomain Check

Kiểm tra nhanh tên miền còn khả dụng hay không. Nhanh hơn WHOIS vì chỉ trả về trạng thái.

Cũng khả dụng tại /api/v2/domain/check với error envelope chuẩn hóa (v2) — xem hướng dẫn nâng cấp v1 → v2

{
  "domain": "example-notexist.vn",
  "tld": "vn",
  "available": true,
  "premium": false,
  "cached": false
}

// congchung.vn — reserved
{ "domain": "congchung.vn", "available": false, "reserved": true, "reservedBy": "Cục CNTT – Bộ Tư pháp" }

// bk.vn — auction-only (.vn 1–2 ký tự)
{ "domain": "bk.vn", "available": false, "auction": true }

POSTBulk WHOIS

Tra cứu nhiều tên miền trong một request. Tối đa 20 domain/request. Yêu cầu tier Partner.

Lưu ý: Bulk WHOIS yêu cầu key Partner — demo key trả về 403 trên endpoint này.

Cũng khả dụng tại /api/v2/whois/bulk với error envelope chuẩn hóa (v2) — xem hướng dẫn nâng cấp v1 → v2

{
  "domains": ["bkns.vn", "google.com", "example.org"]
}

{
  "results": [
    { "domain": "bkns.vn",     "status": "registered", "data": { ... } },
    { "domain": "example.org", "status": "available" }
  ],
  "total": 3,
  "queryTime": 512
}

Response Schema

Cấu trúc đầy đủ của object WHOIS trả về.

Top-level fields

data object (chỉ khi registered)

TLD hỗ trợ

1.260+ loại TLD bao gồm tất cả ccTLD, gTLD phổ biến và new gTLD.

Code mẫu

WHOIS Lookup

const domain = 'bkns.vn';
const apiKey = 'bkns_dmo_2376da23bd44858c8390aeeb93065404d21ede1ba2c5d59c0cffc33d6e83c2dd';

const res = await fetch(
  `https://whois.bkns.vn/api/v1/whois?domain=${domain}`,
  { headers: { 'X-API-Key': apiKey } }
);

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();

// Always check status before accessing data.*
if (data.status === 'registered') {
  console.log('Registrar:', data.data.registrar.name);
  console.log('Expires: ', data.data.dates.expiry);
  console.log('Nameservers:', data.data.nameservers.join(', '));
} else {
  console.log('Domain is not registered.');
}

Xử lý 429 — Retry với backoff

async function whoisWithRetry(domain, apiKey, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(
      `https://whois.bkns.vn/api/v1/whois?domain=${domain}`,
      { headers: { 'X-API-Key': apiKey } }
    );
    if (res.status === 429) {
      const wait = Number(res.headers.get('Retry-After') ?? 5) * 1000;
      await new Promise(r => setTimeout(r, wait));
      continue;
    }
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.json();
  }
}

Ví dụ v2 — endpoint & error envelope

Endpoint /api/v2/whois dùng chung tham số với v1 (domain, raw, bypass_cache), nhưng lỗi trả về theo error envelope chuẩn hóa — xem mục Mã lỗi để biết bảng mã đầy đủ.

curl -s \
  "https://whois.bkns.vn/api/v2/whois?domain=bkns.vn" \
  -H "X-API-Key: bkns_dmo_2376da23bd44858c8390aeeb93065404d21ede1ba2c5d59c0cffc33d6e83c2dd" \
  | python3 -m json.tool

{
  "success": false,
  "error": {
    "code": "BKNS-WHOIS-001",
    "message": "Tên miền không hợp lệ",
    "messageEn": "Invalid domain name",
    "details": { "legacyCode": "INVALID_DOMAIN" },
    "correlation_id": "01J8Z3K9QW7M2P5RXT6VYB4NDA"
  }
}

Liên hệ

Cần hỗ trợ kỹ thuật hoặc muốn đăng ký API key Partner?