API Xác Thực & Định Dạng Số Điện Thoại là gì?

API Xác Thực & Định Dạng Số Điện Thoại là một công cụ giúp bạn xác thực, định dạng và phân tích số điện thoại từ khắp nơi trên thế giới. API này có thể chuyển đổi số điện thoại sang định dạng chuẩn E.164 và xác định các siêu dữ liệu như vùng/quốc gia, loại số (di động/cố định), tính hợp lệ và nhiều thông tin khác.

API Xác Thực Số Điện Thoại dùng để làm gì?

API này dùng để kiểm tra số điện thoại có hợp lệ hay không, định dạng cho sử dụng quốc tế, nhận diện loại số (ví dụ: di động, VoIP), phát hiện thông tin vùng/quốc gia, và đảm bảo dữ liệu số điện thoại nhập vào luôn chuẩn hóa cho CRM, công cụ marketing, hoặc đăng ký người dùng.

API hỗ trợ những định dạng nào?

API chấp nhận số điện thoại theo nhiều định dạng như quốc gia, quốc tế hoặc E.164. Nó sẽ tự động nhận diện và chuẩn hóa về định dạng đúng.

API có thể phát hiện loại số điện thoại không?

Có. API trả về trường numberType cho biết số đó là MOBILE, FIXED_LINE, VOIP, v.v.

API trả về kiểu phản hồi nào?

Một phản hồi thành công bao gồm trạng thái, các biến thể số đã định dạng (quốc gia, quốc tế, E.164), thông tin vùng, loại số, số tín dụng đã dùng và nhiều thông tin khác. Xem phần Ví Dụ Phản Hồi API để biết chi tiết.

Tôi nên gửi API key như thế nào?

Với yêu cầu GET, bạn thêm API key vào URL dưới dạng ?key=YOUR_API_KEY. Với yêu cầu POST, gửi API key dưới dạng Bearer token trong header: 'Authorization: Bearer YOUR_API_KEY'.

Nếu tôi nhận được phản hồi status: false thì sao?

Điều này có nghĩa là yêu cầu không thành công. Trường message sẽ chỉ ra lý do lỗi chi tiết, như thiếu tham số, số điện thoại không hợp lệ, hoặc hết tín dụng.

Tôi có thể sử dụng địa chỉ ở nhiều định dạng hoặc ngôn ngữ khác nhau không?

Có. Ngoài mã quốc gia ISO 3166-1 alpha-2 (như US, DE, TR), tham số address còn chấp nhận tên quốc gia hoặc tên thành phố — thậm chí bằng ngôn ngữ khác. API sử dụng AI tích hợp để tự động nhận diện và ánh xạ đến quốc gia hoặc vùng phù hợp. Ví dụ: address=Deutschland, address=États-Unis, address=İstanbul, address=New York, address=Estados Unidos.

API Xác Thực và Định Dạng Số Điện Thoại

Q: API hỗ trợ bao nhiêu quốc gia?

API hỗ trợ số điện thoại từ 242 quốc gia và vùng lãnh thổ trên toàn cầu. Điều này đảm bảo khả năng sử dụng toàn cầu cho mọi ứng dụng quốc tế hoặc khu vực.

Q: Sự khác biệt giữa isValid và isPossible là gì?

isValid nghĩa là số đó đã được cấp chính thức và tuân thủ các quy tắc vùng. isPossible kiểm tra xem số đó về mặt cấu trúc có thể tồn tại hay không, ngay cả khi chưa được cấp phát.

API Xác Thực Số Điện Thoại được hỗ trợ tại 242 quốc gia.

API Xác Thực và Định Dạng Số Điện Thoại cho phép bạn dễ dàng xử lý các số điện thoại do người dùng nhập vào với nhiều định dạng khác nhau. Dù đầu vào có bất thường như 1(212)-867-53-09, +1 212 8675309, 001-212.867.5309, hoặc đơn giản là 2128675309, API của chúng tôi sẽ thông minh phát hiện cấu trúc và trả về phiên bản chuẩn hóa.

Công cụ này tự động chuyển đổi đầu vào thành định dạng E.164, định dạng quốc tế được công nhận toàn cầu cho các số điện thoại. Ví dụ, +1 212 867 5309 sẽ được trả về dưới dạng +12128675309, làm cho nó phù hợp với các hệ thống gọi quốc tế và các tích hợp.

Ngoài việc định dạng, API còn cung cấp khả năng xác thực số điện thoại chi tiết. Nó kiểm tra xem số điện thoại có isValid: true hay không — có nghĩa là nó là số hợp lệ theo các kế hoạch số quốc gia. Nó cũng cung cấp kiểm tra isPossible: true, cho biết liệu một số có thể tồn tại hay không ngay cả khi nó chưa được cấp phát. Điều này rất hữu ích cho việc xác thực trước khi lưu hoặc xử lý.

