इंटीग्रेशन गाइड

शुरुआत

एक मिनट में

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_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{"address": {"street": "1 Rue de Paris", "city": "Saint-Denis", "state": "RE", "zip": "97400", "country": "RE"}}'

सभी उदाहरणों में sk_live_YOUR_KEY की जगह अपनी कुंजी रखें।

अभी खाता नहीं है? पता निःशुल्क जाँचकर देखें: पृष्ठ कुछ सहेजता नहीं और ठीक वही दिखाता है जो 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, 2 अक्षर)
}}

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 ou 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. 401API कुंजी अज्ञात

   आपकी ओर से सुधार

   कुंजी अधूरी है, रद्द हो चुकी है (नई बनाई गई) या किसी दूसरी सेवा की है। एनवायरनमेंट वेरिएबल ठीक करें। लूप में बार-बार कोशिश न करें।

   नहीं: कुंजी ठीक करें

3. 402इस माह का कोटा खत्म, या कोई मान्य भुगतान नहीं

   सीमा या भुगतान

   उत्तर का बॉडी पढ़ें: वह बताता है कि दोनों में से कौन-सा मामला है। कोटे वाला 402 खराबी नहीं है।

   बॉडी के अनुसार

   {"reason": "quota_atteint"}उपयोग की सीमा पूरी हुई। यह खराबी नहीं है। काउंटर माह की 1 तारीख़ (UTC) को फिर शुरू होता है।

   {"x402Version": 1}इस कॉल का भुगतान नहीं आया। कीमत फ़ील्ड accepts में है।

4. 403खाता समाप्त

   आपकी ओर से सुधार

   निःशुल्क ट्रायल खत्म हो गया है और खाता ट्रायल प्लान पर ही रह गया है। सशुल्क प्लान पर जाएँ: कुछ भी अपने आप नहीं कटता।

   नहीं: प्लान बदलें

5. 422अनुरोध का रूप गलत

   आपकी ओर से सुधार

   कोई फ़ील्ड गायब या खाली है। street, city, state और zip अनिवार्य हैं; country का डिफ़ॉल्ट US है।

   सुधार के बाद

6. 429निःशुल्क प्रयासों की सीमा पूरी हुई

   सीमा

   यह /validate-form यानी बिना खाते के ट्रायल पर लागू होता है, सशुल्क API पर नहीं। Retry-After में बताई अवधि तक रुकें, या खाता बनाएँ।

   Retry-After के बाद

7. 500भुगतान लिया गया, पर रजिस्टर तक पहुँच नहीं

   सेवा की ओर की समस्या

   सेवा ऐसा वैलिडेशन देने से इनकार करती है जिसे वह दर्ज नहीं कर सकती। फिर कोशिश करें। कॉल का भुगतान हुआ था तो transaction_id बताएँ: मिलान हाथ से किया जाता है।

   हाँ, transaction_id सँभालकर रखें

8. 503ग्राहक खाते या डेटाबेस तक पहुँच नहीं

   सेवा की ओर की समस्या

   कुंजी की जाँच नहीं हो सकी (यह अस्वीकृति नहीं है), या डेटाबेस जवाब नहीं दे रहा। कुछ मिनट बाद फिर कोशिश करें: कुछ भी खर्च नहीं हुआ।

   503 कभी भुगतान की माँग नहीं होता।

   हाँ, कुछ मिनट बाद

बिलिंग

जिसका दोबारा भुगतान नहीं होता, और जिसकी सीमा है

विषयक्या होता हैआप क्या करें

कैश (निर्णय)

एक ही सामान्यीकृत पता 30 दिन तक प्रदाता से दोबारा नहीं पूछा जाता। इसकी गारंटी cache_key देता है।

करेंएक ही सवाल का दो बार भुगतान होने की चिंता किए बिना कॉल करें। नई कॉल के लिए पता बदलें: API अंदाज़ा नहीं लगाती।

कैश (डिग्रेडेड)

degraded नतीजा 5 मिनट रखा जाता है, 30 दिन नहीं: «प्रदाता ने उत्तर नहीं दिया» कोई निर्णय नहीं है।

