Poradnik integracji z PHP

Weryfikacja numeru IBAN w formularzu PHP

Utwórz mały formularz po stronie serwera, który weryfikuje numer IBAN za pomocą IBAN-Test, utrzymuje Twój token API z dala od przeglądarki i wyraźnie informuje klientów, gdy weryfikacja nie może zostać ukończona.

Stan testów: Dołączone testy używają symulowanego transportu i fikcyjnych danych uwierzytelniających. Sprawdzają wyniki prawidłowe, nieprawidłowe i niedostępne, odrzucenie CSRF, kodowanie znaków HTML oraz odstęp między wysłaniami. Symulują nieudany transfer, aby sprawdzić obsługę przekroczenia czasu bez oczekiwania na sieć. Nie jest to uwierzytelniony test rzeczywistego API. Uruchamiaj testy podczas dostosowywania przykładu, a następnie sprawdź środowisko testowe przed przyjmowaniem danych od rzeczywistych klientów.

1. Zrozum przepływ żądań

Przeglądarka wyświetla zwykły formularz HTML. Po przesłaniu numer IBAN i token CSRF są przesyłane z sesji do Twojej aplikacji PHP. PHP sprawdza token formularza, ogranicza dane wejściowe i usuwa normalne białe znaki przed zażądaniem API. Przeglądarka nigdy nie łączy się bezpośrednio z IBAN-Test i nie otrzymuje tokena nośnika.

Backend wysyła JSON do POST https://www.iban-test.eu/api/v2/iban/validate. Odczytuje status HTTP i pola JSON, mapuje wynik na określoną wiadomość użytkownika i zwraca kolejną stronę HTML. Interfejs jest opisany w dokumentacja API IBAN-Test.

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

Zachowaj ten podział nawet przy dostosowaniu AJAX: JavaScript może wywoływać własną aplikację, ale uwierzytelnianie do IBAN-Test pozostaje na serwerze. Token w pliku JavaScript lub zminimalizowanym pakiecie nie jest tajny.

2. Uruchom przykład lokalnie

Rozpakuj plik ZIP i przejdź do katalogu demo. Sprawdź wersję PHP i rozszerzenie cURL, używając php -v i php -m. Sesje i JSON również muszą być dostępne. Kompozytor nie jest wymagany. Najpierw przeprowadź dołączone kontrole offline:

php tests/run.php

Do rzeczywistego testowania API będziesz potrzebować tokena z konta IBAN-Test. W Bash użyj ukrytych danych wejściowych, aby wartość nie znalazła się w historii powłoki jako polecenie w postaci zwykłego tekstu:

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

Otwórz http://127.0.0.1:8080. Serwer nasłuchuje tylko na Twoim komputerze. Zatrzymaj go za pomocą Ctrl+C, a następnie uruchom unset IBAN_TEST_API_TOKEN. W tym ćwiczeniu lokalnym używany jest serwer programistyczny PHP. Pozostaw public ustawiony jako katalog główny, aby klient, testy i plik README znajdowały się poza dostarczonym katalogiem.

Bez zmiennej środowiskowej formularz będzie nadal ładowany. Jeśli dane wejściowe są wiarygodne, wyświetla komunikat o niedostępności bez wysyłania zapytań do interfejsu API. Prawdziwe żądania API wymagają aktywnego konta i zużywają limit.

3. Wstępnie sprawdź wpisy i chroń formularz

Przykład przyjmuje pojedynczy ciąg o długości do 80 bajtów, usuwa zwykłe spacje, zamienia litery na wielkie i sprawdza prosty wzorzec znaków. Dzięki temu odrzuca oczywiście nieodpowiednie dane niewielkim kosztem. Te kontrole nie obliczają sumy kontrolnej ani nie potwierdzają poprawności IBAN; serwer nadal potrzebuje wyniku API.

Losowy token przechowywany w sesji jest wysyłany jako ukryte pole i porównywany po wysłaniu. Inny token jest odrzucany przed wywołaniem API. Istnieje również okres oczekiwania wynoszący trzy sekundy pomiędzy wpisami w sesji. Pomaga to uniknąć wielokrotnego klikania, ale nie stanowi produktywnego limitu szybkości, ponieważ użytkownicy mogą tworzyć nowe sesje.

