Guida all’integrazione PHP

Validare un IBAN in un modulo PHP

Crea un piccolo modulo lato server che verifica un IBAN con IBAN-Test, mantiene il token API lontano dal browser e informa chiaramente i clienti quando non è possibile completare una verifica.

Stato dei test: I test inclusi usano un trasporto simulato e credenziali fittizie per verificare esiti validi, non validi e non disponibili, rifiuto CSRF, escape HTML e intervallo tra invii. Simulano un trasferimento fallito per controllare i timeout senza attendere la rete. Non costituiscono un test autenticato dell’API reale. Eseguili quando adatti l’esempio e verifica l’ambiente di collaudo prima di accettare invii da clienti reali.

1. Comprendere il flusso della richiesta

Il browser visualizza un normale modulo HTML. Una volta inviati, l'IBAN e un token CSRF vengono trasferiti dalla sessione alla tua applicazione PHP. PHP controlla il token del modulo, delimita l'input e rimuove i normali spazi bianchi prima di richiedere l'API. Il browser non si connette mai direttamente a IBAN-Test e non riceve il token al portatore.

Il backend invia JSON a POST https://www.iban-test.eu/api/v2/iban/validate. Legge lo stato HTTP e i campi JSON, associa il risultato a un messaggio utente specificato e restituisce un'altra pagina HTML. L'interfaccia è descritta nello documentazione dell’API IBAN-Test.

Browser form → your PHP backend → IBAN-Test API
Browser result ← controlled message ← HTTP status and JSON

Mantieni questa suddivisione anche con una personalizzazione AJAX: a JavaScript è consentito chiamare la tua applicazione, ma l'autenticazione su IBAN-Test rimane sul server. Un token in un file JavaScript o in un bundle minimizzato non è segreto.

2. Avviare l'esempio localmente

Decomprimi il file ZIP e vai alla directory demo. Controlla la versione PHP e l'estensione cURL utilizzando php -v e php -m. Devono essere disponibili anche sessioni e JSON. Il compositore non è richiesto. Innanzitutto, esegui i controlli offline inclusi:

php tests/run.php

Per il test effettivo dell'API avrai bisogno di un token dal tuo account IBAN-Test. In Bash, usa l'input nascosto in modo che il valore non finisca nella cronologia della shell come comando di testo semplice:

read -r -s -p 'IBAN-Test API token: ' IBAN_TEST_API_TOKEN
printf '\n'
export IBAN_TEST_API_TOKEN
php -d display_errors=0 -d post_max_size=4K -S 127.0.0.1:8080 -t public

Apri http://127.0.0.1:8080. Il server ascolta solo sul tuo computer. Interrompilo con Ctrl+C e quindi esegui unset IBAN_TEST_API_TOKEN. Per questo esercizio locale viene utilizzato il server di sviluppo PHP. Lasciare public impostato come root del documento per mantenere il client, i test e il README all'esterno della directory fornita.

Senza la variabile di ambiente, il modulo verrà comunque caricato. Se l'input è plausibile, mostra un messaggio di indisponibilità senza interrogare l'API. Le richieste API reali richiedono un account attivo e consumano una quota.

3. Pre-controlla le voci e proteggi il modulo

L’esempio accetta una stringa di massimo 80 byte, rimuove gli spazi ordinari, converte le lettere in maiuscolo e verifica un semplice schema di caratteri. In questo modo scarta a basso costo gli input palesemente inadatti. Questi controlli non calcolano il checksum e non confermano la validità dell’IBAN; il server ha ancora bisogno del risultato dell’API.

Un token casuale archiviato nella sessione viene inviato come campo nascosto e confrontato al momento dell'invio. Un token diverso viene rifiutato prima della chiamata API. C'è anche un periodo di attesa di tre secondi tra gli inserimenti per sessione. Ciò aiuta a evitare clic ripetuti, ma non rappresenta un limite di velocità produttiva poiché gli utenti possono creare nuove sessioni.

Tutti i valori inseriti in HTML vengono mascherati con htmlspecialchars, incluso l'input rivisualizzato dopo un errore. L'implementazione evita esplicitamente le virgolette e sostituisce le sequenze UTF-8 non valide secondo Riferimento al mascheramento PHP. Le risposte del browser utilizzano Cache-Control: no-store. I cookie di sessione utilizzano HttpOnly e SameSite; Le opzioni sono spiegate nello Documentazione della sessione PHP.

4. Invia una richiesta API limitata

Il client legge IBAN_TEST_API_TOKEN sul server e invia un'intestazione Authorization: Bearer. Il contenuto della richiesta riporta esclusivamente l'IBAN normalizzato:

{"iban":"DE89370400440532013000"}

L'obiettivo è specificato nel codice. Gli invii dei moduli non possono selezionare un host. Il certificato TLS e il nome host sono ancora controllati; I reindirizzamenti sono disabilitati. La realizzazione del collegamento è limitata a tre secondi e l'intera trasmissione a otto secondi. Una risposta superiore a 64 KiB interrompe la trasmissione. Le opzioni sono descritte da Riferimento cURL PHP.

Non esiste una ripetizione automatica. Dopo un timeout potrebbe non essere chiaro se il fornitore ha elaborato la richiesta; Le ripetizioni potrebbero consumare una quota aggiuntiva. Ecco perché la pagina mostra un errore temporaneo. Se l'applicazione aggiunge successivamente nuovi tentativi, definisci una strategia limitata che tenga conto sia della latenza che della quota.

5. Mostra il risultato corretto

Controlla sia l'avvenuta trasmissione che i campi di risposta. Per questo endpoint, l'esempio secondo codici risultato documentati copre tre casi:

• Valido: HTTP 200, il valore intero code: 2100 e il valore booleano error: false devono essere presenti insieme.
• Coordinate bancarie non valide: Una risposta HTTP 200 costruita correttamente con il codice 3100, 3101 o 3102 e il valore booleano error: true richiede la correzione. Le risposte contrastanti con error: false sono considerate non disponibili.
• Non disponibile: Problemi di autenticazione o quota, diversi valori di stato HTTP, timeout, codici sconosciuti e JSON non valido producono un messaggio di errore tecnico.

Se la verifica non è disponibile, non bisogna comunicare al cliente che il suo IBAN non è valido. L’esempio usa messaggi propri anziché il testo grezzo del fornitore. Un esito valido conferma la validazione formale, non la titolarità o l’esistenza del conto né il successo di un pagamento.

6. Preparare la domanda per l'operazione

Prima di rendere pubblico il modulo, richiedi l’autorizzazione nell’applicazione e applica un limite di consumo condiviso tra utenti, sessioni e istanze. Per gli acquisti come ospite, lega l’accesso a una sessione di acquisto autorizzata dal server e aggiungi protezioni contro gli abusi. L’intervallo tra invii e il controllo CSRF non bastano a proteggere la quota a pagamento.

Utilizza HTTPS, cookie sicuri, un server PHP di livello produttivo e limiti alle dimensioni dei contenuti delle richieste lato server. Configurare esplicitamente i proxy attendibili quando TLS termina a monte. Fornire segreti sul tuo ambiente di hosting; PHP-FPM potrebbe richiedere una configurazione esplicita dell'ambiente. Escludi token, contenuto della richiesta IBAN e dettagli sensibili sugli errori dai log e dal monitoraggio. Non pubblicare mai una pagina di diagnostica che restituisce le variabili di ambiente.