Aller au contenu
IBANforge
← Retour au blog

Valider un IBAN et rechercher sa banque : premiers appels API

·5 min read

Un formulaire fournisseur, une facture extraite par OCR ou une reprise de données peuvent tous contenir un IBAN. Le premier travail consiste à distinguer une erreur de structure, une référence bancaire disponible et une information qui reste inconnue. Ces résultats demandent des traitements différents.

IBANforge contrôle la structure de l’IBAN et recherche les références bancaires disponibles. Il ne confirme ni l’existence du compte, ni son titulaire, ni l’autorisation de payer. Les exemples ci-dessous servent au développement ; ils ne sont pas des instructions de paiement.

1. Faire un premier appel sans clé

L’essai sans clé est proposé sur POST /v1/iban/validate. Son allocation et son renouvellement sont décrits dans la référence de validation. Le bloc trial de la réponse indique le solde et l’échéance applicables ; cet essai ne donne pas accès sans clé à toutes les routes.

curl --fail-with-body --max-time 15 \
  https://api.ibanforge.com/v1/iban/validate \
  -H 'Content-Type: application/json' \
  -d '{"iban":"CH1000230000000012345"}'

Un HTTP 200 signifie que la requête a été traitée. Il faut encore lire valid et les autres contrôles : un IBAN invalide peut lui aussi produire un HTTP 200. Si l’essai est épuisé, ne pas boucler sur le même appel : lire l’erreur et suivre la prise en main d’une clé conservée. Aucune signature de paiement n’est créée par cet exemple.

2. Lire le résultat sans lui donner une portée excessive

ChampLecture utile
validRésultat de la validation de structure ; ne résume pas tous les contrôles bancaires ou nationaux additionnels.
checksContrôles détaillés, avec leurs échecs et états inconnus. Lire notamment le contrôle national lorsqu’il est disponible.
bank_code_holderÉtat de l’identification du détenteur du code bancaire, pas identité du titulaire du compte.
bank_code_checkRéférence consultée, résultat, portée et date as_of. Une source indisponible ou incomplète ne justifie pas une conclusion d’inexistence.
bicBIC éventuellement trouvé. Lire basis, authoritative, source et as_of ; le bloc peut être absent ou nul.
sepa et VoPIndications de pays, banque ou registre selon le champ ; aucune réponse de vérification du nom du bénéficiaire.

Un BIC absent ne rend donc pas à lui seul un IBAN invalide. Un résultat bancaire confirmé ne valide pas le compte. La couverture par source et la lecture du registre VoP détaillent ces limites. Conserver les constats et leur provenance avant de décider comment les présenter à l’utilisateur.

3. Réutiliser la même clé côté serveur

Pour les appels réguliers, créer une clé une fois selon la documentation des clés, puis la conserver dans IBANFORGE_API_KEY. Ne pas recréer une clé à chaque exécution. Les allocations et options payantes restent celles de la page de prix ; les exemples n’achètent ni crédit ni abonnement.

Python, bibliothèque standard

Ce code s’exécute côté serveur. Il borne l’attente, vérifie le statut HTTP avant de décoder la réponse et ne suit pas les redirections. Le résumé affiché ne contient pas l’IBAN saisi ; conserver la réponse complète uniquement dans le stockage adapté à votre application.

import http.client
import json
import os
 
key = os.environ.get("IBANFORGE_API_KEY", "").strip()
if not key:
    raise SystemExit("IBANFORGE_API_KEY is required")
 
connection = http.client.HTTPSConnection("api.ibanforge.com", timeout=10)
try:
    connection.request(
        "POST", "/v1/iban/validate",
        body=json.dumps({"iban": "CH1000230000000012345"}),
        headers={"Content-Type": "application/json", "Authorization": f"Bearer {key}"},
    )
    response = connection.getresponse()
    if response.status != 200:
        raise SystemExit(f"API HTTP {response.status}")
    result = json.load(response)
finally:
    connection.close()
 
if not isinstance(result, dict) or type(result.get("valid")) is not bool:
    raise SystemExit("Unexpected API response")
print(json.dumps({
    "valid": result["valid"],
    "bank_code_holder": result.get("bank_code_holder"),
    "bic": (result.get("bic") or {}).get("code"),
}))

TypeScript ou JavaScript côté serveur

Exemple pour Node.js 22 ou plus récent. Ne pas placer une clé secrète dans le JavaScript envoyé au navigateur. Pour un formulaire web, faire l’appel depuis votre serveur ; consulter la référence API pour les erreurs et l’authentification.

Enregistrer le bloc dans premier-appel.mjs, puis lancer node premier-appel.mjs : le await de premier niveau nécessite un module ESM.

const key = process.env.IBANFORGE_API_KEY?.trim();
if (!key) throw new Error('IBANFORGE_API_KEY is required');
 
const response = await fetch('https://api.ibanforge.com/v1/iban/validate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
  body: JSON.stringify({ iban: 'CH1000230000000012345' }),
  signal: AbortSignal.timeout(10_000),
  redirect: 'error',
});
if (response.status !== 200) throw new Error(`API HTTP ${response.status}`);
const result = await response.json();
if (typeof result?.valid !== 'boolean') throw new Error('Unexpected API response');
console.log({
  valid: result.valid,
  bank_code_holder: result.bank_code_holder ?? null,
  bic: result.bic?.code ?? null,
});

Ces exemples s’arrêtent sur une erreur HTTP et n’effectuent aucune relance automatique. Une erreur réseau ou un délai dépassé doit rester distinct d’un verdict « IBAN invalide ».

4. Rechercher un BIC déjà fourni

Si le document contient déjà un BIC, la recherche BIC permet de consulter sa référence bancaire. Avec la même variable de clé définie :

curl --fail-with-body --max-time 15 \
  https://api.ibanforge.com/v1/bic/UBSWCHZH80A \
  -H "Authorization: Bearer ${IBANFORGE_API_KEY}"

Cette recherche ne prouve pas que le BIC appartient à l’IBAN saisi. Si les données existantes et la référence retrouvée divergent, conserver les deux et demander une revue ; ne pas écraser silencieusement la fiche fournisseur.

5. Passer à un petit lot, puis à un flux de revue

Le traitement par lot demande son propre accès : l’essai sans clé de la validation unitaire ne s’y applique pas. Le premier lot ci-dessous contient deux valeurs de démonstration, dont une clé de contrôle incorrecte.

curl --fail-with-body --max-time 15 \
  https://api.ibanforge.com/v1/iban/batch \
  -H "Authorization: Bearer ${IBANFORGE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"ibans":["CH1000230000000012345","CH0000230000000012345"]}'

Vérifier le nombre de résultats et la correspondance de chaque IBAN avant de les rattacher aux lignes du fichier. Une réponse partielle, inversée ou inconnue doit interrompre l’attribution automatique ; conserver le fichier d’origine. Ne pas conclure à la validité du lot entier depuis son seul HTTP 200.

Le guide de revue avant migration fournit un exemple Python qui sépare l’original, les constats et les propositions. Les recettes d’intégration proposent aussi un modèle n8n. Choisir d’abord un cas concret et quelques données de démonstration, puis vérifier comment votre application traite les résultats inconnus avant tout usage réel.