Documentación · API de verificación

Lista de verificación de integración

Qué decidir, construir y probar antes de poner en producción la verificación de Crown Intelligence en su sistema: la colección, el mapeo de campos, el umbral de coincidencia, cómo se revisan y se registran las posibles coincidencias, cómo se mantienen actualizados los registros y cómo maneja la integración los límites y los errores.

Hoy la API de verificación no requiere clave y responde a solicitudes anónimas. Las comprobaciones siguientes usan los puntos de acceso de la guía de la API de verificación y de la referencia de la API. La verificación automatizada o sistemática, y el uso en un proceso de negocio, requieren una licencia comercial conforme a nuestros términos de uso. Confírmelo antes de conectar un sistema en producción.

Elija una colección

Cada colección es una ruta de coincidencia independiente. Elija la que corresponda a las listas que abarcan sus obligaciones. Un registro no es una colección por sí mismo; para limitar una búsqueda a un registro, use include_dataset.

• Elija la colección para cada proceso y deje por escrito la elección, el motivo y el responsable.
• Guarde el nombre de la colección en la configuración, para que cambiarla no requiera una nueva versión del código.
• Confirme en cada ejecución el valor de version de la colección a partir de /api/catalog (consulte Nueva verificación y monitoreo).

Asigne los campos del cliente a la solicitud de coincidencia

Una solicitud de coincidencia envía hasta 20 consultas con nombre en un solo cuerpo, cada una con schema y properties. Use su propio ID de cliente o contraparte como clave de la consulta, de modo que cada respuesta se asocie con su registro.

• Asigne cada campo del cliente a una fila de la tabla anterior y omita los campos vacíos en lugar de enviar cadenas vacías.
• Envíe todos los nombres que tenga de una parte, hasta cinco, incluidas las transliteraciones.
• Envíe la fecha de nacimiento con la precisión de que disponga y nunca suponga el día ni el mes.
• Pruebe una consulta sin nombre, IMO ni MMSI. La API devuelve el estado 400 solo para esa consulta (consulte Pruebe con nombres conocidos).

Un punto de partida que asigna un registro de cliente, envía un lote con reintentos e imprime el resultado principal de cada parte.

import os, time, json, requests

BASE = os.environ.get("CROWN_API_BASE", "https://api.crownintelligence.net")
session = requests.Session()
session.headers["User-Agent"] = "my-screening-tool/1.0 ([email protected])"


def to_query(customer):
    """Map one customer record to a match query (see the field table above)."""
    props = {"name": customer["names"][:5]}
    if customer.get("birth_date"):
        props["birthDate"] = [customer["birth_date"]]        # YYYY, YYYY-MM or YYYY-MM-DD
    if customer.get("nationality"):
        props["nationality"] = [customer["nationality"]]     # ISO 3166-1 alpha-2, e.g. "ca"
    if customer.get("imo"):
        props["imoNumber"] = [customer["imo"]]               # seven digits
    return {"schema": customer["schema"], "properties": props}


def match(collection, queries, limit=5, threshold=0.75, changed_since=None, retries=3):
    """POST /api/match with retries for 429 (honour Retry-After) and 5xx (back off)."""
    params = {"limit": limit, "threshold": threshold}
    if changed_since:
        params["changed_since"] = changed_since
    for attempt in range(retries + 1):
        r = session.post(f"{BASE}/api/match/{collection}", params=params,
                         json={"queries": queries}, timeout=60)
        if r.status_code == 429 and attempt < retries:
            time.sleep(int(r.headers.get("Retry-After", "5")))
            continue
        if r.status_code >= 500 and attempt < retries:
            time.sleep(2 ** attempt)
            continue
        r.raise_for_status()
        return r.json()


customers = {
    "C-1001": {"schema": "Person", "names": ["Igor Putin", "Игорь Путин"], "birth_date": "1953-03-30", "nationality": "ru"},
    "C-1002": {"schema": "Vessel", "names": ["Selam"], "imo": "9418286"},
    "C-1003": {"schema": "Person", "names": ["Zz Crown Checklist Testperson"], "birth_date": "1980", "nationality": "ca"},
}
queries = {cid: to_query(c) for cid, c in customers.items()}
out = match("default", queries, limit=3, threshold=0.75)

for cid, answer in out["responses"].items():
    print(cid, answer["status"], "candidates:", answer["total"])
    for hit in answer["results"][:1]:
        print("   top:", hit["caption"], hit["score"], "match" if hit["match"] else "no match", hit["datasets"][:1])
print("checked_at:", out["checked_at"], "| collection:", out["collection"], "| threshold:", out["threshold"])

Defina el umbral e interprete el indicador de coincidencia

Cada resultado tiene un valor score de 0 a 1 y un indicador match, que es true cuando la puntuación es igual o superior a threshold. El umbral predeterminado es 0.75 y el valor predeterminado de limit es de 5 resultados por consulta (hasta 50). Los resultados por debajo del umbral también se devuelven, con match establecido en false, para que los revisores vean los casi coincidentes.

