Vai al contenuto principale
GET
/
v1
/
bic
Validazione BIC
curl --request GET \
  --url https://bankvalidation.cleariflow.com/v1/bic/
{
  "bic": "DEUTDEFF500",
  "is_valid": true,
  "country_code": "DE",
  "country_name": "Germany",
  "bank_code": "DEUT",
  "bank_name": "Bank information not available",
  "location_code": "F",
  "branch_code": "500",
  "details": {
    "type": "BIC",
    "active": true,
    "institution_type": "Bank"
  }
}

​
Per iniziare

​
URL di base

https://bankvalidation.cleariflow.com/v1/bic/

​
Endpoint di validazione

L’endpoint bic richiede la tua chiave API e un parametro BIC per eseguire una validazione completa dei Business Identifier Codes. 
https://bankvalidation.cleariflow.com/v1/bic/
? api_key = YOUR_UNIQUE_API_KEY
& bic = DEUTDEFF500
Questa richiesta riuscita valida un BIC tedesco e restituisce informazioni dettagliate: 
{
  "bic": "DEUTDEFF500",
  "is_valid": true,
  "country_code": "DE",
  "country_name": "Germany",
  "bank_code": "DEUT",
  "bank_name": "Bank information not available",
  "location_code": "F",
  "branch_code": "500",
  "details": {
    "type": "BIC",
    "active": true,
    "institution_type": "Bank"
  }
}

​
Parametri della richiesta

​
api_key
String
obbligatorio
La tua chiave API univoca. Nota che ogni utente ha chiavi API univoche per ciascuna delle API Cleariflow, quindi la chiave dell’API di validazione bancaria non funzionerà per l’API tassi di cambio, ad esempio.
​
bic
String
obbligatorio
Il Business Identifier Code da validare. Gli spazi sono consentiti e verranno rimossi automaticamente durante l’elaborazione. Il BIC deve seguire il formato standard ISO 9362.

​
Parametri della risposta

La risposta API viene restituita in un formato JSON universale e leggero.
​
bic
String
Il BIC normalizzato senza spazi, restituito in formato maiuscolo.
​
is_valid
Boolean
Risultato complessivo della validazione che indica se il BIC è valido secondo tutte le regole di validazione.
​
country_code
String
Il codice paese ISO a due lettere (es. DE per Germania, US per Stati Uniti).
​
country_name
String
Il nome completo del paese associato al BIC.
​
bank_code
String
Il codice identificativo bancario a 4 caratteri (es. DEUT per Deutsche Bank).
​
bank_name
String
Il nome della banca (attualmente mostra “Bank information not available”).
​
location_code
String
Il codice di localizzazione a 2 caratteri che indica la città o la regione (es. FF per Francoforte).
​
branch_code
String
Il codice filiale a 3 caratteri (opzionale, può essere vuoto per BIC a 8 caratteri).
​
details
Object
Informazioni dettagliate aggiuntive sul tipo e lo stato del BIC.
​
details.type
String
Il tipo di identificativo (tipicamente “BIC”).
​
details.active
Boolean
Se il BIC è attualmente attivo e in uso.
​
details.institution_type
String
Il tipo di istituto finanziario (es. “Bank”, “Credit Union”).

​
Esempi

​
BIC tedesco valido (8 caratteri)

Richiesta: 
GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY&bic=DEUTDEFF
Risposta: 
{
  "bic": "DEUTDEFF",
  "is_valid": true,
  "country_code": "DE",
  "country_name": "Germany",
  "bank_code": "DEUT",
  "bank_name": "Bank information not available",
  "location_code": "FF",
  "branch_code": "",
  "details": {
    "type": "BIC",
    "active": true,
    "institution_type": "Bank"
  }
}

​
BIC tedesco valido (11 caratteri con filiale)

Richiesta: 
GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY&bic=DEUTDEFF500
Risposta: 
{
  "bic": "DEUTDEFF500",
  "is_valid": true,
  "country_code": "DE",
  "country_name": "Germany",
  "bank_code": "DEUT",
  "bank_name": "Bank information not available",
  "location_code": "FF",
  "branch_code": "500",
  "details": {
    "type": "BIC",
    "active": true,
    "institution_type": "Bank"
  }
}

​
BIC statunitense valido

Richiesta: 
GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY&bic=CHASUS33
Risposta: 
{
  "bic": "CHASUS33",
  "is_valid": true,
  "country_code": "US",
  "country_name": "United States",
  "bank_code": "CHAS",
  "bank_name": "Bank information not available",
  "location_code": "33",
  "branch_code": "",
  "details": {
    "type": "BIC",
    "active": true,
    "institution_type": "Bank"
  }
}