Wszystkie wartości wstawiane do HTML są maskowane za pomocą htmlspecialchars, łącznie z ponownym wyświetlaniem danych wejściowych po błędzie. Implementacja jawnie pomija cudzysłowy i zastępuje nieprawidłowe sekwencje UTF-8 zgodnie z Odniesienie do maskowania PHP. Odpowiedzi przeglądarki używają Cache-Control: no-store. Sesyjne pliki cookie wykorzystują HttpOnly i SameSite; Opcje wyjaśniono w Dokumentacja sesji PHP.

4. Wyślij ograniczone żądanie API

Klient odczytuje IBAN_TEST_API_TOKEN na serwerze i wysyła nagłówek Authorization: Bearer. Treść żądania zawiera wyłącznie znormalizowany numer IBAN:

{"iban":"DE89370400440532013000"}

Cel jest określony w kodzie. Przesyłanie formularza nie umożliwia wybrania hosta. Certyfikat TLS i nazwa hosta są nadal sprawdzane; Przekierowania są wyłączone. Nawiązanie połączenia jest ograniczone do trzech sekund, a cała transmisja do ośmiu sekund. Odpowiedź powyżej 64 KiB przerywa transmisję. Opcje są opisane w dokumentacja PHP cURL.

Nie ma automatycznego powtarzania. Po upływie limitu czasu może nie być jasne, czy dostawca przetworzył żądanie; Powtórzenia mogą zająć dodatkowy limit. Dlatego na stronie pojawia się tymczasowy błąd. Jeśli aplikacja później doda ponowne próby, zdefiniuj ograniczoną strategię, która uwzględnia zarówno opóźnienia, jak i przydział.

5. Pokaż poprawny wynik

Sprawdź zarówno pomyślną transmisję, jak i pola odpowiedzi. W przypadku tego punktu końcowego przykład zgodny z udokumentowane kody wyników obejmuje trzy przypadki:

• Ważne: HTTP 200, wartość całkowita code: 2100 i wartość logiczna error: false muszą występować razem.
• Nieprawidłowe dane bankowe: Poprawnie skonstruowana odpowiedź HTTP 200 z kodem 3100, 3101 lub 3102 i wartością logiczną error: true skłania do korekty. Odpowiedzi sprzeczne z error: false są uważane za niedostępne.
• Niedostępne: Problemy z uwierzytelnianiem lub przydziałami, różne wartości stanu HTTP, przekroczenia limitu czasu, nieznane kody i zły kod JSON powodują wyświetlenie komunikatu o błędzie technicznym.

Brak możliwości wykonania weryfikacji nie oznacza, że numer IBAN klienta jest nieprawidłowy. Przykład wyświetla własne komunikaty zamiast surowego tekstu dostawcy. Prawidłowy wynik potwierdza zgodność formalną, ale nie potwierdza właściciela ani istnienia konta czy powodzenia płatności.

6. Przygotuj aplikację do działania

Przed publicznym udostępnieniem formularza wymagaj autoryzacji w aplikacji i egzekwuj wspólny limit wykorzystania API dla użytkowników, sesji i instancji. Przy zakupach bez konta powiąż dostęp z sesją zakupową autoryzowaną na serwerze i dodaj ochronę przed nadużyciami. Sam odstęp między wysłaniami i kontrola CSRF nie chronią płatnego limitu API.

Korzystaj z protokołu HTTPS, bezpiecznych plików cookie, produkcyjnego serwera PHP i ograniczeń rozmiaru treści żądań po stronie serwera. Jawnie skonfiguruj zaufane serwery proxy, gdy TLS zakończy przesyłanie danych. Podaj tajemnice dotyczące swojego środowiska hostingowego; PHP-FPM może wymagać jawnej konfiguracji środowiska. Wyklucz tokeny, treść żądania IBAN i wrażliwe szczegóły błędów z dzienników i monitorowania. Nigdy nie publikuj strony diagnostycznej, która generuje zmienne środowiskowe.