Inicio rápido

Esta página le lleva de una clave sandbox a una entrega de webhook verificada por usted, usando solo el entorno sandbox. Nada de lo que aquí se hace se factura. Cada paso enlaza con la guía completa, así que esta página se mantiene breve.

1. Obtenga una clave sandbox

Las claves las emite Leeri bajo solicitud: escriba a hello@leeri.ai y pida una clave sandbox con los scopes checks:write, checks:read y webhooks:manage. Una clave sandbox empieza por ak_sandbox_. Ejecuta el motor de cribado real sobre sus propios datos sin coste y nunca consume cuota ni saldo; consulte Sandbox y live.

Guarde la clave en el entorno, nunca en el código:

export LEERI_API_KEY="ak_sandbox_..."

2. Ejecute una verificación de dirección

Envíe la dirección de prueba designada. Con una clave sandbox siempre responde pending, así que puede construir desde el primer día su sondeo y la gestión de webhooks. Envíe un Idempotency-Key con cada POST para que un reintento nunca verifique dos veces; consulte Idempotencia.

curl

curl -s -X POST https://api.leeri.ai/v1/checks \
  -H "Authorization: Bearer $LEERI_API_KEY" \
  -H "Idempotency-Key: quickstart-1" \
  -H "Content-Type: application/json" \
  -d '{"subject":"address","asset":"BTC","address":"1PENDNGCHECKADDRESSFRSANDBXTEST99"}'

Node.js

const response = await fetch('https://api.leeri.ai/v1/checks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LEERI_API_KEY}`,
    'Idempotency-Key': 'quickstart-1',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ subject: 'address', asset: 'BTC', address: '1PENDNGCHECKADDRESSFRSANDBXTEST99' }),
});
const { data } = await response.json();
console.log(data.status, data.check_id); // "pending" and the id to poll

Python

import os
import requests

response = requests.post(
    "https://api.leeri.ai/v1/checks",
    headers={
        "Authorization": f"Bearer {os.environ['LEERI_API_KEY']}",
        "Idempotency-Key": "quickstart-1",
    },
    json={"subject": "address", "asset": "BTC", "address": "1PENDNGCHECKADDRESSFRSANDBXTEST99"},
    timeout=30,
)
data = response.json()["data"]
print(data["status"], data["check_id"])  # "pending" and the id to poll

La respuesta tiene status: "pending" y un check_id. Toda verificación, pendiente o no, tiene la misma forma; todos los campos están en Verificaciones de dirección.

3. Lea el veredicto

Sondee la verificación hasta que su status deje de ser pending. Entre sondeos espere hasta next_attempt_at en lugar de repetir en bucle: nada cambia antes. Consulte Pending y sondeo.

curl

curl -s https://api.leeri.ai/v1/checks/$CHECK_ID \
  -H "Authorization: Bearer $LEERI_API_KEY"

Node.js

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

let check;
do {
  const response = await fetch(`https://api.leeri.ai/v1/checks/${checkId}`, {
    headers: { Authorization: `Bearer ${process.env.LEERI_API_KEY}` },
  });
  check = (await response.json()).data;
  if (check.status === 'pending') {
    const wait = check.next_attempt_at ? Date.parse(check.next_attempt_at) - Date.now() : 6000;
    await sleep(Math.min(Math.max(wait, 6000), 30000));
  }
} while (check.status === 'pending');

console.log(check.status, check.band, check.score);

Python

import os
import time
from datetime import datetime, timezone

import requests

while True:
    response = requests.get(
        f"https://api.leeri.ai/v1/checks/{check_id}",
        headers={"Authorization": f"Bearer {os.environ['LEERI_API_KEY']}"},
        timeout=30,
    )
    check = response.json()["data"]
    if check["status"] != "pending":
        break
    wait = 6.0
    if check["next_attempt_at"]:
        due = datetime.fromisoformat(check["next_attempt_at"].replace("Z", "+00:00"))
        wait = (due - datetime.now(timezone.utc)).total_seconds()
    time.sleep(min(max(wait, 6.0), 30.0))

