دليل التكامل

البداية

في دقيقة واحدة

1. احصل على مفتاح. أنشئ حسابًا: 14 يومًا و100 عملية تحقق مجانًا، دون بطاقة بنكية. يظهر المفتاح (sk_live_…) مرة واحدة فقط. بعد ذلك، يمكن إعادة إنشائه من حساب العميل.
2. استدعِ POST /validate مع المفتاح في الترويسة X-API-Key.
3. اقرأ النتيجة: العنوان بصيغة موحّدة، وقابلية التسليم، والإحداثيات، والقيمة cache_key.

curl -sS https://kder-ai.com/validate \
  -H "X-API-Key: sk_live_مفتاحك" \
  -H "content-type: application/json" \
  -d '{"address": {"street": "1 Rue de Paris", "city": "Saint-Denis", "state": "RE", "zip": "97400", "country": "RE"}}'

في كل الأمثلة، استبدل sk_live_مفتاحك بمفتاحك.

ليس لديك حساب بعد؟ اختبر عنوانًا مجانًا: الصفحة لا تحفظ شيئًا، وتعرض لك بالضبط ما تعيده واجهة API.

الوصول

المصادقة

مدخلان، ورد واحد. لا يتغير إلا الترويسة المرسلة وطريقة الدفع.

لا تضع المفتاح أبدًا في مستودع git أو في ملف مشترك أو في عنوان URL. مكانه متغير بيئة أو مدير أسرار، ولا ينتقل إلا عبر https. المفتاح المسرَّب يُعاد إنشاؤه بنقرة: يتوقف القديم عن العمل فورًا.

مرجع

عقد الواجهة

الطلب

POST https://kder-ai.com/validate، متن بصيغة JSON، والترويسة content-type: application/json.

{"address": {
   "street": "1 Rue de Paris",   // إلزامي
   "city": "Saint-Denis",        // إلزامي
   "state": "RE",                // إلزامي (المنطقة أو الولاية)
   "zip": "97400",               // إلزامي
   "country": "RE"               // اختياري، والقيمة الافتراضية "US" (رمز ISO من حرفين)
}}

الرد 200

{
  "result": {
    "validated": true,
    "standardized": {"line1": "1 RUE DE PARIS", "line2": "", "city": "SAINT-DENIS",
                     "state": "RE", "zip": "97400", "country": "RE"},
    "latitude": -20.8823, "longitude": 55.4504,
    "deliverability": "residential",
    "confidence": 0.99,
    "degraded": false,
    "cache_key": "9b7a..."
  },
  "price_paid": 0.0,
  "transaction_id": null
}

الحقلما يعنيه

validated

تعرّف المزوّد على العنوان. القيمة false ليست حكمًا في كل الأحوال: اقرأ degraded قبل أن تستنتج شيئًا.

deliverability

residential أو commercial أو unknown أو invalid: رمز المزوّد، مترجمًا بلغة واضحة.

confidence

مؤشر بين 0 و1: مؤشر، لا ضمان. اختر عتبتك حسب نسبة المرتجعات التي تقبلها.

degraded

true: لم يستجب المزوّد (عطل، أو تجاوز المهلة، أو قاطع دائرة مفتوح). الرد لا يقول شيئًا عن العنوان. لا تسجّله أبدًا على أنه «عنوان غير صالح».

price_paid

0.0 لاستدعاء مشمول باشتراك؛ والسعر بعملة USDC لاستدعاء مدفوع.

cache_key

اسم مستعار للعنوان (SHA-256). يُستخدم لذاكرة التخزين المؤقت ولأي طلب حذف. احتفظ به: لا يحتوي على العنوان.

ترويسات الرد

هذه هي الترويسات التي يضعها المسار فعلًا. لا نعِد بغيرها.

الترويسةالمحتوى

X-Payment-Mode

api_key أو x402: طريقة دفع الاستدعاء.

X-Plan

trial أو starter أو pro أو enterprise. في وضع المفتاح فقط.

X-Quota-Remaining

عمليات التحقق المتبقية هذا الشهر. إذا غابت فالباقة غير محدودة: غيابها يعني «دون سقف».