• Registre el umbral, el algoritmo y el límite en su política de verificación, y haga que el área de cumplimiento los apruebe.
• Use algorithm=standard (el valor predeterminado; best significa lo mismo). name-only puntúa solo por el nombre: la fecha de nacimiento, el país, el número IMO y el tipo se informan como características, pero no modifican la puntuación. GET /api/algorithms enumera las características y las constantes.
• Pruebe el umbral con nombres conocidos antes de la puesta en producción (consulte Pruebe con nombres conocidos). No lo cambie sin una nueva aprobación y sin anotar la fecha.
• Considere la puntuación como semejanza, no como identidad. Confirme cada coincidencia con la lista oficial del editor antes de actuar.

Gestione las posibles coincidencias

Un resultado con match establecido en true es una posible coincidencia, no una conclusión. Envíelo a una cola de revisión y conserve una decisión para cada uno.

• Muestre al revisor el título, la puntuación, las características, los conjuntos de datos, los temas y el programa de cada posible coincidencia.
• Abra el registro completo con GET /api/entity/<id> para ver sus inclusiones en listas, fechas y el enlace a la fuente (cuando el registro lo incluya). El ejemplo de Nueva verificación y monitoreo muestra la llamada.
• Registre la decisión como una de estas: coincidencia confirmada, no es una coincidencia o abierta. Registre el revisor, la fecha y el motivo.
• Consulte la lista oficial del editor antes de actuar ante una coincidencia confirmada.
• Aplique sus propias reglas de escalamiento a las coincidencias confirmadas. El escalamiento es un asunto de su política, no de la API.
• Conserve el registro id y el valor de merged_entity (cuando se indique). Una entidad combinada puede agrupar registros de varios registros oficiales.

Registre lo que se verificó

No almacenamos los cuerpos de las consultas, por lo que su sistema debe conservar su propio registro de cada verificación, incluidas las que no arrojan coincidencia. Almacene la respuesta tal como se recibió y agregue los campos siguientes.

• Registre las verificaciones que no arrojaron coincidencias, además de las posibles coincidencias.
• Conserve los registros de actividad en UTC y consérvelos durante el tiempo que exija su política de conservación de registros.
• Haga que el registro de actividad sea legible para un auditor sin necesidad de la aplicación: una fila por verificación, con la decisión vinculada.

Reverificar y monitorear

Las listas cambian. Una parte aprobada el mes pasado puede generar una coincidencia tras una nueva inclusión en la lista. Vuelva a verificar según un calendario y cada vez que se reconstruya una colección.

• Consulte /api/catalog periódicamente y almacene el version de cada colección. Cuando cambie, vuelva a verificar las partes de esa colección.
• Para una ejecución rutinaria de alertas, agregue changed_since a la solicitud de coincidencias. Devuelve solo los registros agregados o modificados en esa fecha u hora, o después. “Agregado” significa recopilado por primera vez; “modificado” significa que una compilación de exportación detectó un cambio en el registro publicado.
• Ejecute una reverificación completa en un ciclo más largo, sin changed_since, para que no se omita nada si falla una ejecución.
• Si dispone de los archivos masivos, use el delta.json de cada colección (un objeto JSON por línea, con un op y el entity modificado, que incluye su last_change) y deltas.json (cantidades de agregados, modificados y eliminados de cada compilación). Gestione cada valor de op que encuentre y vuelva a verificar cuando encuentre uno que no esperaba.
• Alerte a los revisores solo ante una nueva inclusión en la lista o un cambio que afecte sus obligaciones. Las actualizaciones rutinarias no deben llegar a ellos. Consulte Cómo crear un flujo de trabajo de monitoreo.

import os, json, requests

BASE = os.environ.get("CROWN_API_BASE", "https://api.crownintelligence.net")

# Versions now, to compare with the versions stored at the last run
catalog = requests.get(f"{BASE}/api/catalog", timeout=30).json()
versions = {c["name"]: c["version"] for c in catalog["collections"]}
last_run = {"sanctions": "20261004022212-jhp"}  # the version stored at the last run
changed = [name for name, v in versions.items() if last_run.get(name) not in (None, v)]
print("collections rebuilt since the last run:", changed)

# Only records added or changed since the last run (ISO 8601 date or time)
body = {"queries": {"C-1001": {"schema": "Person", "properties": {"name": ["Igor Putin"], "birthDate": ["1953"]}}}}
r = requests.post(f"{BASE}/api/match/sanctions", params={"limit": 10, "changed_since": "2026-10-01"},
                  json=body, timeout=60)
r.raise_for_status()
answer = r.json()["responses"]["C-1001"]
print("changed since 2026-10-01:", answer["total"], "candidates;", r.json()["filters"]["changed_since"])

# Entity lookup for the review screen
ent = requests.get(f"{BASE}/api/entity/379781867", timeout=30).json()
print(ent["id"], ent["name"], ent["register"], ent["list_type"], ent["listings"][0]["register"])

Límites de velocidad, reintentos y volumen