print(check["status"], check["band"], check["score"])

completed y failed son ambos terminales: después ningún campo cambia. En una verificación completada mire primero esto:

• band y score. El nivel de riesgo es low, medium, high o severe; léalo del campo en lugar de recalcularlo a partir de la puntuación. Consulte Puntuación y nivel de riesgo.
• findings. Cada hallazgo nombra la regla que se activó y enlaza su fuente en source_url, ya sea un documento público o una página de metodología; consulte Hallazgos y la Metodología.
• partial y partial_reasons. Una verificación nunca falla con un error de servidor porque una fuente de datos esté caída: lo indica. Consulte Qué tan completo es el veredicto.
• report. El informe de evidencias del veredicto, incluido con la verificación; consulte Informes de evidencias.

4. Registre un webhook

Con un webhook registra un endpoint una vez y recibe una entrega firmada check.completed por cada verificación terminada, así que no hay nada que sondear. La URL debe ser https. La respuesta incluye el secreto de firma secret una sola vez: guárdelo de inmediato en su gestor de secretos. Si lo pierde, rote el endpoint. Consulte Registrar un endpoint.

curl

curl -s -X POST https://api.leeri.ai/v1/webhooks \
  -H "Authorization: Bearer $LEERI_API_KEY" \
  -H "Idempotency-Key: quickstart-webhook-1" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-service.example.com/webhooks/leeri"}'

Node.js

const response = await fetch('https://api.leeri.ai/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LEERI_API_KEY}`,
    'Idempotency-Key': 'quickstart-webhook-1',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://your-service.example.com/webhooks/leeri' }),
});
const { data } = await response.json();

// data.secret is shown only in this response.
console.log(data.webhook_id, data.secret);

Python

import os
import requests

response = requests.post(
    "https://api.leeri.ai/v1/webhooks",
    headers={
        "Authorization": f"Bearer {os.environ['LEERI_API_KEY']}",
        "Idempotency-Key": "quickstart-webhook-1",
    },
    json={"url": "https://your-service.example.com/webhooks/leeri"},
    timeout=30,
)
data = response.json()["data"]

# data["secret"] is shown only in this response.
print(data["webhook_id"], data["secret"])

5. Verifique las entregas

Cualquiera que conozca su URL puede enviarle una solicitud, así que una entrega solo es de fiar cuando su cabecera x-aml-signature se verifica con el secreto del paso 4. Calcule el HMAC sobre el cuerpo sin procesar de la solicitud, compare en tiempo constante y rechace una marca de tiempo caducada. Los ejemplos funcionales y un receptor mínimo están en Verificar la firma. Responda 2xx rápido y deduplique por event_id, porque las entregas son al menos una vez; consulte Entrega y reintentos.

Ejecute otra verificación sandbox con la misma clave y confirme que su receptor verifica la entrega y responde 2xx.

Pasar a live

Cuando los pasos anteriores funcionen, pase de sandbox a live cambiando la clave y nada más. Antes:

• Use una clave ak_live_, emitida del mismo modo que la clave sandbox. Guárdela en su almacén de secretos; consulte Autenticación.
• Envíe un Idempotency-Key en cada POST; consulte Idempotencia.
• Gestione 402, 429 y 503 como se describe en Errores y respete Retry-After.
• Manténgase dentro de los límites de Límites de solicitudes y cuotas. Los planes están en la página de precios.
• Vuelva a registrar su endpoint de webhook con la clave live: los endpoints pertenecen a un solo entorno.
• Verifique también transacciones donde las necesite; consulte Verificaciones de transacción.

¿Migra desde una integración con AMLBot? Consulte Migración desde AMLBot: su cliente actual sigue funcionando tras reapuntar tres variables de entorno.