集成指南

快速开始

一分钟上手

获取密钥。创建账户：免费试用 14 天，100 次验证，无需信用卡。密钥（sk_live_…）只显示一次。之后可在客户中心重新生成。
调用 POST /validate，并把密钥放在请求头 X-API-Key 中。
读取结果：标准化地址、可送达性、坐标，以及 cache_key。

POST/validatecurl

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 的返回内容。

访问方式

身份验证

两种接入方式，同样的响应。只有发送的请求头和付费方式不同。

网店

您发送: X-API-Key: sk_live_…，即注册时显示的密钥，或在客户中心重新生成的密钥。
您支付: 您套餐的月度额度。调用时不会收取任何费用。

按次付费 · x402

自主智能体

您发送: X-PAYMENT：根据 402 响应正文（accepts 字段）构造并签名的 EIP-3009 授权。
您支付: 每次收费的验证 0.02 USDC。

密钥优先。如果两个请求头同时发送，以订阅为准：账户已覆盖的调用绝不会收取 USDC。每个响应都会在 X-Payment-Mode 中说明本次调用是如何付费的。

切勿把密钥放进 git 仓库、共享文件或 URL。密钥应保存在环境变量或密钥管理工具中，并且只通过 https 传输。密钥一旦泄露，一键即可重新生成：旧密钥会立即失效。

参考

接口约定

请求

POST https://kder-ai.com/validate，JSON 正文，请求头 content-type: application/json。

请求正文JSON

{"address": {
   "street": "1 Rue de Paris",   // 必填
   "city": "Saint-Denis",        // 必填
   "state": "RE",                // 必填（地区或州）
   "zip": "97400",               // 必填
   "country": "RE"               // 可选，默认为 "US"（ISO 2 位字母）
}}

`200` 响应

200 OKJSON

{
  "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）是有意区分的：请分别处理。

已完成

200

读取结果。

需在您这边修正

401 403 422

不做任何修改就重试，没有用。

限额或付款

402 429

不是故障：响应正文或 Retry-After 会告诉您该怎么做。

服务端故障

500 503

请重试。绝不是付款请求。

200验证已完成
成功

读取 result。请保存 cache_key：它是该地址的假名标识，可用于申请删除。

无需重试
401API 密钥未知
需在您这边修正

密钥不完整、已被撤销（已重新生成），或属于其他服务。请修正环境变量。不要循环重试。

否：请修正密钥
402本月额度已用完，或没有有效付款
限额或付款

请读取响应正文：它会说明属于哪种情况。因额度产生的 402 不是故障。

视响应正文而定

{"reason": "quota_atteint"}已达到用量上限。这不是故障。计数器每月 1 日（UTC）重置。

{"x402Version": 1}本次调用缺少付款。价格在 accepts 字段中。
403账户已过期
需在您这边修正

免费试用已结束，账户仍停留在试用套餐。请升级到付费套餐：不会自动扣款。

否：请更换套餐
422请求格式错误
需在您这边修正

某个字段缺失或为空。street、city、state 和 zip 为必填；country 默认为 US。

修正后再试
429已达免费测试上限
限额

适用于 /validate-form，即无需账户的测试，而不是付费 API。请等待 Retry-After 中给出的时间，或创建账户。

Retry-After 之后
500已收款，但无法访问记录库
服务端故障

服务拒绝返回无法记录的验证结果。请重试。如果该调用已付款，请提供 transaction_id：我们会手动对账。

是，请保存 transaction_id
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）

POST/validatePowerShell

$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）

verifier_colis.pyPython

"""核对地址 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 结果会标记为“需重新验证”，而不是写成无效地址。

没有 Shopify 应用，也没有 WooCommerce 插件。您的网店无需安装任何东西：API 就是接口约定，调用从您自己的服务发出。这样您就可以自行设定置信度阈值。

3. Shopify

触发条件: orders/create webhook（或您的包裹备货环节）调用您的服务，由您的服务带着订单的收货地址请求 /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 动作（订单已付款），或遍历备货中订单的定时任务（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 与订单一起保存：它是申请删除时唯一有效的地址标识。
Ce que nous ne fournissons pas: 没有 WooCommerce 插件：调用来自您自己的服务。

无论哪种情况：每个地址、每个订单只调用一次，绝不要放进忽略状态码的循环里。因额度产生的 402 不是故障，而是一项限制，响应里会写明。

开发者与 AI 智能体

按次付费，无需账户

自主智能体既不需要账户，也不需要密钥。每次收费的验证为 0.02 USDC，通过 x402 在 Base 网络上支付。

1调用 POST /validate，正文与平常相同。未付款时，响应为 402，其正文包含 {"x402Version": 1} 和 accepts 字段：价格就在其中。
2签署授权。根据 accepts 构造 EIP-3009 授权，并带上请求头 X-PAYMENT 重新发送请求。
3读取响应。X-Payment-Mode 为 x402，price_paid 给出以 USDC 计的价格，transaction_id 是遇到 500 时需要提供的凭据。

您的智能体可以免费发现以下全部内容：

集成之前请了解

限制

美国已优化: 服务商针对美国地址优化：标准化地址、坐标、可送达性和置信度。
法国及海外省已核验（BAN）: 法国及海外省地址由国家地址库（BAN）核验：评分、邮编和城市必须一致。其他国家仍为部分验证。
degraded: true 需重新验证: 服务商没有响应。该响应不说明地址本身的任何情况，也不是拒绝。请稍后重试。
集成: 没有 Shopify 应用，也没有 WooCommerce 插件：调用从您自己的服务发出。

我们保存什么，不保存什么。对于付费调用或订阅调用：保存地址的指纹（cache_key）和处理结果，绝不保存地址本身。对于无需账户的免费测试：什么都不保存，只有一个匿名计数器用来执行上限。删除请求通过 cache_key 提出。

开始动手

创建账户以获取密钥，或先无需账户测试一个地址。

创建账户查看价格测试地址

一分钟上手

身份验证

网店

自主智能体

接口约定

请求

200 响应

响应头

状态码，以及该怎么处理

200验证已完成

401API 密钥未知

402本月额度已用完，或没有有效付款

403账户已过期

422请求格式错误

429已达免费测试上限

500已收款，但无法访问记录库

503无法访问客户账户或数据库