# Xác thực và định dạng điện thoại với API v2 > Xác thực và định dạng số điện thoại quốc tế hoặc quốc gia với GenderAPI v2. Xem bối cảnh quốc gia bắt buộc, các trường JSON và khoản phí một tín dụng. Canonical HTML: https://www.genderapi.io/vi/docs/v2/phone-validation Last reviewed: 2026-09-25 ## Xác thực và định dạng số điện thoại POST /phone/validate chấp nhận number và trường country tùy chọn. Sử dụng số điện thoại quốc tế bắt đầu bằng +. Đối với số điện thoại quốc gia, hãy cung cấp mã quốc gia ISO viết hoa. Phản hồi có valid, possible, e164, country và country_calling_code bên trong data, cùng với đối tượng meta được chia sẻ. Điều này kiểm tra cấu trúc của số điện thoại chứ không phải liệu thuê bao có tồn tại hay không. Mỗi lần xác thực hoàn thành tốn 1 tín dụng, bao gồm cả kết quả không hợp lệ. Phản hồi minh họa bên dưới hiển thị số không hợp lệ và độc lập với ví dụ về yêu cầu. Chạy các ví dụ này trên máy chủ của bạn. Đặt GENDERAPI_API_KEY trong môi trường quy trình thành khóa API hiện có của bạn. Xác nhận meta.access.mode là api_key: khóa không được nhận dạng có thể quay lại bản dùng thử IP. Mỗi yêu cầu dự đoán là một hoạt động mới có thể tính phí, bao gồm cả số lần thử lại. Những ví dụ này không tự động thử lại. Kiểm tra trạng thái thanh toán trước khi gửi yêu cầu khác. Phản hồi HTTP 4xx và 5xx JSON giữ nguyên phần thân lỗi và trả về trạng thái thoát khác 0. Kiểm tra code, action và meta.usage.billing_status trước khi thử lại. | Trường JSON | Loại | Quy tắc | | --- | --- | --- | | number | string | Bắt buộc, 3–32 ký tự. Các chữ số, dấu cách, dấu ngoặc đơn và dấu gạch nối ASCII với dấu + ở đầu tùy chọn. Phần mở rộng và ký tự chữ cái không được chấp nhận. | | country | string | Mã ISO 3166-1 alpha-2 viết hoa. Bắt buộc đối với số điện thoại quốc gia. Tùy chọn khi giá trị number bắt đầu bằng +. Bỏ qua trường này khi không cần thiết. | **cURL** cURL 7.76+ trong vỏ POSIX. Chạy trong terminal của bạn. ```bash curl --silent --show-error --fail-with-body --max-time 30 \ --request POST 'https://api.genderapi.io/api/v2/phone/validate' \ --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \ --header 'Content-Type: application/json' \ --data '{ "number": "+905321234567" }' ``` **JavaScript / Node.js** Node.js 22+; tìm nạp tích hợp. Lưu dưới dạng example.mjs và chạy node example.mjs. ```javascript // Server-side Node.js. Save as example.mjs. const apiKey = process.env.GENDERAPI_API_KEY; if (!apiKey) throw new Error("Set GENDERAPI_API_KEY"); const body = { "number": "+905321234567" }; const response = await fetch("https://api.genderapi.io/api/v2/phone/validate", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000), redirect: "error", }); const raw = await response.text(); if (!(response.headers.get("content-type") ?? "").includes("json")) { throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`); } const result = JSON.parse(raw); // Also accepts application/problem+json. if (!response.ok) { console.error(`HTTP ${response.status}`, result); process.exitCode = 1; // A retry is a new operation; inspect billing first. } else { console.log(JSON.stringify(result, null, 2)); // For batches, inspect every item: HTTP 200 may contain item errors. } ``` **Python** Python 3.10+; thư viện chuẩn. Lưu dưới dạng example.py và chạy python3 example.py. ```python import json import os import sys import urllib.error import urllib.request api_key = os.environ.get("GENDERAPI_API_KEY") if not api_key: raise RuntimeError("Set GENDERAPI_API_KEY") body = json.loads("{\"number\":\"+905321234567\"}") class NoRedirect(urllib.request.HTTPRedirectHandler): def redirect_request(self, req, fp, code, msg, headers, newurl): return None request = urllib.request.Request( "https://api.genderapi.io/api/v2/phone/validate", method="POST", data=json.dumps(body).encode("utf-8"), headers={ "Authorization": "Bearer " + api_key, "Content-Type": "application/json", }, ) opener = urllib.request.build_opener(NoRedirect()) try: response = opener.open(request, timeout=30) except urllib.error.HTTPError as error: response = error # Keep the Problem Details body on non-2xx responses. with response: status = response.status raw = response.read().decode("utf-8") if "json" not in response.headers.get("Content-Type", ""): raise RuntimeError(f"HTTP {status}: expected a JSON response") result = json.loads(raw) print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout) if not 200 <= status < 300: sys.exit(1) # Inspect code, action and billing before retrying. # For batches, inspect every item even when HTTP status is 200. ``` **PHP** PHP 8+ với phần mở rộng cURL. Lưu dưới dạng example.php và chạy php example.php. ```php 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_FOLLOWLOCATION => false, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $apiKey, 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR), ]); $raw = curl_exec($ch); if ($raw === false) { throw new RuntimeException(curl_error($ch)); } $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); $contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: ''; curl_close($ch); if (strpos($contentType, 'json') === false) { throw new RuntimeException("HTTP $status: expected a JSON response"); } $result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR); $output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL; if ($status < 200 || $status >= 300) { fwrite(STDERR, $output); // Preserve the Problem Details body. exit(1); } echo $output; // For batches, inspect every item; HTTP 200 can contain item errors. ``` **Java** Java 17+; máy khách HTTP tiêu chuẩn. Lưu dưới dạng GenderApiExample.java và chạy java GenderApiExample.java. ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.time.Duration; public class GenderApiExample { private static String requiredEnv(String name) { String value = System.getenv(name); if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name); return value; } public static void main(String[] args) throws Exception { String apiKey = requiredEnv("GENDERAPI_API_KEY"); String body = "{\"number\":\"+905321234567\"}"; HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .followRedirects(HttpClient.Redirect.NEVER) .build(); HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/phone/validate")) .timeout(Duration.ofSeconds(30)) .header("Authorization", "Bearer " + apiKey) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8)); if (!response.headers().firstValue("content-type").orElse("").contains("json")) { throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON"); } // JSON text; parse with your application's JSON library when integrating. if (response.statusCode() < 200 || response.statusCode() >= 300) { System.err.println(response.body()); // Includes Problem Details. System.exit(1); } System.out.println(response.body()); // For batches, inspect each item's data or error, including on HTTP 200. } } ``` **C# / .NET** Ứng dụng bảng điều khiển .NET 8+. Sử dụng làm Program.cs trong dự án bảng điều khiển, sau đó chạy dotnet run. ```csharp using System; using System.Net.Http; using System.Net.Http.Headers; using System.Text; using System.Text.Json; string RequiredEnv(string name) => !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name)) ? Environment.GetEnvironmentVariable(name)! : throw new InvalidOperationException($"Set {name}"); var apiKey = RequiredEnv("GENDERAPI_API_KEY"); using var handler = new HttpClientHandler { AllowAutoRedirect = false }; using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) }; using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/phone/validate"); request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey); request.Content = new StringContent("{\"number\":\"+905321234567\"}", Encoding.UTF8, "application/json"); using var response = await client.SendAsync(request); var raw = await response.Content.ReadAsStringAsync(); if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false)) throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON"); using var result = JsonDocument.Parse(raw); if (!response.IsSuccessStatusCode) { Console.Error.WriteLine(result.RootElement); // Preserve Problem Details. Environment.ExitCode = 1; } else { Console.WriteLine(result.RootElement); // For batches, inspect every item even on HTTP 200. } ``` **Go** Go 1.22+; thư viện chuẩn. Lưu dưới dạng main.go và chạy go run main.go. ```go package main import ( "encoding/json" "fmt" "io" "net/http" "os" "strings" "time" ) func requiredEnv(name string) string { value := os.Getenv(name) if value == "" { panic("Set " + name) } return value } func run() error { apiKey := requiredEnv("GENDERAPI_API_KEY") body := "{\"number\":\"+905321234567\"}" request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/phone/validate", strings.NewReader(body)) if err != nil { return err } request.Header.Set("Authorization", "Bearer " + apiKey) request.Header.Set("Content-Type", "application/json") client := &http.Client{ Timeout: 30 * time.Second, CheckRedirect: func(req *http.Request, via []*http.Request) error { return http.ErrUseLastResponse }, } response, err := client.Do(request) if err != nil { return err } defer response.Body.Close() raw, err := io.ReadAll(response.Body) if err != nil { return err } if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) { return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode) } if response.StatusCode < 200 || response.StatusCode >= 300 { return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw) } fmt.Println(string(raw)) // For batches, inspect every item even on HTTP 200. return nil } func main() { if err := run(); err != nil { fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling. os.Exit(1) } } ``` ```json { "data": { "valid": false, "possible": false, "e164": null, "country": null, "country_calling_code": null }, "meta": { "request_id": "11111111-1111-4111-8111-111111111111", "duration_ms": 12, "access": { "mode": "ip_trial", "reason": "api_key_missing" }, "usage": { "charged_credits": 1, "remaining_credits": 7, "billing_status": "confirmed", "resets_at": "2026-09-26T12:00:00.000Z", "limit": 10, "period_seconds": 86400 } } } ``` ## Đọc các trường xác thực điện thoại Đầu vào không đúng định dạng bị từ chối bằng HTTP 422 trước khi thanh toán. Nếu định dạng yêu cầu đúng nhưng không thể phân tích cú pháp số điện thoại, thao tác có thể trả về HTTP 200 với các trường định dạng valid: false và null. Việc xác thực hoàn thành này tốn 1 tín dụng. Một số có thể được phân tích cú pháp nhưng không hợp lệ vẫn có thể có giá trị e164. Kiểm tra valid; chỉ một số được định dạng không phải là bằng chứng hợp lệ. | Trường bên trong data | Ý nghĩa | | --- | --- | | valid | Số có khớp với quy tắc xác thực sơ đồ đánh số hay không. | | possible | Số đó có độ dài hợp lý cho sơ đồ đánh số của nó hay không; yếu hơn hợp lệ. | | e164 | Số được định dạng quốc tế khi phân tích cú pháp thành công, nếu không thì null. | | country | Vùng bắt nguồn từ số hoặc null khi không có sẵn; nó không định vị được người đăng ký. | | country_calling_code | Mã gọi quốc tế dạng số hoặc null khi không khả dụng. | ## Xác thực và thử lại Gửi khóa API hiện có của bạn bằng xác thực Bearer và Content-Type: application/json. Các ví dụ đọc GiớiAPI_API_KEY từ môi trường. Trường country là bắt buộc đối với số điện thoại quốc gia và tùy chọn khi giá trị number bắt đầu bằng +. - [Xác thực](https://www.genderapi.io/vi/docs/v2/authentication) - [Lỗi và thử lại](https://www.genderapi.io/vi/docs/v2/errors-and-retries) - [Tín dụng và cách sử dụng](https://www.genderapi.io/vi/docs/v2/credits-and-usage)