El servicio de datos tiene un límite de solicitudes por dirección que el operador puede activar. Hoy está desactivado y no se publica ninguna cifra. Los términos se reservan el derecho de aplicar límites o topes de volumen al uso automatizado, por lo que debe acordar sus volúmenes con nosotros antes de enviar un lote grande.

• No envíe credenciales. Hoy la API no tiene claves y las ignora. Guarde cualquier clave futura en un almacén de secretos, no en el código.
• Envíe hasta 20 consultas en una sola solicitud de coincidencias, en lugar de una solicitud por parte.
• Defina un tiempo de espera para las solicitudes. Los ejemplos de esta sección usan 60 segundos.
• Cuando una respuesta sea 429 Too Many Requests, espere la cantidad de segundos indicada en Retry-After y vuelva a intentarlo. Cuando el límite está activado, cada respuesta también incluye X-RateLimit-Limit y X-RateLimit-Remaining.
• Ante una respuesta 5xx, reintente con una demora creciente y deténgase después de unos pocos intentos.
• No reintente ante un 400 o un 404. Esto significa que la solicitud debe modificarse. Regístrelos y corrija el mapeo.
• Limite la cantidad de solicitudes en paralelo en su sistema y envíe un User-Agent que indique el nombre de su herramienta y una dirección de contacto.

Pruebas con nombres conocidos

Pruebe la integración con nombres que tengan inclusiones conocidas en listas antes de la puesta en producción y mantenga el conjunto de pruebas bajo control de versiones. Incluya:

• Nombres incluidos en listas, con la inclusión confirmada en la lista del editor, en cada colección en la que se base.
• Variantes de ortografía, orden invertido de nombres, iniciales y transliteraciones.
• Fechas de nacimiento con precisión de año, mes y día, y una parte sin fecha de nacimiento.
• Nombres que no deberían coincidir y una embarcación con número IMO, si verifica embarcaciones.
• Una consulta sin nombre, IMO ni MMSI. Espere el estado 400 para esa consulta, con el error name, imoNumber or mmsi required. Las demás consultas de la solicitud se devuelven normalmente.
• Una colección desconocida, que devuelve 404 con la lista de colecciones válidas.

Una verificación que realizamos para esta página: la consulta Igor Putin, año de nacimiento 1953 y nacionalidad ru, contra la colección de sanciones con un umbral de 0.8, devolvió la inclusión en la lista de sanciones con puntaje 1 y match establecido en true. Los resultados dependen de la compilación en uso, por lo que debe registrar la versión de la colección en cada ejecución de pruebas y repetirlas después de cada reconstrucción.

Verificaciones previas a la puesta en producción

• Existe una licencia comercial para la verificación automatizada o sistemática.
• La dirección base está definida en la configuración y la integración no usa credenciales.
• Las colecciones, los mapeos de campos, los umbrales y el límite están aprobados y documentados.
• Las posibles coincidencias llegan a la cola de revisión y se registran cada decisión y su revisor.
• El registro de actividad contiene cada verificación con la versión de la colección y checked_at, y un auditor puede leerlo.
• La reverificación se ejecuta según el calendario y una colección reconstruida activa una reverificación.
• Los reintentos funcionan para 429 y 5xx, y los errores 400 se registran y se reportan.
• Las pruebas con nombres conocidos se aprueban en la compilación de producción y los resultados se guardan.
• Alguien es responsable de la integración y sabe adónde enviar las preguntas: [email protected].

Ejemplos

Los ejemplos siguientes son puntos de partida, por lo que debe ejecutarlos en un entorno de pruebas antes de confiar en ellos. Defina CROWN_API_BASE para cambiar la dirección base; el valor predeterminado es el servicio público.

Node.js: solicitud de coincidencias

const BASE = process.env.CROWN_API_BASE ?? "https://api.crownintelligence.net";
const queries = {
  vessel: { schema: "Vessel", properties: { name: ["Selam"], imoNumber: ["9418286"] } },
  person: { schema: "Person", properties: { name: ["Igor Putin"], birthDate: ["1953-03-30"], nationality: ["ru"] } },
};
const params = new URLSearchParams({ limit: "3", threshold: "0.75" });
const res = await fetch(`${BASE}/api/match/maritime?${params}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ queries }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
for (const [key, answer] of Object.entries(data.responses)) {
  const top = answer.results[0];
  console.log(key, answer.status, answer.total, top ? [top.caption, top.score, top.match] : "no hits");
}

curl: versiones de colecciones y una coincidencia

# Versions of each collection, to see when a list was rebuilt
curl -s "$CROWN_API_BASE/api/catalog" | python3 -c 'import json,sys; [print(c["name"], c["version"]) for c in json.load(sys.stdin)["collections"]]'

# One party against the sanctions collection
curl -s -X POST "$CROWN_API_BASE/api/match/sanctions?limit=3&threshold=0.8&topics=sanction" \
  -H "Content-Type: application/json" \
  -d '{"queries":{"q1":{"schema":"Person","properties":{"name":["Igor Putin"],"birthDate":["1953"],"nationality":["ru"]}}}}'

Última actualización: 2026-10-10