करेंdegraded: true को «बाद में फिर कोशिश करें» मानें। इस छोटी अवधि के बाद वही कॉल असली उत्तर पाती है।

कोटा

मासिक, UTC कैलेंडर माह के अनुसार: वह माह की 1 तारीख़ को फिर शुरू होता है, आपकी पहली कॉल के 30 दिन बाद नहीं।

करेंX-Quota-Remaining पर नज़र रखें। सीमा के बाद नहीं, उससे पहले हमें लिखें।

प्रति कॉल कीमत

वसूल किए गए हर वैलिडेशन पर 0.02 USDC (x402 मोड)। सब्सक्रिप्शन से कवर कॉल में price_paid: 0.0 आता है।

करेंभुगतान करने वाला एजेंट 402 का बॉडी (accepts) पढ़ता है: कीमत वहीं रहती है, उसका अंदाज़ा कभी नहीं लगाना पड़ता।

बिना खाते का ट्रायल

/validate-form पर हर दिन, हर विज़िटर के लिए 10 वैलिडेशन।

करेंनियमित उपयोग के लिए खाता बनाएँ: 100 वैलिडेशन निःशुल्क, फिर मासिक प्लान।

उदाहरण

व्यावहारिक उदाहरण

API जोड़ने के चार तरीके। हर उदाहरण कुंजी को एनवायरनमेंट वेरिएबल से पढ़ता है।

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 खराबी नहीं है: वह एक सीमा है, और उत्तर में ही पढ़ी जा सकती है।

डेवलपर और AI एजेंट

खाते के बिना, प्रति कॉल भुगतान

स्वायत्त एजेंट को न खाते की ज़रूरत है, न कुंजी की। हर वसूल किया गया वैलिडेशन 0.02 USDC का है, जो Base नेटवर्क पर x402 से चुकाया जाता है।

1. 1POST /validate को कॉल करें, सामान्य बॉडी के साथ। भुगतान के बिना उत्तर 402 होता है, जिसके बॉडी में {"x402Version": 1} और फ़ील्ड accepts होते हैं: कीमत वहीं है।
2. 2प्राधिकरण पर हस्ताक्षर करें। accepts से EIP-3009 प्राधिकरण बनाएँ और अनुरोध हेडर X-PAYMENT के साथ दोबारा भेजें।
3. 3उत्तर पढ़ें। X-Payment-Mode का मान x402 है, price_paid USDC में कीमत देता है, और transaction_id वह संदर्भ है जिसे 500 की स्थिति में बताना है।

आपके एजेंटों के लिए सब कुछ बिना भुगतान के खोजा जा सकता है:

• /mcpMCP सर्वर, टूल validate_address, डिस्कवरी निःशुल्क
• /manifestएजेंट के पढ़ने लायक x402 विवरण
• /llms.txtसर्च इंजन और एजेंट के लिए संक्षिप्त सार
• /AGENTS.mdआपके एजेंटों के लिए निर्देश
• /docsइंटरैक्टिव दस्तावेज़ (OpenAPI, आज़माने योग्य)

इंटीग्रेट करने से पहले जानें

सीमाएँ

अमेरिका अनुकूलित

प्रदाता अमेरिका के पतों के लिए अनुकूलित है: मानकीकृत पता, निर्देशांक, डिलीवरी योग्यता और भरोसा स्कोर।

फ़्रांस और विदेशी विभाग सत्यापित (BAN)

फ़्रांस और विदेशी विभागों के पते राष्ट्रीय पता आधार (BAN) से जाँचे जाते हैं: स्कोर, पिन कोड और शहर मेल खाने चाहिए। बाकी देशों की जाँच आंशिक रहती है।

degraded: true दोबारा जाँचें

प्रदाता ने उत्तर नहीं दिया। यह उत्तर पते के बारे में कुछ नहीं कहता: यह अस्वीकृति नहीं है। बाद में फिर चलाएँ।

इंटीग्रेशन

न कोई Shopify ऐप, न कोई WooCommerce एक्सटेंशन: कॉल आपकी अपनी सेवा से जाती है।