مرجع

رموز الاستجابة، وما يجب فعله

ثمانية رموز ممكنة على /validate. حالات الرفض الثلاث في وضع المفتاح (401 و402 و403) منفصلة عن قصد: عالج كل واحدة منها بطريقتها.

1. 200تمّت عملية التحقق

   نجاح

   اقرأ result. احتفظ بالقيمة cache_key: إنها الاسم المستعار لهذا العنوان، وتُستخدم لطلب الحذف.

   لا حاجة إلى إعادة المحاولة

2. 401مفتاح API غير معروف

   يُصحَّح من جهتك

   المفتاح ناقص، أو ملغى (أُعيد إنشاؤه)، أو مخصص لخدمة أخرى. صحّح متغير البيئة. لا تُعِد المحاولة في حلقة.

   لا: صحّح المفتاح

3. 402استُهلكت حصة الشهر، أو لا يوجد دفع صالح

   حدّ أو دفع

   اقرأ متن الرد: يحدد أيّ الحالتين تنطبق. الرمز 402 الخاص بالحصة ليس عطلًا.

   حسب المتن

   {"reason": "quota_atteint"}بلغت سقف الاستخدام. هذا ليس عطلًا. يبدأ العدّاد من جديد في اليوم الأول من الشهر (UTC).

   {"x402Version": 1}الدفع مفقود لهذا الاستدعاء. السعر موجود في الحقل accepts.

4. 403حساب منتهي الصلاحية

   يُصحَّح من جهتك

   انتهت التجربة المجانية وبقي الحساب على باقة التجربة. انتقل إلى باقة مدفوعة: لا يُخصم أي مبلغ تلقائيًا.

   لا: غيّر الباقة

5. 422طلب غير سليم الصياغة

   يُصحَّح من جهتك

   حقل مفقود أو فارغ. الحقول street وcity وstate وzip إلزامية؛ والقيمة الافتراضية للحقل country هي US.

   بعد التصحيح

6. 429بلغت الحد الأقصى للتجارب المجانية

   حدّ

   يخص /validate-form، أي التجربة دون حساب، لا الواجهة المدفوعة. انتظر المهلة المعلنة في Retry-After، أو أنشئ حسابًا.

   بعد Retry-After

7. 500حُصِّل الدفع، لكن تعذّر الوصول إلى السجل

   عطل من جهة الخدمة

   ترفض الخدمة تقديم عملية تحقق لا تستطيع تسجيلها. أعد المحاولة. إن كان الاستدعاء مدفوعًا، فاذكر transaction_id: تتم المطابقة يدويًا.

   نعم، مع حفظ transaction_id

8. 503تعذّر الوصول إلى حسابات العملاء أو قاعدة البيانات

   عطل من جهة الخدمة

   تعذّر التحقق من المفتاح (وهذا ليس رفضًا)، أو أن قاعدة البيانات لا تستجيب. أعد المحاولة بعد بضع دقائق: لم يُستهلك شيء.

   الرمز 503 ليس طلب دفع أبدًا.

   نعم، بعد بضع دقائق

الفوترة

ما لا تدفعه مرتين، وما له سقف

الموضوعما يحدثما تفعله

التخزين المؤقت (حكم)

العنوان الموحَّد نفسه لا يُعاد الاستعلام عنه لدى المزوّد طوال 30 يومًا. يضمن ذلك cache_key.

ما تفعلهاستدعِ دون خوف من دفع ثمن السؤال نفسه مرتين. لفرض استدعاء جديد، غيّر العنوان: الواجهة لا تخمّن.

التخزين المؤقت (منقوص)

النتيجة degraded تُحفظ 5 دقائق، لا 30 يومًا: «لم يستجب المزوّد» ليس حكمًا.

ما تفعلهتعامل مع degraded: true على أنها «أعد المحاولة لاحقًا». بعد هذه النافذة القصيرة، يحصل الاستدعاء نفسه على رد حقيقي.

الحصة