Tham số numberType giúp xác định liệu số điện thoại là số di động, điện thoại cố định hay VoIP. Điều này đặc biệt hữu ích trong các tình huống mà bạn chỉ muốn cho phép số di động cho việc xác minh SMS hoặc số cố định cho các liên hệ văn phòng.

Với hỗ trợ nhận diện mã vùng, API cũng có thể phát hiện nguồn gốc địa lý của số điện thoại. Ví dụ, một số bắt đầu với mã vùng 212 sẽ tự động được ánh xạ đến New York City (Manhattan). Tính năng này rất lý tưởng cho các ứng dụng yêu cầu phân đoạn hoặc phân tích dựa trên vị trí.

Mỗi số điện thoại cũng được liên kết với các metadata cấp quốc gia chi tiết, chẳng hạn như mã vùng ISO (ví dụ, US) và mã quốc gia số (ví dụ, 1), cho phép logic và định dạng hiển thị theo khu vực trong các ứng dụng của bạn.

✅ Phản Hồi API

Ví dụ về phản hồi JSON:

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country":"United States",
  "national": "(212) 867-5309",
  "international": "+1 212-867-5309",
  "e164": "+12128675309",
  "isValid": true,
  "isPossible": true,
  "numberType": "FIXED_LINE_OR_MOBILE",
  "nationalSignificantNumber": "2128675309",
  "rawInput": "+1 212 867 5309",
  "isGeographical": true,
  "areaCode": "212",
  "location": "New York City (Manhattan)"
}

Đang tải...

Tài khoản của bạn đã hết tín dụng. Đăng ký và nhận 200 tín dụng miễn phí.

Đăng ký miễn phí

Thử API Xác Thực Số Điện Thoại Ngay

Cách Sử Dụng Cơ Bản

Gửi một số điện thoại tới endpoint sau:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309

Bạn có thể nhận API key miễn phí hàng ngày với 200 tín dụng từ liên kết này.

Tham Số Địa Chỉ

API cũng hỗ trợ tham số address tùy chọn, rất hữu ích trong trường hợp số điện thoại được cung cấp không có mã quốc gia quốc tế. Trường này giúp hệ thống phát hiện khu vực dự định và phân tích đúng số điện thoại. Ví dụ, nếu số điện thoại đầu vào là 2128675309 và không có mã quốc gia, việc đặt address=US, address=United States, hoặc thậm chí address=New York sẽ giúp API xác định số điện thoại thuộc về United States.

Tham số address chấp nhận đầu vào theo nhiều định dạng, bao gồm:

Mã ISO 3166-1 alpha-2 như US, DE, hoặc TR
Tên quốc gia như Germany, Turkey, hoặc America
Tên thành phố hoặc khu vực như Berlin, Istanbul, hoặc New York

Mặc dù tùy chọn, address trở thành bắt buộc nếu số điện thoại không bắt đầu bằng dấu cộng và mã gọi quốc tế (ví dụ, +1, +44, +90). Nếu không có thông tin ngữ cảnh này, API có thể không thể diễn giải đúng định dạng số quốc gia.

Ví dụ với tham số địa chỉ:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309&address=US

Các Trường Phản Hồi

Trường	Loại	Mô Tả
status	Boolean	`true` nếu yêu cầu thành công.
remaining_credits	Số Nguyên	Số tín dụng API còn lại sau yêu cầu này.
expires	Số Nguyên (thời gian dấu vết)	Thời gian hết hạn tín dụng theo định dạng UNIX (giây).
duration	Chuỗi	Thời gian xử lý yêu cầu (ví dụ: `308ms`).
regionCode	Chuỗi	Mã vùng ISO 3166-1 alpha-2 của quốc gia phát hiện được (ví dụ: `US`).
countryCode	Số Nguyên	Mã gọi quốc tế của quốc gia (ví dụ: `1` cho Mỹ).
country	Chuỗi	Tên đầy đủ của quốc gia ở định dạng dễ đọc (ví dụ: United States).
national	Chuỗi	Phiên bản số điện thoại quốc gia đã được định dạng (ví dụ: `(212) 867–5309`).
international	Chuỗi	Phiên bản quốc tế đã được định dạng (ví dụ: `+1 212–867–5309`).
e164	Chuỗi	Số điện thoại ở định dạng E.164 (ví dụ: `+12128675309`).
isValid	Boolean	`true` nếu số điện thoại hợp lệ theo quy định vùng.
isPossible	Boolean	`true` nếu số có cấu trúc hợp lệ và có thể tồn tại, ngay cả khi chưa được cấp phát.
numberType	Enum[Chuỗi]	Loại số điện thoại. Các giá trị có thể: `FIXED_LINE`, `MOBILE`, `FIXED_LINE_OR_MOBILE`, v.v.
nationalSignificantNumber	Chuỗi	Số điện thoại quốc gia đầy đủ mà không có mã quốc gia (ví dụ: `2128675309`).
rawInput	Chuỗi	Số điện thoại gốc mà người dùng nhập vào trong yêu cầu API.
isGeographical	Boolean	`true` nếu số điện thoại có thể liên kết với một khu vực địa lý (ví dụ: số điện thoại cố định).
areaCode	Chuỗi	Mã vùng của số điện thoại (ví dụ: `212`).
location	Chuỗi	Vị trí địa lý liên kết với mã vùng (ví dụ: `New York City (Manhattan)`).

