Documentation · API de vérification

Liste de vérification d’intégration

Ce qu’il faut décider, construire et tester avant la mise en production de la vérification Crown Intelligence dans votre système : la collection, la correspondance des champs, le seuil de correspondance, la façon dont les correspondances possibles sont examinées et consignées, la mise à jour des fiches, ainsi que la gestion des limites et des erreurs par l’intégration.

L’API de vérification n’exige aucune clé pour l’instant et répond aux requêtes anonymes. Les contrôles ci-dessous utilisent les points d’accès décrits dans le guide de l’API de vérification et la référence de l’API. La vérification automatisée ou systématique, ainsi que l’utilisation dans un processus d’affaires, nécessitent une licence commerciale en vertu de nos conditions d’utilisation. Confirmez ce point avant de connecter un système en production.

Choisir une collection

Chaque collection constitue un parcours de correspondance distinct. Choisissez celle qui correspond aux listes visées par vos obligations. Un registre n’est pas une collection en soi; pour restreindre une recherche à un registre, utilisez include_dataset.

• Choisissez la collection pour chaque processus et consignez ce choix avec le motif et le responsable.
• Stockez le nom de la collection dans la configuration, afin que sa modification ne nécessite pas de publication de code.
• Confirmez version de la collection à partir de /api/catalog à chaque exécution (voir Revérifier et surveiller).

Faire correspondre les champs du client à la requête de correspondance

Une requête de correspondance envoie jusqu’à 20 requêtes nommées dans un seul corps, chacune avec schema et properties. Utilisez votre propre ID de client ou de contrepartie comme clé de requête, afin que chaque réponse soit rattachée à votre fiche.

• Associez chaque champ du client à une ligne ci-dessus et omettez les champs vides plutôt que d’envoyer des chaînes vides.
• Envoyez tous les noms que vous détenez pour une partie, jusqu’à cinq, y compris les translittérations.
• Envoyez la date de naissance avec la précision dont vous disposez et ne devinez jamais le jour ni le mois.
• Testez une requête sans nom, sans numéro IMO ni MMSI. L’API renvoie le statut 400 pour cette requête seulement (voir Tester avec des noms connus).

Un point de départ qui fait correspondre une fiche client, envoie un lot avec reprises et affiche le meilleur résultat pour chaque partie.

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"])

Définir le seuil et lire l’indicateur de correspondance

Chaque résultat comporte un score de 0 à 1 et un indicateur match, qui vaut true lorsque le score est égal ou supérieur à threshold. Le seuil par défaut est de 0.75 et la valeur par défaut de limit est de 5 résultats par requête (jusqu’à 50). Les résultats sous le seuil sont tout de même renvoyés avec match défini à false, ce qui permet aux réviseurs de voir les quasi-correspondances.

• Consignez le seuil, l’algorithme et la limite dans votre politique de vérification et faites-les approuver par la conformité.
• Utilisez algorithm=standard (valeur par défaut; best a le même sens). name-only calcule le score à partir du nom seul : la date de naissance, le pays, le numéro IMO et le type sont signalés comme caractéristiques, mais ne modifient pas le score. GET /api/algorithms énumère les caractéristiques et les constantes.
• Testez le seuil avec des noms connus avant la mise en production (voir Tester avec des noms connus). Ne le modifiez pas sans nouvelle approbation ni sans noter la date.
• Considérez un score comme une ressemblance, non comme une identité. Confirmez chaque correspondance auprès de la liste officielle de l’éditeur avant d’agir.

Traiter les correspondances possibles

Un résultat dont match est défini à true est une correspondance possible, et non une conclusion. Acheminez-le vers une file d’examen et conservez une décision pour chacun.

• Montrez au réviseur le libellé, le score, les caractéristiques, les jeux de données, les thèmes et le programme de chaque correspondance possible.
• Ouvrez la fiche complète avec GET /api/entity/<id> pour consulter ses inscriptions, ses dates et le lien vers la source (lorsque la fiche en fournit un). L’exemple de Revérifier et surveiller illustre l’appel.
• Consignez la décision selon l’une des mentions suivantes : correspondance confirmée, non-correspondance ou en suspens. Consignez le réviseur, la date et le motif.
• Vérifiez la liste officielle de l’éditeur avant d’agir sur une correspondance confirmée.
• Appliquez vos propres règles d’escalade aux correspondances confirmées. L’escalade relève de votre politique, et non de l’API.
• Conservez id de la fiche et merged_entity (lorsqu’il est fourni). Une entité fusionnée peut regrouper des fiches provenant de plusieurs registres.

Consigner ce qui a été vérifié

Nous ne conservons pas le corps des requêtes; votre système doit donc tenir son propre registre de chaque vérification, y compris celles sans correspondance. Conservez la réponse telle qu’elle a été reçue et ajoutez les champs ci-dessous.

• Consignez les vérifications qui n’ont donné aucune correspondance, ainsi que les correspondances possibles.
• Conservez les journaux en UTC, aussi longtemps que l’exige votre politique de tenue de dossiers.
• Rendez le journal lisible par un auditeur sans l’application : une ligne par vérification, avec la décision liée.

Revérifier et surveiller

Les listes changent. Une partie blanchie le mois dernier peut produire une correspondance après une nouvelle inscription. Effectuez une nouvelle vérification selon un calendrier établi, et chaque fois qu’une collection est reconstruite.

