Guía de integración

Primeros pasos

En un minuto

Consigue una clave. Crea una cuenta: 14 días y 100 validaciones gratis, sin tarjeta de crédito. La clave (sk_live_…) se muestra una sola vez. Después, se regenera desde el área de cliente.
Llama a POST /validate con la clave en el encabezado X-API-Key.
Lee el resultado: dirección estandarizada, entregabilidad, coordenadas y cache_key.

POST/validatecurl

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

En todos los ejemplos, sustituye sk_live_TU_CLAVE por tu clave.

¿Aún no tienes cuenta? Prueba una dirección gratis: la página no guarda nada y te muestra exactamente lo que devuelve la API.

Acceso

Autenticación

Dos accesos, una sola respuesta. Solo cambian el encabezado enviado y el pago.

Suscripción

Una tienda

Envías: X-API-Key: sk_live_…, la clave que se muestra al registrarte, o regenerada en el área de cliente.
Pagas: La cuota mensual de tu plan. No se cobra nada por llamada.

Pago por llamada · x402

Un agente autónomo

Envías: X-PAYMENT: una autorización EIP-3009 firmada, construida a partir del cuerpo de la respuesta 402 (campo accepts).
Pagas: 0,02 USDC por validación cobrada.

La clave tiene prioridad. Si los dos encabezados se envían juntos, decide la suscripción: una llamada cubierta por una cuenta nunca se cobra en USDC. Cada respuesta indica cómo se pagó, en X-Payment-Mode.

Nunca pongas la clave en un repositorio git, un archivo compartido ni una URL. Vive en una variable de entorno o en un gestor de secretos, y solo circula por https. Una clave filtrada se regenera con un clic: la anterior deja de funcionar al instante.

Referencia

El contrato

Solicitud

POST https://kder-ai.com/validate, cuerpo JSON, encabezado content-type: application/json.

Cuerpo de la solicitudJSON

{"address": {
   "street": "1 Rue de Paris",   // obligatorio
   "city": "Saint-Denis",        // obligatorio
   "state": "RE",                // obligatorio (region o estado)
   "zip": "97400",               // obligatorio
   "country": "RE"               // opcional, "US" por defecto (ISO de 2 letras)
}}

