Guia do Google Sheets
Validar IBAN no Google Sheets com Apps Script
Verifique uma coluna de IBAN selecionada no menu da folha de cálculo e obtenha um relatório separado com data e hora, estado de validação, banco e BIC. Descarregue o modelo, guarde o token da API e execute as verificações quando precisar.
Descarregue o pacote inicial do Google Sheets
O ZIP contém Code.gs, um manifesto Apps Script, instruções de configuração e testes locais. Não são necessárias bibliotecas, implementações ou suplementos da folha de cálculo. É necessária uma conta Google com permissão de edição e um token da API IBAN-Test.
Estado dos testes: O download passa em 46 testes locais do Node.js com serviços simulados do Apps Script. Limpeza duplicada, limites, tratamento de resposta, armazenamento de token, gravações interrompidas e mascaramento de fórmula são verificados. Nenhum teste foi realizado em uma conta real do Google Sheets ou com uma API autenticada. Comece com uma pequena tabela de teste antes de usar dados operacionais.
O que esta tabela verifica
A API verifica o formato e a soma de verificação do IBAN e complementa os dados disponíveis do diretório bancário. Um resultado válido não prova a titularidade da conta, a existência da conta, a capacidade da conta para efetuar pagamentos ou os fundos disponíveis. O escopo atual dos testes está descrito em documentação da API IBAN-Test.
O modelo usa um comando de menu explícito em IBAN-Test. A edição de uma célula não aciona uma solicitação cobrável. Cada passagem aceita um intervalo contíguo de uma coluna com até 500 linhas e um máximo de 10 IBANs diferentes e não vazios. Estes são limites de modelo, não o seu plano de conta.
Para consultas e detecção de duplicatas, os espaços são removidos e as letras são maiúsculas. As células originais permanecem inalteradas. IBANs repetidos compartilham uma consulta em uma execução, mas cada linha de origem aparece no relatório. As células vazias são ignoradas; Títulos e fórmulas devem ser excluídos da seleção.
1. Instale o modelo em uma folha de cálculo
- Para o primeiro teste, crie uma folha de cálculo privada do Google. Descarregue o ficheiro ZIP e descompacte-o.
- Em Google Sheets, abra Extensões → Apps Script. Substitua o conteúdo padrão de
Code.gspelo ficheiro baixado. Se o projeto já contém scripts necessários, use uma nova tabela para esta configuração. - No Apps Script, abra as Definições do projeto e ative a apresentação de appsscript.json no editor. Regresse ao editor e substitua esse ficheiro pelo manifesto incluído.
- Guarde o projeto e recarregue a folha de cálculo. A função
onOpendo script adiciona o menu IBAN-Test. O Google explica esse mecanismo no Guia de menu personalizado. - Selecione IBAN-Test → Save my API token (Armazenar token de API). Passar pela autorização do Google para a tabela atual e solicitações externas; execute o comando novamente, se necessário. Revise o script e as permissões solicitadas antes de permitir o acesso. As políticas do espaço de trabalho podem exigir assistência do administrador; consulte Documentação de autorização do Google.
- Cole o token da API da sua conta IBAN-Test na caixa de diálogo. Introduza apenas o token, sem
Bearer. A introdução não é ocultada: evite partilhar o ecrã enquanto escreve.
2. Selecione e verifique os IBANs
Insira um título como IBAN em A1. Formate as células de entrada como texto simples e insira os IBANs abaixo. Para uma primeira demonstração, use o exemplo documentado DE89370400440532013000, a variante com espaços DE89 3704 0044 0532 0130 00 e uma soma de verificação deliberadamente alterada como DE00370400440532013000.
Selecione apenas o intervalo de entrada preenchido, por exemplo A2:A4 e depois IBAN-Test → Validate selected IBANs (verifique os IBANs selecionados). Esta seleção contém dois valores normalizados diferentes, portanto o modelo tenta duas solicitações. Não selecione a coluna inteira, os títulos ou várias seções separadas. Não edite as células selecionadas durante a execução.
Depois que todas as consultas retornarem resultados reconhecidos, o script criará uma nova folha de cálculo. Seu nome começa com IBAN check, seguido pelo carimbo de data/hora UTC e pelo identificador curto. Abra-o e verifique a marca COMPLETE em A1. Os relatórios antigos permanecem instantâneos históricos e nunca são atualizados automaticamente.
3. Leia o relatório
O relatório contém nove colunas: Planilha de Origem, Linha de Origem, IBAN Original, IBAN Normalizado, Status, Código API, Nome do Banco, BIC e Horário de Verificação em UTC. Campos bancários vazios significam que nenhum valor foi entregue; eles não invalidam um IBAN válido.
Este exemplo resumido mostra o mapeamento de estado esperado quando a API fornece os códigos especificados. É para fins ilustrativos e não é um teste ao vivo autenticado:
| Linha de origem | Entrada | Código API | estado |
|---|---|---|---|
| 2 | DE89370400440532013000 | 2100 | VALID |
| 3 | DE89 3704 0044 0532 0130 00 | 2100 | VALID |
| 4 | DE00370400440532013000 | 3100 | INVALID |
O modelo aceita apenas VALID em HTTP 200, código 2100 e error: false. INVALID aplica-se apenas aos códigos 3100, 3101 ou 3102 com error: true. Autenticação, quota, erros de rede e respostas inesperadas interrompem o processo. Veja o códigos de resultado documentados.
Mantenha os tokens e os dados da tabela privados
Seu token é armazenado nas propriedades de script do utilizador atual, separado das células e do código-fonte. Cada contribuidor deve depositar seu próprio token. O Google documenta esse escopo em PropertiesService.
As propriedades do utilizador não protegem contra alterações maliciosas de script. Os editores de tabela também podem editar o script vinculado; o código modificado poderá acessar seu token na próxima vez que você executá-lo. Use o modelo apenas com editores confiáveis ou em uma tabela privada separada. O Google descreve essas relações de acesso no Guia para scripts vinculados.
O script envia IBANs normalizados para IBAN-Test por HTTPS. Os relatórios contêm os IBANs originais e estão sujeitos aos direitos de acesso à pasta de trabalho. Limite o compartilhamento e retenha relatórios apenas pelo tempo necessário. Remove my API token remove seu token armazenado localmente; Além disso, revogue um token comprometido em sua conta IBAN-Test.
Cotas, erros e novas tentativas
Não há novas tentativas automáticas ou cache em várias execuções. Uma nova execução verifica novamente cada valor diferente. As solicitações concluídas antes de um erro podem já ter esgotado a quota. O script usa Google URL Fetch; o quotas e limites de execução do Apps Script também se aplica.
- Erro de token ou acesso: Verifique o status do token e da conta antes de reiniciar.
- Limite de quota ou taxa: Aguarde até que as solicitações sejam permitidas novamente. Preste atenção aos intervalos de repetição especificados e não clique continuamente no comando do menu.
- Rede, erro de servidor ou resposta ilegível: Espere e refaça a pequena seleção manualmente. Erros permanentes devem ser investigados.
- Nenhum menu ou acesso negado: Guarde o script, recarregue as folha de cálculos e verifique os direitos de edição e restrições do espaço de trabalho.
Uma verificação interrompida não produz um novo relatório completo. Uma gravação interrompida pode deixar uma folha de cálculo incompleta: descarte-a e nunca use um relatório mais antigo para substituir a execução com falha. O script protege contra substituição de entrada, execuções simultâneas de script e fórmulas injetadas em textos de saída.