Aller au contenu
IBANforge

Validation IBAN par lot

Contrôlez de 1 à 100 IBAN par requête. Le résultat de chaque élément reste indépendant : un IBAN invalide ne supprime ni les autres résultats ni sa propre ligne. Ce contrôle ne prouve pas l’existence du compte ou l’identité de son titulaire.

POST https://api.ibanforge.com/v1/iban/batch

Accès et coût

Une clé API ou un paiement x402 est nécessaire. L’essai sans clé de la validation unitaire ne couvre pas cette route. Conservez la même clé pour suivre son usage et la recharger ; ne la placez pas dans une page publique ou un dépôt.

Avec une clé, chaque élément envoyé compte pour une unité de franchise ou un crédit prépayé, y compris les doublons et les IBAN invalides. Le coût affiché dans cost_usdc vaut alors 0 : cela ne signifie pas que le lot ne consomme aucune unité. Un lot qui dépasse les unités disponibles est refusé entièrement en 402 ; aucun résultat partiel n’est servi. L’allocation et les crédits peuvent financer ensemble un lot.

Avec x402, le prix est de 0,002 USDC par IBAN. Un client x402 signe les exigences reçues dans le 402 ; un en-tête vide n’est pas un paiement. Le guide x402 décrit les signatures v2 PAYMENT-SIGNATURE et la compatibilité v1 X-PAYMENT.

Requête avec une clé

Les exemples utilisent une clé déjà conservée dans la variable d’environnement IBANFORGE_API_KEY, côté serveur. Obtenir et conserver une clé. Les IBAN ci-dessous sont des exemples documentaires ; ils ne désignent pas des comptes à payer.

curl --fail-with-body --silent --show-error \
  https://api.ibanforge.com/v1/iban/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${IBANFORGE_API_KEY:?}" \
  -d '{"ibans":["CH1000230000000012345","DE89370400440532013000","INVALID123"]}'

ibans est un tableau de 1 à 100 chaînes. Les alias iban_list et list sont aussi acceptés ; utilisez un seul champ. Les espaces, traits d’union ASCII et minuscules sont normalisés par le validateur. Une chaîne vide reste un élément invalide, tandis qu’un nombre ou un objet rend la requête entière invalide.

Python

import json
import os
import urllib.request
 
ibans = ["CH1000230000000012345", "DE89370400440532013000", "INVALID123"]
request = urllib.request.Request(
    "https://api.ibanforge.com/v1/iban/batch",
    data=json.dumps({"ibans": ibans}).encode(),
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer " + os.environ["IBANFORGE_API_KEY"],
    },
    method="POST",
)
with urllib.request.urlopen(request, timeout=30) as response:
    data = json.load(response)
 
if len(data["results"]) != len(ibans):
    raise ValueError("results / ibans")
for index, result in enumerate(data["results"]):
    print(json.dumps({"index": index, "input": ibans[index], "result": result}))

Node.js / TypeScript

const key = process.env.IBANFORGE_API_KEY;
if (!key) throw new Error("IBANFORGE_API_KEY");
const ibans = ["CH1000230000000012345", "DE89370400440532013000", "INVALID123"];
const response = await fetch("https://api.ibanforge.com/v1/iban/batch", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
  body: JSON.stringify({ ibans }),
  signal: AbortSignal.timeout(30000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
if (!Array.isArray(data.results) || data.results.length !== ibans.length) {
  throw new Error("results / ibans");
}
for (const [index, result] of data.results.entries()) {
  console.log(JSON.stringify({ index, input: ibans[index], result }));
}

Lire la réponse

Un 200 signifie que le lot a été traité, pas que chaque IBAN est valide. results[i] correspond à l’entrée ibans[i], dans le même ordre et sans dédoublonnage. Conservez votre identifiant de ligne à côté de cet indice.

ChampLecture
resultsUne réponse de validation par entrée ; inspecter valid, puis les contrôles et leurs sources.
countNombre d’éléments traités, doublons compris.
valid_countNombre dont valid vaut true ; ne compte pas des comptes existants ou des paiements autorisés.
cost_usdcMontant USDC de cet appel ; zéro avec une clé.
processing_msDurée de traitement de cette réponse ; ce n’est pas un engagement de délai.
attributionCrédits de sources lorsque la réponse en porte ; les conserver avec les résultats.

Chaque élément suit la référence de validation unitaire. bank_code_holder, bank_code_check, bic, checks et les sources distinguent une référence confirmée, une déduction et une absence de donnée. Certains blocs sont absents ou null selon l’IBAN et les sources disponibles. Le lot ne renvoie pas le bloc supplémentaire de la route compliance.

Erreurs et reprise

Statut / codeTraitement
400 invalid_jsonJSON mal formé.
400 invalid_requestChamp absent, tableau attendu ou élément non textuel.
400 empty_batchTableau vide.
400 batch_too_largePlus de 100 éléments ; découper les entrées avant l’appel.
402Clé absente, inutilisable ou unités insuffisantes ; lire le corps et les en-têtes du refus.
429Limite de débit ; attendre Retry-After.

Une réponse 200 peut contenir valid: false avec error et error_detail. Pour un échec réseau après l’envoi, le traitement peut avoir eu lieu : ne pas rejouer automatiquement tout le lot comme s’il n’avait rien consommé. Conserver les lignes déjà traitées et vérifier l’usage de la clé. Une issue de paiement x402 inconnue demande aussi une vérification avant tout nouveau paiement.

Pour un fichier à examiner, utiliser l’audit de fichier ou le parcours fournisseurs. Pour automatiser la revue : recettes. Pour démarrer : prise en main. Les erreurs détaillent les quotas et les limites de débit.

Passez à votre cas concret

Choisissez une première étape pour votre logiciel ou votre fichier fournisseurs.

Contrôler un fichier fournisseurs

Déposez un CSV ou un fichier Excel et consultez gratuitement l’aperçu des constats. Achetez le classeur annoté si vous avez besoin du rapport complet. Sans compte ni abonnement.

Découvrir l’audit de fichiers

Intégrer les contrôles IBAN à votre logiciel

Essayez une validation, examinez la réponse, puis reliez votre application à l’API ou à une intégration existante.

Découvrir le parcours API

Les informations bancaires disponibles varient selon le pays et la source. Ces contrôles ne confirment pas le titulaire du compte et ne garantissent pas la réussite d’un paiement.