شهرية، على الشهر التقويمي بتوقيت UTC: تبدأ من جديد في اليوم الأول من الشهر، لا بعد 30 يومًا من أول استدعاء لك.

ما تفعلهراقب X-Quota-Remaining. راسلنا قبل بلوغ الحد لا بعده.

السعر لكل استدعاء

0.02 USDC لكل عملية تحقق محصَّلة (وضع x402). والاستدعاء المشمول باشتراك يعرض price_paid: 0.0.

ما تفعلهالوكيل الذي يدفع يقرأ متن 402 (accepts): السعر مذكور فيه، ولا حاجة إلى تخمينه أبدًا.

التجربة دون حساب

10 عمليات تحقق يوميًا لكل زائر على /validate-form.

ما تفعلهللاستخدام المنتظم، أنشئ حسابًا: 100 عملية تحقق مجانية، ثم باقة شهرية.

أمثلة

حالات عملية

أربع طرق لربط الواجهة. كل مثال يقرأ المفتاح من متغير بيئة.

1. الاستدعاء المباشر (PowerShell)

$cle = $env:ADDRESS_VALIDATOR_KEY
$corps = '{"address":{"street":"1 Rue de Paris","city":"Saint-Denis","state":"RE","zip":"97400","country":"RE"}}'
$r = Invoke-WebRequest -Uri https://kder-ai.com/validate -Method POST `
     -Headers @{ "X-API-Key" = $cle } -ContentType "application/json" -Body $corps
$r.StatusCode
$r.Headers["X-Payment-Mode"], $r.Headers["X-Plan"], $r.Headers["X-Quota-Remaining"]
($r.Content | ConvertFrom-Json).result

2. استيراد CSV (Python)

"""يتحقق من ملف CSV للعناوين ويكتب النتيجة بجانب كل سطر.

لا يُستعلَم لدى المزوّد إلا مرة واحدة لكل عنوان: يُحفَظ الرد
في ذاكرة التخزين المؤقت (30 يومًا للحكم)، لذا فإن تشغيلًا ثانيًا
على الملف نفسه لا يكلّف شيئًا إضافيًا.
"""
import csv
import os
import time

import requests

CLE = os.environ["ADDRESS_VALIDATOR_KEY"]  # لا تضعه أبدًا في الشيفرة ولا في git
API = "https://kder-ai.com/validate"

with open("colis.csv", newline="", encoding="utf-8") as source, open(
    "colis-verifies.csv", "w", newline="", encoding="utf-8"
) as cible:
    lecteur = csv.DictReader(source)
    champs = list(lecteur.fieldnames) + [
        "validated", "deliverability", "degraded", "note",
    ]
    sortie = csv.DictWriter(cible, fieldnames=champs)
    sortie.writeheader()
    for ligne in lecteur:
        reponse = requests.post(
            API,
            headers={"X-API-Key": CLE},
            timeout=30,
            json={
                "address": {
                    "street": ligne["adresse"],
                    "city": ligne["ville"],
                    "state": ligne["region"],
                    "zip": ligne["code_postal"],
                    "country": ligne.get("pays") or "US",
                }
            },
        )
        if reponse.status_code in (500, 503):
            time.sleep(5)  # عطل من جهة الخدمة: لم يُستهلك شيء
            continue
        if reponse.status_code == 429:
            time.sleep(int(reponse.headers.get("Retry-After", "60")))
            continue
        if reponse.status_code != 200:
            sortie.writerow({**ligne, "note": f"refus {reponse.status_code}"})
            continue
        resultat = reponse.json()["result"]
        sortie.writerow(
            {
                **ligne,
                "validated": resultat["validated"],
                "deliverability": resultat["deliverability"],
                "degraded": resultat["degraded"],
                "note": "a reverifier (fournisseur injoignable)"
                if resultat["degraded"]
                else "",
            }
        )

ما يوضّحه المثال، ولا شيء غيره: المفتاح يأتي من متغير بيئة، والرمز 429 محترَم (المهلة تُقرأ ولا تُخمَّن)، والنتيجة degraded تُعلَّم «لإعادة التحقق» بدل تسجيلها كعنوان غير صالح.

