Gabriel-Richard-dev · Oct 16, 2026 · Oct 16, 2026
diff --git a/pages/api/banks/v1/index.js b/pages/api/banks/v1/index.js
@@ -1,10 +1,53 @@
 import app from '@/app';
+import BadRequestError from '@/errors/BadRequestError';
 import { getBanksData } from '@/services/banco-central';
 
+const MAX_SEARCH_LENGTH = 100;
+
+const normalize = (text) =>
+  String(text ?? '')
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .trim();
+
+const parseSearch = (search) => {
+  const term = typeof search === 'string' ? normalize(search) : '';
+
+  if (!term || term.length > MAX_SEARCH_LENGTH) {
+    throw new BadRequestError({
+      message: `O parâmetro search deve ser um texto entre 1 e ${MAX_SEARCH_LENGTH} caracteres`,
+      type: 'BANK_SEARCH_INVALID',
+    });
+  }
+
+  return term;
+};
+
+const matchesSearch = (bank, term) => {
+  if (/^\d+$/.test(term)) {
+    return bank.code === Number(term) || String(bank.ispb).includes(term);
+  }
+
+  return (
+    normalize(bank.name).includes(term) ||
+    normalize(bank.fullName).includes(term)
+  );
+};
+
 const action = async (request, response) => {
+  const { search } = request.query;
+  const term = search === undefined ? null : parseSearch(search);
+
   const allBanksData = await getBanksData();
 
-  return response.status(200).json(allBanksData);
+  if (term === null) {
+    return response.status(200).json(allBanksData);
+  }
+
+  return response
+    .status(200)
+    .json(allBanksData.filter((bank) => matchesSearch(bank, term)));
 };
 
 export default app().get(action);
diff --git a/pages/docs/doc/bank.json b/pages/docs/doc/bank.json
@@ -10,7 +10,34 @@
       "get": {
         "tags": ["BANKS"],
         "summary": "Retorna informações de todos os bancos do Brasil",
-        "description": "Retorna uma lista com os dados de todos os bancos. Exemplo de uso: `GET https://brasilapi.com.br/api/banks/v1`.",
+        "description": "Retorna uma lista com os dados de todos os bancos. Use o parâmetro opcional `search` para filtrar por trecho do nome (sem diferenciar maiúsculas e acentos), código bancário ou ISPB. Exemplos de uso: `GET https://brasilapi.com.br/api/banks/v1` e `GET https://brasilapi.com.br/api/banks/v1?search=inter`.",
+        "parameters": [
+          {
+            "name": "search",
+            "in": "query",
+            "description": "Termo de busca (1 a 100 caracteres). Textos são comparados com `name` e `fullName` ignorando maiúsculas e acentos; termos numéricos são comparados com `code` (igualdade) e `ispb` (trecho). Sem resultados, retorna lista vazia.",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 100
+            },
+            "examples": {
+              "nome": {
+                "summary": "Trecho do nome",
+                "value": "pagamentos"
+              },
+              "codigo": {
+                "summary": "Código bancário",
+                "value": "260"
+              },
+              "ispb": {
+                "summary": "ISPB",
+                "value": "18236120"
+              }
+            }
+          }
+        ],
         "responses": {
           "200": {
             "description": "Success",
@@ -32,6 +59,20 @@
                 ]
               }
             }
+          },
+          "400": {
+            "description": "O parâmetro search é inválido",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorMessage"
+                },
+                "example": {
+                  "message": "O parâmetro search deve ser um texto entre 1 e 100 caracteres",
+                  "type": "BANK_SEARCH_INVALID"
+                }
+              }
+            }
           }
         }
       }

diff --git a/tests/banks-v1.test.js b/tests/banks-v1.test.js
@@ -117,4 +117,91 @@ describe('banks v1 (E2E)', () => {
     expect(firstBank).toEqual(validOutputSchema);
     validateOptionalAddressFields(firstBank);
   });
+
+  describe('GET /banks/v1?search=', () => {
+    const search = (term) =>
+      axios.get(`${global.SERVER_URL}/api/banks/v1`, {
+        params: { search: term },
+      });
+
+    const normalize = (text) =>
+      String(text ?? '')
+        .normalize('NFD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase();
+
+    test('Busca por trecho do nome sem diferenciar maiúsculas e acentos', async () => {
+      const [{ data: allBanks }, response] = await Promise.all([
+        axios.get(`${global.SERVER_URL}/api/banks/v1`),
+        search('Pagamentos'),
+      ]);
+
+      expect(response.status).toBe(200);
+      expect(Array.isArray(response.data)).toBe(true);
+      expect(response.data.length).toBeGreaterThan(0);
+      expect(response.data.length).toBeLessThan(allBanks.length);
+      expect(response.data.map(({ code }) => code)).toContain(260);
+
+      response.data.forEach((bank) => {
+        expect(bank).toEqual(validOutputSchema);
+        const matches =
+          normalize(bank.name).includes('pagamentos') ||
+          normalize(bank.fullName).includes('pagamentos');
+        expect(matches).toBe(true);
+      });
+
+      const { data: accented } = await search('PAGAMÉNTOS');
+      expect(accented).toEqual(response.data);
+    });
+
+    test('Busca por código bancário', async () => {
+      const response = await search('260');
+
+      expect(response.status).toBe(200);
+      expect(response.data.length).toBeGreaterThan(0);
+      expect(response.data.map(({ ispb }) => ispb)).toContain('18236120');
+      response.data.forEach((bank) => {
+        expect(bank.code === 260 || bank.ispb.includes('260')).toBe(true);
+      });
+    });
+
+    test('Busca por ISPB', async () => {
+      const response = await search('18236120');
+
+      expect(response.status).toBe(200);
+      expect(response.data.map(({ code }) => code)).toContain(260);
+    });
+
+    test('Busca sem resultados retorna lista vazia', async () => {
+      const response = await search('banco-que-nao-existe-xyz');
+
+      expect(response.status).toBe(200);
+      expect(response.data).toEqual([]);
+    });
+
+    test.each([
+      ['vazio', ''],
+      ['só espaços', '   '],
+      ['longo demais', 'a'.repeat(101)],
+    ])('Parâmetro search %s retorna 400', async (_, term) => {
+      await expect(search(term)).rejects.toMatchObject({
+        response: {
+          status: 400,
+          data: { type: 'BANK_SEARCH_INVALID' },
+        },
+      });
+    });
+
+    test('Parâmetro search repetido retorna 400', async () => {
+      await expect(
+        axios.get(`${global.SERVER_URL}/api/banks/v1?search=a&search=b`)
+      ).rejects.toMatchObject({ response: { status: 400 } });
+    });
+
+    test('Verifica CORS', async () => {
+      const response = await search('inter');
+
+      expect(response.headers['access-control-allow-origin']).toBe('*');
+    });
+  });
 });