Các Giá Trị Loại Số

Loại	Mô Tả
FIXED_LINE	Số điện thoại cố định chuẩn liên kết với một vị trí địa lý.
MOBILE	Số di động có thể nhận cuộc gọi và tin nhắn SMS.
FIXED_LINE_OR_MOBILE	Số điện thoại có thể là số cố định hoặc số di động. Sự phân biệt không rõ ràng trong kế hoạch phân bổ số.
TOLL_FREE	Số điện thoại miễn phí, nơi người nhận chịu chi phí, ví dụ: số 800 ở Mỹ.
PREMIUM_RATE	Số điện thoại có giá cước cao, thường dùng cho các dịch vụ giải trí hoặc thông tin.
SHARED_COST	Số điện thoại có chi phí được chia sẻ giữa người gọi và người nhận.
VOIP	Số điện thoại sử dụng công nghệ Voice over IP, phục vụ cho các dịch vụ điện thoại qua Internet như Skype hoặc Google Voice.
PERSONAL_NUMBER	Số điện thoại cá nhân có thể chuyển hướng đến bất kỳ số điện thoại nào do người dùng chọn.
PAGER	Số máy nhắn tin được sử dụng để thông báo dạng văn bản (hiện nay phần lớn đã lỗi thời).
UAN	Số liên lạc phổ quát, thường được các doanh nghiệp sử dụng làm điểm liên hệ duy nhất.
VOICEMAIL	Số điện thoại dành riêng cho dịch vụ hộp thư thoại.
UNKNOWN	Không thể xác định loại số điện thoại.

⚠️ Cảnh báo: Nếu giá trị đầu vào của bạn bao gồm khoảng trắng hoặc ký tự đặc biệt (như dấu + trong số điện thoại hoặc khoảng trắng trong tên quốc gia), luôn luôn mã hóa URL chúng trước khi thực hiện yêu cầu GET. Nếu không, yêu cầu của bạn có thể thất bại hoặc các tham số có thể bị hiểu sai.

❌ Ví dụ (sai):

curl "https://api.genderapi.io/api/phone?number=+49 151 12345678&address=United States&key=YOUR_API_KEY"

✅ Sử dụng đúng (mã hóa URL):

curl "https://api.genderapi.io/api/phone?number=%2B49%20151%2012345678&address=United%20States&key=YOUR_API_KEY"

Bạn cũng có thể sử dụng các hàm mã hóa URL có sẵn trong ngôn ngữ lập trình của bạn để mã hóa các tham số trước khi gửi.

API Xác Thực Số Điện Thoại qua Yêu Cầu POST

Bạn có thể sử dụng phương thức POST để xác thực số điện thoại của Hoa Kỳ. Chỉ cần cung cấp số điện thoại theo định dạng E.164, quốc gia, hoặc quốc tế cùng với quốc gia/địa chỉ. API key của bạn phải được gửi dưới dạng Bearer token.

Ví Dụ với cURL

curl -X POST "https://api.genderapi.io/api/phone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number": "+12128675309", "address": "US"}'

Ví Dụ PHP cURL

<?php
$url = "https://api.genderapi.io/api/phone";

$data = array(
    "number" => "+12128675309",
    "address" => "US"
);

$payload = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authorization: Bearer YOUR_API_KEY"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Ví Dụ JavaScript fetch

fetch("https://api.genderapi.io/api/phone", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    number: "+12128675309",
    address: "United States"
  })
})
.then(response => response.json())
.then(data => console.log(data));

Ví Dụ Python requests

import requests

url = "https://api.genderapi.io/api/phone"

payload = {
    "number": "+12128675309",
    "address": "United States"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())

Thư Viện Client

Để việc tích hợp trở nên dễ dàng hơn, chúng tôi cung cấp một loạt các thư viện client chính thức và hỗ trợ cộng đồng cho các ngôn ngữ lập trình khác nhau. Những thư viện này cho phép bạn tương tác với các điểm cuối của GenderAPI — như API Xác Thực Số Điện Thoại — mà không cần phải xử lý thủ công các yêu cầu HTTP hoặc phân tích JSON. Chỉ cần chọn thư viện phù hợp cho môi trường của bạn, cài đặt nó và bắt đầu gửi yêu cầu với thiết lập tối thiểu.