Respuesta `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: El proveedor reconoció la dirección. false no siempre es un veredicto: lee degraded antes de sacar una conclusión.
deliverability: residential, commercial, unknown o invalid: el código del proveedor, traducido a lenguaje claro.
confidence: Índice entre 0 y 1: un índice, no una garantía. Elige tu umbral según la tasa de devoluciones que aceptes.
degraded: true: el proveedor no respondió (caída, tiempo de espera agotado, cortacircuitos abierto). La respuesta no dice nada de la dirección. No la registres nunca como «dirección inválida».
price_paid: 0.0 para una llamada cubierta por una suscripción; el precio en USDC para una llamada pagada.
cache_key: Seudónimo de la dirección (SHA-256). Sirve para la caché y para cualquier solicitud de eliminación. Guárdalo: no contiene la dirección.

Encabezados de respuesta

Son los encabezados que la ruta añade de verdad. No se promete ningún otro.

X-Payment-Mode: api_key o x402: cómo se pagó la llamada.
X-Plan: trial, starter, pro o enterprise. Solo en modo clave.
X-Quota-Remaining: Validaciones restantes este mes. Si falta: plan ilimitado, la ausencia significa «sin tope».

Referencia

Los códigos de respuesta y qué hacer

Ocho códigos posibles en /validate. Los tres rechazos del modo clave (401, 402, 403) son distintos a propósito: trata cada uno a su manera.

Atendido

200

Lee el resultado.

Por corregir de tu lado

401 403 422

Reintentar sin cambiar nada no sirve de nada.

Límite o pago

402 429

No es una caída: el cuerpo o Retry-After indica qué hacer.

Incidente del servicio

500 503

Reintenta. Nunca es una petición de pago.

200Validación atendida
Éxito

Lee result. Guarda cache_key: es tu seudónimo de esta dirección y sirve para pedir una eliminación.

Nada que reintentar
401Clave de API desconocida
Por corregir de tu lado

La clave está incompleta, revocada (regenerada) o es de otro servicio. Corrige la variable de entorno. No reintentes en bucle.

No: corrige la clave
402Cuota del mes agotada o ningún pago válido
Límite o pago

Lee el cuerpo de la respuesta: indica cuál de los dos casos se aplica. Un 402 de cuota no es una caída.

Según el cuerpo

{"reason": "quota_atteint"}Tope de uso alcanzado. No es una caída. El contador se reinicia el día 1 del mes (UTC).

{"x402Version": 1}Falta el pago de esta llamada. El precio está en el campo accepts.
403Cuenta caducada
Por corregir de tu lado

La prueba gratuita ha terminado y la cuenta sigue en el plan de prueba. Pasa a un plan de pago: no se cobra nada automáticamente.

No: cambia de plan
422Solicitud mal formada
Por corregir de tu lado

Falta un campo o está vacío. street, city, state y zip son obligatorios; country vale US por defecto.

Tras corregir
429Límite de pruebas gratuitas alcanzado
Límite

Afecta a /validate-form, la prueba sin cuenta, no a la API de pago. Espera el plazo indicado en Retry-After o crea una cuenta.

Tras Retry-After
500Pago cobrado, pero registro inaccesible
Incidente del servicio

El servicio se niega a atender una validación que no puede registrar. Reintenta. Si la llamada era de pago, cita transaction_id: la conciliación se hace a mano.

Sí, guarda transaction_id
503Cuentas de clientes o base de datos inaccesibles
Incidente del servicio

No se pudo verificar la clave (no es un rechazo) o la base de datos no responde. Reintenta en unos minutos: no se ha consumido nada.
Un 503 nunca es una petición de pago.

Sí, en unos minutos

Facturación

Lo que no se vuelve a pagar y lo que tiene tope

Caché (veredicto): Una misma dirección normalizada no vuelve a consultar al proveedor durante 30 días. Lo garantiza cache_key.; Qué hacerLlama sin miedo a pagar dos veces la misma consulta. Para forzar una nueva llamada, cambia la dirección: la API no adivina.
Caché (degradado): Un resultado degraded se guarda 5 minutos, no 30 días: «el proveedor no respondió» no es un veredicto.; Qué hacerTrata degraded: true como «inténtalo más tarde». Pasada esa ventana corta, la misma llamada obtiene una respuesta real.
Cuota: Mensual, sobre el mes natural en UTC: se reinicia el día 1 del mes, no 30 días después de tu primera llamada.; Qué hacerVigila X-Quota-Remaining. Escríbenos antes del límite y no después.
Precio por llamada: 0,02 USDC por validación cobrada (modo x402). Una llamada cubierta por una suscripción indica price_paid: 0.0.; Qué hacerUn agente que paga lee el cuerpo 402 (accepts): el precio figura ahí y nunca hay que adivinarlo.
Prueba sin cuenta: 10 validaciones por día y por visitante en /validate-form.; Qué hacerPara un uso regular, crea una cuenta: 100 validaciones gratis y después un plan mensual.

Ejemplos

Casos prácticos

Cuatro formas de conectar la API. Cada ejemplo lee la clave de una variable de entorno.

1. Llamada directa (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. Importación CSV (Python)

verifier_colis.pyPython

"""Verifica un CSV de direcciones y escribe el veredicto al lado.

El proveedor solo se consulta una vez por direccion: la respuesta se guarda en
cache (30 dias para un veredicto), asi que una segunda ejecucion sobre el mismo
archivo no cuesta nada mas.
"""
import csv
import os
import time

import requests

CLE = os.environ["ADDRESS_VALIDATOR_KEY"]  # nunca en el codigo, nunca en 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)  # caida del servicio: no se ha consumido nada
            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"rechazo {reponse.status_code}"})
            continue
        resultat = reponse.json()["result"]
        sortie.writerow(
            {
                **ligne,
                "validated": resultat["validated"],
                "deliverability": resultat["deliverability"],
                "degraded": resultat["degraded"],
                "note": "a reverificar (proveedor no disponible)"
                if resultat["degraded"]
                else "",
            }
        )

Lo que ilustra el ejemplo, y nada más: la clave viene de una variable de entorno, se respeta el 429 (el plazo se lee, no se adivina) y un resultado degraded se marca como «por reverificar» en lugar de escribirse como dirección inválida.

Ni aplicación de Shopify ni extensión de WooCommerce. No hay nada que instalar en tu tienda: la API es el contrato y la llamada sale de tu servicio. Eso te deja elegir tu umbral de confianza.

3. Shopify

Disparador: Un webhook orders/create (o tu paso de preparación de paquetes) llama a tu servicio, que consulta /validate con la dirección de entrega del pedido.
Correspondencia de campos: shipping_address.address1 → street (añade address2 a line2 en el resultado)
city → city
province_code → state
zip → zip
country_code → country
Decisión: validated: false: señala el pedido en tu back-office antes del envío. degraded: true: no bloquees nada, reprograma una comprobación.
Lo que no ofrecemos: Ninguna aplicación de Shopify lista para instalar: la llamada sale de tu servicio.

4. WooCommerce

Disparador: La acción woocommerce_checkout_order_processed (pedido pagado) o un cron que recorre los pedidos en preparación (wc_get_orders( ['status' => 'processing'] )).
Correspondencia de campos: $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
Trazabilidad: Guarda cache_key con el pedido: es el único identificador de la dirección válido para una solicitud de eliminación.
Lo que no ofrecemos: Ninguna extensión de WooCommerce: la llamada sale de tu servicio.

En todos los casos: una sola llamada por dirección y por pedido, nunca en un bucle que ignore los códigos de respuesta. Un 402 de cuota no es una caída: es un límite y se lee en la respuesta.

Desarrolladores y agentes de IA

Pago por llamada, sin cuenta

Un agente autónomo no necesita ni cuenta ni clave. Cada validación cobrada cuesta 0,02 USDC, pagada con x402 en la red Base.

1Llama a POST /validate con el cuerpo habitual. Sin pago, la respuesta es un 402 cuyo cuerpo lleva {"x402Version": 1} y el campo accepts: el precio figura ahí.
2Firma la autorización. Construye una autorización EIP-3009 a partir de accepts y reenvía la solicitud con el encabezado X-PAYMENT.
3Lee la respuesta. X-Payment-Mode vale x402, price_paid da el precio en USDC y transaction_id es la referencia que hay que citar en caso de 500.

Para tus agentes, todo se descubre sin pagar:

Conviene saber antes de integrar

Límites

Estados Unidos Optimizado: El proveedor está optimizado para direcciones de Estados Unidos: dirección estandarizada, coordenadas, entregabilidad e índice de confianza.
Francia y ultramar Verificado (BAN): Las direcciones francesas y de ultramar se verifican con la Base Adresse Nationale: la puntuación, el código postal y la ciudad deben coincidir. Otros países siguen con verificación parcial.
degraded: true Reverificar: El proveedor no respondió. La respuesta no dice nada de la dirección: no es un rechazo. Repite la verificación más tarde.
Integraciones: Ni aplicación de Shopify ni extensión de WooCommerce: la llamada sale de tu propio servicio.

Lo que conservamos y lo que no. En una llamada de pago o con suscripción: una huella de la dirección (cache_key) y el resultado, nunca la dirección en sí. En la prueba gratuita sin cuenta: nada, solo un contador anónimo que hace respetar el tope. Una solicitud de eliminación se hace con el cache_key.

Pasa a la práctica

Crea una cuenta para obtener tu clave o prueba primero una dirección sin cuenta.

Crear cuenta Ver los precios Probar una dirección

En un minuto

Autenticación

Una tienda

Un agente autónomo

El contrato

Solicitud

Respuesta 200

Encabezados de respuesta

Los códigos de respuesta y qué hacer

200Validación atendida

401Clave de API desconocida

402Cuota del mes agotada o ningún pago válido

403Cuenta caducada

422Solicitud mal formada

429Límite de pruebas gratuitas alcanzado

500Pago cobrado, pero registro inaccesible

503Cuentas de clientes o base de datos inaccesibles