​
BIC britannico valido

Richiesta: 
GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY&bic=NWBKGB2L
Risposta: 
{
  "bic": "NWBKGB2L",
  "is_valid": true,
  "country_code": "GB",
  "country_name": "United Kingdom",
  "bank_code": "NWBK",
  "bank_name": "Bank information not available",
  "location_code": "2L",
  "branch_code": "",
  "details": {
    "type": "BIC",
    "active": true,
    "institution_type": "Bank"
  }
}

​
BIC non valido

Richiesta: 
GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY&bic=INVALID
Risposta: 
{
  "bic": "INVALID",
  "is_valid": false,
  "country_code": "",
  "country_name": "",
  "bank_code": "",
  "bank_name": "Bank information not available",
  "location_code": "",
  "branch_code": "",
  "details": {
    "type": "BIC",
    "active": true
  }
}

​
Gestione degli errori

​
Parametro BIC mancante

Richiesta: 
GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY
Risposta: 
{
  "error": {
    "message": "Missing bic",
    "code": "missing_bic"
  }
}

​
Chiave API mancante

Richiesta: 
GET https://bankvalidation.cleariflow.com/v1/bic/?bic=DEUTDEFF500
Risposta: 
{
  "error": {
    "message": "API key is required",
    "code": "missing_api_key"
  }
}

​
Struttura BIC

Il BIC è composto da diversi elementi:
  1. Codice bancario (4 caratteri): identificativo univoco dell’istituto finanziario
  2. Codice paese (2 caratteri): codice paese ISO 3166-1 alpha-2
  3. Codice di localizzazione (2 caratteri): identificativo della città o regione
  4. Codice filiale (3 caratteri): identificativo filiale opzionale (XXX per la sede centrale)

​
Esempi di formato

  • BIC a 8 caratteri: DEUTDEFF (Deutsche Bank, Germania, Francoforte)
  • BIC a 11 caratteri: DEUTDEFF500 (Deutsche Bank, Germania, Francoforte, filiale 500)

​
Codici di localizzazione comuni

  • FF: Francoforte, Germania
  • 33: New York, Stati Uniti
  • 2L: Londra, Regno Unito
  • PP: Parigi, Francia
  • MM: Milano, Italia

​
Regole di validazione

L’API esegue una validazione completa che include:
  1. Validazione della lunghezza: verifica se il BIC è lungo 8 o 11 caratteri
  2. Validazione del formato: verifica che il BIC segua lo standard ISO 9362
  3. Validazione dei caratteri: assicura che vengano usati solo caratteri alfanumerici
  4. Validazione del codice paese: valida il formato del codice paese
  5. Validazione del codice bancario: verifica il formato dell’identificativo bancario

​
Requisiti del formato BIC

  • Codice bancario: 4 caratteri alfanumerici
  • Codice paese: 2 caratteri alfabetici (ISO 3166-1)
  • Codice di localizzazione: 2 caratteri alfanumerici
  • Codice filiale: 3 caratteri alfanumerici (opzionale)

​
BIC vs SWIFT

BIC (Business Identifier Code) e SWIFT sono spesso usati in modo intercambiabile:
  • BIC: il nome ufficiale dello standard ISO 9362
  • SWIFT: la rete di messaggistica che ha reso popolare il codice
  • Codice SWIFT: nome alternativo per BIC
Tutti i BIC possono essere usati per la messaggistica SWIFT, ma non tutti i codici SWIFT sono BIC validi.

​
Paesi supportati

L’API supporta la validazione BIC per oltre 50 paesi tra cui:
  • Europa: Germania, Francia, Italia, Spagna, Paesi Bassi, Belgio, Austria, Svizzera, Regno Unito, Polonia
  • Americhe: Stati Uniti, Canada, Brasile, Messico
  • Asia: Giappone, Singapore, Hong Kong, Australia
  • Africa: Sudafrica, Egitto, Nigeria
Per un elenco completo dei paesi supportati, consulta la pagina Paesi supportati.

​
Casi d’uso

La validazione BIC è essenziale per:
  1. Bonifici internazionali: garantire informazioni di instradamento accurate
  2. Pagamenti SEPA: requisiti del sistema di pagamento europeo
  3. Applicazioni bancarie: validazione dei conti cliente
  4. Conformità finanziaria: requisiti di reporting normativo
  5. Elaborazione pagamenti: applicazioni e-commerce e fintech