Bạn có thể tìm thấy các thư viện client có sẵn và hướng dẫn cài đặt tại trang sau:
https://www.genderapi.io/vi/docs-client-libraries

Các Câu Hỏi Thường Gặp (FAQ)

1. API Xác Thực và Định Dạng Số Điện Thoại là gì?

API Xác Thực và Định Dạng Số Điện Thoại là một công cụ cho phép bạn xác thực, định dạng và phân tích số điện thoại từ khắp nơi trên thế giới. Nó có thể chuyển đổi số điện thoại thành định dạng E.164 chuẩn và xác định các siêu dữ liệu như khu vực, loại số (di động/cố định), tính hợp lệ và nhiều hơn nữa.

2. API Xác Thực Số Điện Thoại được sử dụng để làm gì?

Nó được sử dụng để kiểm tra xem số điện thoại có hợp lệ không, định dạng nó cho việc sử dụng quốc tế, xác định loại số (ví dụ: di động, VoIP), phát hiện siêu dữ liệu theo khu vực, và đảm bảo đầu vào số điện thoại sạch sẽ và chuẩn hóa cho CRM, công cụ marketing, hoặc đăng ký người dùng.

3. API hỗ trợ bao nhiêu quốc gia?

API hỗ trợ số điện thoại từ 242 quốc gia và lãnh thổ trên toàn cầu. Điều này đảm bảo sự bao phủ toàn cầu cho bất kỳ ứng dụng quốc tế hay khu vực nào.

4. Các định dạng nào được hỗ trợ?

API chấp nhận số điện thoại theo các định dạng như quốc gia, quốc tế hoặc E.164. Nó tự động phát hiện và chuẩn hóa chúng thành định dạng đúng.

5. Điều gì xảy ra nếu tôi bỏ qua tham số quốc gia hoặc địa chỉ?

Nếu số điện thoại không bắt đầu bằng dấu '+' và không có quốc gia/địa chỉ được cung cấp, API có thể không thể diễn giải đúng số điện thoại. Việc bao gồm tham số address (như US, United States, hoặc New York) là khuyến nghị.

6. API có thể phát hiện loại số không?

Có. API trả về trường numberType cho biết liệu số điện thoại có phải là MOBILE, FIXED_LINE, VOIP, v.v.

7. Sự khác biệt giữa `isValid` và `isPossible` là gì?

isValid có nghĩa là số điện thoại đã được cấp chính thức và phù hợp với tất cả các quy tắc vùng. isPossible kiểm tra xem số điện thoại có thể tồn tại lý thuyết không dựa trên cấu trúc của nó, ngay cả khi nó chưa được cấp phát.

8. API trả về loại phản hồi nào?

Một phản hồi thành công bao gồm trạng thái, các biến thể số đã được định dạng (quốc gia, quốc tế, E.164), dữ liệu khu vực, loại số, việc sử dụng tín dụng và nhiều hơn nữa. Xem phần ví dụ phản hồi API để có một ví dụ đầy đủ.

9. Làm thế nào để tôi gửi API key?

Đối với yêu cầu GET, bạn thêm API key vào như ?key=YOUR_API_KEY. Đối với yêu cầu POST, sử dụng Bearer token trong header như sau:
"Authorization: Bearer YOUR_API_KEY".

10. Nếu tôi thấy phản hồi `status: false` thì sao?

Điều này có nghĩa là yêu cầu đã thất bại. Trường message sẽ bao gồm lý do lỗi chi tiết như thiếu tham số, số điện thoại không hợp lệ, hoặc tín dụng không đủ.

11. Có cho phép ký tự đặc biệt hoặc khoảng trắng trong đầu vào không?

Có, nhưng chúng phải được mã hóa URL đối với yêu cầu GET. Ví dụ, sử dụng %20 thay vì khoảng trắng. Xem phần cảnh báo phía trên để biết cách sử dụng đúng.

12. Tôi có thể sử dụng địa chỉ với các định dạng hoặc ngôn ngữ khác nhau không?

Có. Ngoài các mã ISO 3166-1 alpha-2 (như US, DE, TR), tham số address còn chấp nhận tên quốc gia đầy đủ hoặc tên thành phố — thậm chí trong các ngôn ngữ khác nhau. API sử dụng AI tích hợp để thông minh phát hiện và diễn giải đúng quốc gia hoặc khu vực. Ví dụ:

address=Deutschland
address=États-Unis
address=İstanbul
address=New York
address=Estados Unidos

Tất cả các đầu vào này sẽ được API ánh xạ đúng đến quốc gia hoặc khu vực tương ứng mà không gặp vấn đề gì.