• Interrogez /api/catalog selon un calendrier et conservez le version de chaque collection. Lorsqu’il change, revérifiez les parties de cette collection.
• Pour une exécution de routine des alertes, ajoutez changed_since à la demande de correspondance. Seules les fiches ajoutées ou modifiées à cette date ou à cette heure, ou après, sont renvoyées. “Ajoutée” signifie collectée pour la première fois ; “modifiée” signifie qu’une version d’exportation a détecté une modification de la fiche publiée.
• Effectuez une revérification complète selon un cycle plus long, sans changed_since, afin que rien ne soit manqué si une exécution échoue.
• Si vous détenez les fichiers en bloc, utilisez le fichier delta.json de chaque collection (un objet JSON par ligne, avec un op et l’élément entity modifié, qui porte son last_change) et deltas.json (nombres d’ajouts, de modifications et de suppressions pour chaque construction). Gérez chaque valeur de op que vous rencontrez, et revérifiez lorsque vous en croisez une que vous n’attendiez pas.
• N’alertez les réviseurs que pour une nouvelle inscription ou une modification qui touche leurs obligations. Les mises à jour courantes ne devraient pas leur parvenir. Voir Mettre en place un processus de surveillance.

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"])

Limites de débit, nouvelles tentatives et volume

Le service de données comporte une limite de requêtes par adresse que l’exploitant peut activer. Elle est désactivée actuellement et aucun chiffre n’est publié. Les conditions se réservent le droit d’appliquer des limites ou des plafonds de volume à l’utilisation automatisée; convenez donc de vos volumes avec nous avant d’envoyer un lot important.

• N’envoyez pas d’identifiants. L’API n’a actuellement aucune clé et les ignore. Conservez toute clé future dans un coffre de secrets, non dans le code.
• Envoyez jusqu’à 20 requêtes dans une seule requête de correspondance plutôt qu’une requête par partie.
• Définissez un délai d’expiration des requêtes. Les exemples de cette section utilisent 60 secondes.
• Lorsqu’une réponse est 429 Too Many Requests, attendez le nombre de secondes indiqué dans Retry-After, puis réessayez. Lorsque la limite est activée, chaque réponse comporte aussi X-RateLimit-Limit et X-RateLimit-Remaining.
• En cas de réponse 5xx, réessayez avec un délai croissant et arrêtez après quelques tentatives.
• Ne réessayez pas après une réponse 400 ou 404. Cela signifie que la requête doit être modifiée. Consignez-les et corrigez le mappage.
• Limitez le nombre de requêtes parallèles dans votre système et envoyez un User-Agent qui désigne votre outil et une adresse de contact.

Tester avec des noms connus

Testez l’intégration avec des noms dont l’inscription est connue avant la mise en production, et conservez le jeu de tests dans le contrôle de version. Incluez :

• Des noms inscrits, dont l’inscription est confirmée sur la liste de l’éditeur, dans chaque collection sur laquelle vous vous appuyez.
• Des variantes d’orthographe, l’ordre inversé des noms, des initiales et des translittérations.
• Des dates de naissance avec précision à l’année, au mois et au jour, et une partie sans date de naissance.
• Des noms qui ne devraient pas correspondre, et un navire avec un numéro IMO, si vous vérifiez des navires.
• Une requête sans nom, sans IMO ni MMSI. Attendez-vous au statut 400 pour cette requête, avec l’erreur name, imoNumber or mmsi required. Les autres requêtes de la demande sont tout de même retournées.
• Une collection inconnue, qui retourne 404 avec la liste des collections valides.

Une vérification que nous avons effectuée pour cette page : la requête Igor Putin, année de naissance 1953 et nationalité ru, sur la collection de sanctions avec un seuil de 0.8, a retourné l’inscription aux sanctions avec un score de 1 et match défini à true. Les résultats dépendent de la construction utilisée; consignez donc la version de la collection à chaque exécution de test et répétez les tests après chaque reconstruction.

Vérifications avant la mise en production

• Une licence commerciale est en place pour la vérification automatisée ou systématique.
• L’adresse de base est définie dans la configuration et l’intégration n’utilise aucun identifiant.
• Les collections, les mappages de champs, les seuils et la limite sont approuvés et consignés par écrit.
• Les correspondances possibles parviennent à la file de révision, et chaque décision et son réviseur sont consignés.
• Le journal contient chaque vérification avec la version de la collection et checked_at, et un auditeur peut le lire.
• La revérification s’exécute selon le calendrier, et la reconstruction d’une collection déclenche une revérification.
• Les nouvelles tentatives fonctionnent pour 429 et 5xx, et les erreurs 400 sont consignées et signalées.
• Les tests de noms connus réussissent sur la construction de production et les résultats sont enregistrés.
• Une personne est responsable de l’intégration et sait où acheminer les questions : [email protected].

Exemples

Les exemples ci-dessous sont des points de départ; exécutez-les dans un environnement de test avant de vous y fier. Définissez CROWN_API_BASE pour modifier l’adresse de base; la valeur par défaut est le service public.

Node.js : requête de correspondance

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 : versions des collections et une correspondance

# 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"]}}}}'

Dernière mise à jour : 2026-10-10