> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Validazione BIC

> L'endpoint `bic` valida i Business Identifier Codes, fornendo una scomposizione dettagliata dei codici bancari, delle informazioni sul paese e dei tipi di istituto per le operazioni bancarie internazionali.

## 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:

<ResponseExample>
  ```json theme={"system"}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### Parametri della richiesta

<ParamField query="api_key" type="String" required>
  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.
</ParamField>

<ParamField query="bic" type="String" required>
  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.
</ParamField>

### Parametri della risposta

La risposta API viene restituita in un [formato JSON](https://www.json.org/json-en.html) universale e leggero.

<ResponseField name="bic" type="String">
  Il BIC normalizzato senza spazi, restituito in formato maiuscolo.
</ResponseField>

<ResponseField name="is_valid" type="Boolean">
  Risultato complessivo della validazione che indica se il BIC è valido secondo tutte le regole di validazione.
</ResponseField>

<ResponseField name="country_code" type="String">
  Il codice paese ISO a due lettere (es. DE per Germania, US per Stati Uniti).
</ResponseField>

<ResponseField name="country_name" type="String">
  Il nome completo del paese associato al BIC.
</ResponseField>

<ResponseField name="bank_code" type="String">
  Il codice identificativo bancario a 4 caratteri (es. DEUT per Deutsche Bank).
</ResponseField>

<ResponseField name="bank_name" type="String">
  Il nome della banca (attualmente mostra "Bank information not available").
</ResponseField>

<ResponseField name="location_code" type="String">
  Il codice di localizzazione a 2 caratteri che indica la città o la regione (es. FF per Francoforte).
</ResponseField>

<ResponseField name="branch_code" type="String">
  Il codice filiale a 3 caratteri (opzionale, può essere vuoto per BIC a 8 caratteri).
</ResponseField>

<ResponseField name="details" type="Object">
  Informazioni dettagliate aggiuntive sul tipo e lo stato del BIC.
</ResponseField>

<ResponseField name="details.type" type="String">
  Il tipo di identificativo (tipicamente "BIC").
</ResponseField>

<ResponseField name="details.active" type="Boolean">
  Se il BIC è attualmente attivo e in uso.
</ResponseField>

<ResponseField name="details.institution_type" type="String">
  Il tipo di istituto finanziario (es. "Bank", "Credit Union").
</ResponseField>

## Esempi

### BIC tedesco valido (8 caratteri)

**Richiesta:**

```
GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY&bic=DEUTDEFF
```

**Risposta:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "error": {
    "message": "Missing bic",
    "code": "missing_bic"
  }
}
```

### Chiave API mancante

**Richiesta:**

```
GET https://bankvalidation.cleariflow.com/v1/bic/?bic=DEUTDEFF500
```

**Risposta:**

```json theme={"system"}
{
  "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](/bank-validation/countries).

## 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