3. Shopify

الخطوةما تربطه

المُشغِّل

خطاف ويب orders/create (أو خطوة تجهيز الطرد لديك) يستدعي خدمتك، التي تستعلم /validate بعنوان التسليم الخاص بالطلب.

مطابقة الحقول

• shipping_address.address1 ← street (أضف address2 إلى line2 من جهة النتيجة)
• city ← city
• province_code ← state
• zip ← zip
• country_code ← country

القرار

validated: false: علّم الطلب في لوحة الإدارة قبل الشحن. degraded: true: لا توقف شيئًا، وأعد جدولة فحص.

ما لا نقدّمه

لا يوجد تطبيق Shopify جاهز للتثبيت: الاستدعاء يأتي من خدمتك.

4. WooCommerce

الخطوةما تربطه

المُشغِّل

الإجراء woocommerce_checkout_order_processed (طلب مدفوع)، أو مهمة cron تمر على الطلبات قيد التجهيز (wc_get_orders( ['status' => 'processing'] )).

مطابقة الحقول

• $order->get_shipping_address_1() ← street
• $order->get_shipping_city() ← city
• $order->get_shipping_state() ← state
• $order->get_shipping_postcode() ← zip
• $order->get_shipping_country() ← country

التتبّع

سجّل cache_key مع الطلب: إنه المعرّف الوحيد للعنوان الصالح لطلب الحذف.

ما لا نقدّمه

لا توجد إضافة WooCommerce: الاستدعاء يأتي من خدمتك.

في كل الحالات: استدعاء واحد لكل عنوان ولكل طلب، وليس أبدًا داخل حلقة تتجاهل رموز الاستجابة. الرمز 402 الخاص بالحصة ليس عطلًا: إنه حدّ، ويُقرأ في الرد.

المطورون ووكلاء الذكاء الاصطناعي

الدفع لكل استدعاء، دون حساب

لا يحتاج الوكيل المستقل إلى حساب ولا إلى مفتاح. كل عملية تحقق محصَّلة تكلّف 0.02 USDC، تُدفع عبر x402 على شبكة Base.

1. 1استدعِ POST /validate بالمتن المعتاد. دون دفع، يكون الرد 402 ويحمل متنه {"x402Version": 1} والحقل accepts: السعر مذكور فيه.
2. 2وقّع التفويض. ابنِ تفويض EIP-3009 انطلاقًا من accepts، وأعد إرسال الطلب مع الترويسة X-PAYMENT.
3. 3اقرأ الرد. قيمة X-Payment-Mode هي x402، ويعطي price_paid السعر بعملة USDC، وtransaction_id هو المرجع الذي تذكره في حال 500.

لوكلائك، كل شيء قابل للاستكشاف دون دفع:

• /mcpخادم MCP، والأداة validate_address، والاستكشاف مجاني
• /manifestوصف x402 يقرؤه الوكيل
• /llms.txtملخص قصير لمحركات البحث والوكلاء
• /AGENTS.mdتعليمات لوكلائك
• /docsتوثيق تفاعلي (OpenAPI، قابل للتجربة)

ما يجب معرفته قبل التكامل

الحدود

الولايات المتحدة مُحسَّن

المزوّد مُحسَّن لعناوين الولايات المتحدة: عنوان بصيغة موحّدة، وإحداثيات، وقابلية التسليم، ومؤشر ثقة.

فرنسا وأقاليم ما وراء البحر مُتحقَّق (BAN)

تُتحقَّق العناوين الفرنسية وعناوين أقاليم ما وراء البحر عبر قاعدة العناوين الوطنية (BAN): يجب أن يتطابق المؤشر والرمز البريدي والمدينة. أما بقية الدول فيبقى التحقق فيها جزئيًا.

degraded: true أعد التحقق

لم يستجب المزوّد. الرد لا يقول شيئًا عن العنوان: إنه ليس رفضًا. أعد المحاولة لاحقًا.

التكاملات

لا تطبيق Shopify ولا إضافة WooCommerce: الاستدعاء ينطلق من خدمتك أنت.