# التحقق من صحة الهاتف وتنسيقه باستخدام API v2

> التحقق من صحة أرقام الهواتف الدولية أو الوطنية وتنسيقها باستخدام GenderAPI v2. راجع سياق الدولة المطلوبة وحقول JSON ورسوم الائتمان الواحد.

Canonical HTML: https://www.genderapi.io/ar/docs/v2/phone-validation

Last reviewed: 2026-09-25

## التحقق من صحة رقم الهاتف وتهيئته

يقبل POST /phone/validate number وحقل country الاختياري. استخدم رقم هاتف دولي يبدأ بـ +. للحصول على رقم هاتف وطني، قم بتوفير رمز البلد ISO الكبير. تحتوي الاستجابة على valid وpossible وe164 وcountry وcountry_calling_code داخل data، بالإضافة إلى كائن meta المشترك. يؤدي هذا إلى التحقق من بنية رقم الهاتف، وليس ما إذا كان المشترك موجودًا أم لا. تبلغ تكلفة كل عملية تحقق مكتملة رصيدًا واحدًا، بما في ذلك النتائج غير الصالحة. تُظهر الاستجابة التوضيحية أدناه رقمًا غير صالح وهي مستقلة عن مثال الطلب.

قم بتشغيل هذه الأمثلة على الخادم الخاص بك. قم بتعيين GENDERAPI_API_KEY في بيئة العملية على مفتاح API الموجود لديك. تأكد من أن meta.access.mode هو api_key: يمكن أن يعود المفتاح غير المعروف إلى النسخة التجريبية من IP.

كل طلب تنبؤ هو عملية جديدة قابلة للفوترة، بما في ذلك إعادة المحاولة. لا تقوم هذه الأمثلة بإعادة المحاولة تلقائيًا. التحقق من حالة الفواتير قبل إرسال طلب آخر.

تحافظ استجابات HTTP 4xx و5xx JSON على نص الخطأ وترجع حالة خروج غير صفرية. تحقق من code وaction وmeta.usage.billing_status قبل إعادة المحاولة.

| الحقل JSON | النوع | القاعدة |
| --- | --- | --- |
| number | string | مطلوب، 3–32 حرفًا. ASCII أرقام ومسافات وأقواس وواصلات، مع بادئة + اختيارية. لا يتم قبول الامتدادات والأحرف الأبجدية. |
| country | string | رمز ISO 3166-1 alpha-2 بأحرف لاتينية كبيرة. مطلوب للرقم المحلي واختياري عندما تبدأ قيمة number بالرمز +. احذف الحقل إذا لم تكن بحاجة إليه. |

**cURL**

cURL 7.76+ في غلاف POSIX. قم بالتشغيل في جهازك الطرفي.

```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+; جلب مدمج. احفظ باسم example.mjs وقم بتشغيل 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+; مكتبة قياسية. احفظ باسم example.py وقم بتشغيل 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+ مع الامتداد cURL. احفظ باسم example.php وقم بتشغيل php example.php.

```php
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"number":"+905321234567"}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/phone/validate');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => '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+; عميل HTTP القياسي. احفظ باسم GenderApiExample.java وقم بتشغيل 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<String> 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**

تطبيق وحدة التحكم .NET 8+. استخدمه كـ Program.cs في مشروع وحدة التحكم، ثم قم بتشغيل 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+; مكتبة قياسية. احفظ باسم main.go وقم بتشغيل 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
    }
  }
}
```

## اقرأ حقول التحقق من صحة الهاتف

تم رفض الإدخال غير الصحيح باستخدام HTTP 422 قبل الفوترة. إذا كان تنسيق الطلب صحيحًا ولكن لا يمكن تحليل رقم الهاتف، فيمكن أن تقوم العملية بإرجاع HTTP 200 مع حقول التنسيق valid: false وnull. هذا التحقق المكتمل يكلف رصيدًا واحدًا. قد يظل الرقم الذي يمكن تحليله ولكنه غير صالح يحتوي على قيمة e164. تحقق من valid؛ الرقم المنسق وحده ليس دليلاً على الصلاحية.

| الحقل داخل data | معنى |
| --- | --- |
| valid | ما إذا كان الرقم يتطابق مع قواعد التحقق من صحة خطة الترقيم. |
| possible | ما إذا كان للرقم طول معقول لخطة الترقيم الخاصة به؛ أضعف من صالح. |
| e164 | الرقم المنسق الدولي عند نجاح التحليل، وإلا null. |
| country | المنطقة المشتقة من الرقم، أو null عندما لا تكون متاحة؛ ولا يحدد موقع المشترك. |
| country_calling_code | رمز الاتصال الدولي الرقمي، أو null في حالة عدم توفره. |

## المصادقة وإعادة المحاولة

أرسل مفتاح API الحالي الخاص بك باستخدام مصادقة Bearer ونوع المحتوى: application/json. تقرأ الأمثلة GENDERAPI_API_KEY من البيئة. الحقل country مطلوب لأرقام الهواتف الوطنية وهو اختياري عندما تبدأ قيمة number بـ +.

- [المصادقة](https://www.genderapi.io/ar/docs/v2/authentication)
- [الأخطاء وإعادة المحاولة](https://www.genderapi.io/ar/docs/v2/errors-and-retries)
- [الاعتمادات والاستخدام](https://www.genderapi.io/ar/docs/v2/credits-and-usage)