Cómo integrar una API de listas negras en tu sistema de compliance

¿Por qué integrar una API de listas negras?

Si tu empresa necesita verificar clientes o contrapartes contra listas de sanciones, tienes dos opciones: hacerlo manualmente (descargando archivos, parseando PDFs, comparando nombres en hojas de cálculo) o automatizarlo con una API.

La opción manual no escala. Con cientos o miles de clientes, y listas que se actualizan semanalmente, necesitas una solución automatizada que se integre directamente en tu flujo de trabajo. AmigoApi es la única solución API-first y self-serviceen Latinoamérica — sin plataformas obligatorias, sin dashboards, sin llamadas de venta.

Arquitectura de integración

La integración típica de una API de listas negras sigue uno de estos patrones:

1. Screening en onboarding

El caso más común. Cuando un nuevo cliente se registra, tu sistema envía sus datos a la API antes de activar su cuenta:

// En tu flujo de registro
async function onboardNewClient(client) {
  // 1. Verificar contra listas negras
  const screening = await fetch(
    "https://api.amigoapi.com/search",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: client.fullName,
        threshold: 0.70,
        sources: ["SAT_69B", "OFAC_SDN", "UN_SANCTIONS"],
      }),
    }
  );

  const result = await screening.json();

  // 2. Evaluar resultados
  if (result.total_matches > 0) {
    // Marcar para revisión manual
    await flagForReview(client, result.matches);
  } else {
    // Continuar con el onboarding
    await activateAccount(client);
  }
}

2. Screening periódico (batch)

Además del onboarding, las regulaciones de PLD/FTrequieren verificaciones periódicas. Puedes ejecutar un job que revise toda tu base de clientes:

// Job periódico (semanal/mensual)
async function batchScreening(clients) {
  for (const client of clients) {
    const result = await fetch(
      "https://api.amigoapi.com/search",
      {
        method: "POST",
        headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: client.fullName,
          threshold: 0.65,
        }),
      }
    );

    const data = await result.json();
    await saveScreeningResult(client.id, data);
  }
}

3. Screening en tiempo real (transaccional)

Para empresas que procesan pagos o transferencias, el screening puede ejecutarse por transacción. La latencia de AmigoApi (~15ms) permite hacerlo sin afectar la experiencia del usuario. También es ideal para agentes de IA que necesiten verificar entidades dentro de un workflow automatizado.

Entendiendo los resultados: 6 métricas de scoring

AmigoApi no retorna un simple “sí/no”. Cada coincidencia incluye un composite scorecalculado a partir de 6 métricas independientes:

"scores": {
  "composite": 0.875,
  "token_sort_ratio": 0.901,   // 35% del peso
  "token_set_ratio": 0.856,    // 20% del peso
  "trigram": 0.890,             // 20% del peso
  "ratio": 0.723,              // 10% del peso
  "jaro_winkler": 0.876,       // 10% del peso
  "phonetic_match": true        // 5% bonus
}

1. Token sort ratio (35%):Independiente del orden de palabras — “García López Juan” = “Juan García López”.
2. Token set ratio (20%): Maneja subconjuntos y superconjuntos de palabras.
3. Trigramas (20%): Similitud a nivel de caracteres usando PostgreSQL pg_trgm.
4. Ratio simple (10%):Similitud básica carácter a carácter.
5. Jaro-Winkler (10%): Favorece coincidencias de prefijo.
6. Matching fonético (5%): Double Metaphone — detecta nombres que suenan igual aunque se escriban diferente.

Qué hacer con los resultados

Tu sistema debe definir reglas claras:

1. Definir umbrales:Un composite de 0.95+ es casi seguro una coincidencia real. Entre 0.70-0.95 requiere revisión manual. Debajo de 0.70 probablemente es un falso positivo.
2. Implementar revisión manual:Las coincidencias ambiguas deben ser revisadas por tu equipo de compliance antes de tomar una decisión.
3. Registrar todo: Guarda los resultados de cada screening (positivos y negativos) como evidencia de cumplimiento.
4. Definir acciones:Qué pasa cuando hay un match confirmado: bloqueo de cuenta, reporte a la UIF, notificación a compliance.

Consideraciones técnicas

• Manejo de errores: Si la API no responde, tu flujo no debe bloquearse indefinidamente. Implementa timeouts y reintentos con backoff exponencial.
• Idempotencia:Las consultas de screening son idempotentes — puedes reintentarlas sin efectos secundarios.
• Logging:Registra cada consulta y su resultado para auditoría.
• Threshold configurable: Diferentes listas y contextos pueden requerir diferentes niveles de sensibilidad. AmigoApi permite configurar el threshold por request (0.0 a 1.0).
• RFC matching:Para entidades mexicanas, puedes incluir el RFC para matching exacto adicional, lo que reduce drásticamente falsos positivos.

¿Por qué AmigoApi?

AmigoApi es la única API self-service de listas negras en Latinoamérica. A diferencia de plataformas tradicionales de compliance que te obligan a usar su dashboard y requieren llamadas de venta:

• Obtienes tu API key y empiezas a consultar inmediatamente.
• Un solo endpoint para todas las listas (SAT, OFAC, ONU, UE, CNBV, UK).
• 6 métricas de fuzzy matching incluyendo búsqueda fonética.
• Respuestas en ~15ms — suficiente para screening en tiempo real.
• Diseñado para que devs y agentes de IA lo integren directamente.

Únete a la waitlist para ser de los primeros en acceder.