Guia de integração com PHP

Validar um IBAN num formulário PHP

Crie um pequeno formulário no servidor que verifique um IBAN com IBAN-Test, mantenha seu token de API longe do navegador e informe claramente aos clientes quando uma verificação não puder ser concluída.

Estado dos testes: Os testes incluídos usam transporte simulado e credenciais fictícias para verificar resultados válidos, inválidos e indisponíveis, rejeição CSRF, escape de HTML e intervalo entre envios. Simulam uma transferência falhada para testar os limites de tempo sem esperar pela rede. Não constituem um teste autenticado da API real. Execute-os ao adaptar o exemplo e verifique o ambiente de testes antes de aceitar envios de clientes reais.

1. Entenda o fluxo de solicitações

O navegador exibe um formulário HTML normal. Quando enviado, o IBAN e um token CSRF são transferidos da sessão para o seu aplicação PHP. O PHP verifica o token do formulário, delimita a entrada e remove os espaços em branco normais antes de solicitar a API. O navegador nunca se conecta diretamente ao IBAN-Test e não recebe o token ao portador.

O backend envia JSON para POST https://www.iban-test.eu/api/v2/iban/validate. Ele lê o status HTTP e os campos JSON, mapeia o resultado para uma mensagem de utilizador especificada e retorna outra página HTML. A interface está descrita no documentação da API IBAN-Test.

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

Mantenha essa divisão mesmo com uma customização AJAX: JavaScript pode chamar seu próprio aplicação, mas a autenticação para IBAN-Test permanece no servidor. Um token em um ficheiro JavaScript ou pacote minificado não é secreto.

2. Inicie o exemplo localmente

Descompacte o ficheiro ZIP e vá para o diretório demo. Verifique a versão do PHP e a extensão cURL usando php -v e php -m. Sessões e JSON também devem estar disponíveis. O compositor não é necessário. Primeiro, execute as verificações off-line incluídas:

php tests/run.php

Para testes reais de API, você precisará de um token da sua conta IBAN-Test. No Bash, use entrada oculta para que o valor não acabe no histórico do shell como um comando de texto simples:

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

Abra http://127.0.0.1:8080. O servidor escuta apenas no seu computador. Pare com Ctrl+C e execute unset IBAN_TEST_API_TOKEN. O servidor de desenvolvimento PHP é usado para este exercício local. Deixe public definido como raiz do documento para manter o cliente, os testes e o README fora do diretório fornecido.

Sem a variável de ambiente, o formulário ainda será carregado. Se a entrada for plausível, ela mostrará uma mensagem de indisponibilidade sem consultar a API. Solicitações reais de API exigem uma conta ativa e consomem quota.

3. Verifique previamente as entradas e proteja o formulário

O exemplo aceita uma cadeia de até 80 bytes, remove os espaços normais, converte as letras em maiúsculas e verifica um padrão básico de caracteres. Assim, rejeita entradas manifestamente inadequadas com pouco custo. Estas verificações não calculam a soma de controlo nem confirmam a validade do IBAN; o servidor continua a precisar do resultado da API.

Um token aleatório armazenado na sessão é enviado como um campo oculto e comparado quando enviado. Um token diferente é rejeitado antes da chamada da API. Há também um período de espera de três segundos entre entradas por sessão. Isso ajuda contra cliques repetidos, mas não é um limite de taxa produtiva, pois os utilizadors podem criar novas sessões.

Todos os valores inseridos no HTML são mascarados com htmlspecialchars, incluindo a entrada exibida novamente após um erro. A implementação escapa explicitamente das aspas e substitui sequências UTF-8 inválidas de acordo com Referência de mascaramento PHP. As respostas do navegador usam Cache-Control: no-store. Os cookies de sessão usam HttpOnly e SameSite; As opções são explicadas no Documentação de sessão PHP.

4. Envie uma solicitação de API limitada

O cliente lê IBAN_TEST_API_TOKEN no servidor e envia um cabeçalho Authorization: Bearer. O conteúdo da solicitação contém apenas o IBAN normalizado:

{"iban":"DE89370400440532013000"}

O objetivo é especificado no código. Os envios de formulário não podem selecionar um host. O certificado TLS e o nome do host ainda são verificados; Os redirecionamentos estão desativados. O estabelecimento da ligação está limitado a três segundos e toda a transmissão está limitada a oito segundos. Uma resposta acima de 64 KiB aborta a transmissão. As opções são descritas pelo Referência PHP cURL.

Não há repetição automática. Após um tempo limite, pode não ficar claro se o provedor processou a solicitação; As repetições podem consumir quota adicional. É por isso que a página mostra um erro temporário. Se o seu aplicação adicionar novas tentativas posteriormente, defina uma estratégia limitada que leve em consideração a latência e a quota.

5. Mostre o resultado correto

Verifique a transmissão bem-sucedida e os campos de resposta. Para este endpoint, o exemplo de acordo com códigos de resultado documentados cobre três casos:

• Válido: HTTP 200, o valor inteiro code: 2100 e o valor booleano error: false devem estar presentes juntos.
• Dados bancários inválidos: Uma resposta HTTP 200 construída corretamente com o código 3100, 3101 ou 3102 e o valor booleano error: true solicita correção. Respostas conflitantes com error: false são consideradas indisponíveis.
• Não disponível: Problemas de autenticação ou quota, diferentes valores de status HTTP, tempos limite, códigos desconhecidos e JSON inválido produzem uma mensagem de erro técnico.

Uma verificação indisponível não deve indicar ao cliente que o seu IBAN é inválido. O exemplo usa mensagens próprias em vez do texto original do fornecedor. Um resultado válido confirma a validação formal; não comprova a titularidade ou existência da conta nem o sucesso de um pagamento.

6. Prepare o aplicação para operação

Antes de publicar o formulário, exija autorização na aplicação e aplique um orçamento de quota partilhado entre utilizadores, sessões e instâncias. Nas compras como convidado, associe o acesso a uma sessão de compra autorizada pelo servidor e acrescente proteção contra abusos. O intervalo entre envios e a verificação CSRF não protegem, por si só, a quota paga.

Use HTTPS, cookies seguros, um servidor PHP de nível de produção e limites de tamanho de conteúdo de solicitação do lado do servidor. Configure explicitamente proxies confiáveis ​​quando o TLS encerrar o upstream. Forneça segredos sobre seu ambiente de hospedagem; PHP-FPM pode exigir configuração explícita do ambiente. Exclua tokens, conteúdo de solicitação de IBAN e detalhes confidenciais de erros de logs e monitoramento. Nunca publique uma página de diagnóstico que produza as variáveis ​​de ambiente.