Topics

#banco-central #bancos #brasil #brazilian-banks #compe #fintech #ispb #logos #open-finance #pix

Language breakdown

TypeScript 97.3%

JavaScript 2.7%

▸ Files click to expand

README

logos-bancos-br

Dataset + logos das instituições financeiras e de pagamento do Brasil — bancos, fintechs,

IPs e cooperativas — sempre atualizados. Tudo derivado de três fontes 100% oficiais e

nomeadas: a lista de participantes do STR e a lista de participantes ativos do Pix,

ambas do Banco Central do Brasil, e o **diretório de participantes do Open Finance

Brasil**. Reconstruído automaticamente toda semana por CI, com proveniência verificável por

logo. English version

Banco do Brasil Caixa Bradesco Santander Itaú Nubank Inter Sicredi Sicoob Mercado Pago

→ galeria interativa (busca por nome/COMPE/ISPB + copiar URL de CDN) · PREVIEW.md

O que este pacote entrega

A lista de instituições — atualizada automaticamente, em dois conjuntos. A **lista

principal (data/bancos.json) traz as 470 instituições com código COMPE da lista de participantes do STR do Banco Central. As 643 instituições só-Pix** (fintechs, IPs e cooperativas afiliadas, sem COMPE) ficam num conjunto separado (data/instituicoes-pix.json), mantendo a lista principal enxuta. Ambos trazem nomes oficiais, ISPB, CNPJ (só-Pix) e os atributos de participação no Pix.

Logos oficiais, sem duplicação. 473 instituições com logo usando **160 arquivos

distintos** (~1,7 MB): afiliadas de sistemas cooperativos de marca única (Sicoob, Sicredi, Cresol, Unicred) compartilham um único arquivo por sistema e são marcadas com logo.source.type: "brand". Logos próprios vêm do diretório público do **Open Finance Brasil (openfinance) ou do site oficial da instituição** (direct-uri, com curadoria visual). Cada arquivo carrega proveniência: URI, SHA-256 e data.

Atualização automática, do BCB ao npm. Toda segunda-feira um GitHub Action

(update-logos.yml) reconstrói a lista e os logos a partir das fontes. Mudanças só de dados (inclusões, renomeações e exclusões feitas pelo BCB) são validadas por testes, mergeadas e publicadas no npm automaticamente; qualquer troca de logo abre um PR com o diff visual para revisão humana antes de publicar.

Uso em qualquer stack. API JavaScript/TypeScript, mapa pronto para React Native, CLI que

copia os assets para projetos Flutter/Kotlin/Swift/.NET/PHP, URLs de CDN sem instalar nada — ou só o JSON.

Quem já usa

BrasilAPI — o endpoint /banks/v1

serve o campo logo_url apontando para os logos deste pacote.

Listado no awesome-brazil-data.

Por que fontes oficiais?

Listas mantidas manualmente envelhecem: o BCB inclui, renomeia e exclui instituições ao longo do ano, e os bancos redesenham suas marcas. As bibliotecas existentes ou trazem só dados (sem logos), ou logos coletados de sites variados, sem rastreabilidade. A abordagem aqui:

Fontes oficiais, e apenas elas — os CSVs de participantes do STR e do Pix (que o próprio

BCB atualiza diariamente), o diretório de participantes do Open Finance Brasil e, para quem não participa do Open Finance, o ícone que a própria instituição publica no site oficial dela (revisado à mão). Nenhuma imagem "achada no Google" ou de agregador. Quem quiser só a fonte Open Finance filtra: banks().filter(b => b.logo?.source.type === 'openfinance').

Proveniência por logo — data/bancos.json registra a URI de origem, o SHA-256 do arquivo

original e a data de cada logo. O diff do git é a auditoria.

Correspondência segura — match automático somente por ISPB (= raiz do CNPJ).

Semelhança de nome nunca atribui logo sozinha: vira sugestão para revisão humana. Em contexto bancário, logo errado é pior que logo nenhum.

Assets seguros — download só via https com teto de tamanho e de pixels; SVGs

redistribuídos apenas após sanitização (sem script, event handlers, foreignObject ou referências externas).

Trade-off honesto — 473 das 1.113 instituições têm logo (participantes do Open Finance,

afiliadas dos sistemas cooperativos e ~45 instituições cobertas pelos sites oficiais — a esmagadora maioria das contas do país). As demais são SCDs/corretoras/IPs pequenas; para elas seu app usa o fallback que preferir — e a cobertura cresce a cada release.

As fontes, para conferência

Os mesmos endereços públicos que o pipeline consome — qualquer pessoa pode verificar:

| Fonte | Publicador | O que fornece | Consulta | |---|---|---|---| | Lista de participantes do STR | Banco Central do Brasil | ISPB, código COMPE e nomes oficiais (lista principal) | página · CSV | | Lista de participantes ativos do Pix | Banco Central do Brasil | Instituições do Pix (inclusive sem COMPE), CNPJ e atributos de participação | página (o CSV diário é linkado nela) | | Diretório de participantes | Open Finance Brasil | Logo publicado pela própria instituição, identificado por CNPJ | JSON público |

O campo logo.source.uri de cada logo em data/bancos.json aponta o arquivo exato baixado, com SHA-256 e data.

Instalação e uso

npm install logos-bancos-br

Requer Node ≥ 20 para uso via Node/CLI (em web e React Native vale o ambiente do seu bundler). Zero dependências de runtime. Publicado com npm provenance — verifique a integridade com npm audit signatures.

Os arquivos são nomeados pelo ISPB (8 dígitos, estável e universal — é o que permite cobrir as ~640 instituições do Pix que não têm código COMPE). As consultas aceitam COMPE ou ISPB.

JavaScript / TypeScript (Node ou web)

import { banks, pixInstitutions, allInstitutions, byCompe, byIspb, logoCdnUrl } from 'logos-bancos-br';
banks();             // lista principal: 470 instituições com COMPE pixInstitutions();   // conjunto separado: 643 só-Pix (fintechs, IPs, afiliadas) allInstitutions();   // as duas juntas (1.113)
byCompe(341);        // { ispb: '60701190', compe4: '0341', name: 'Itaú Unibanco S.A.', logo: {...} } byCompe('0260');     // Nubank — '260', 260 e '0260' são equivalentes byIspb('00000000');  // Banco do Brasil byIspb('11275560');  // RecargaPay — só-Pix; byIspb resolve nos DOIS conjuntos
logoCdnUrl(341);     // https://cdn.jsdelivr.net/npm/logos-bancos-br@x.y.z/logos/png/60701190.png
// Atributos de participação no Pix (verbatim da lista do BCB): byCompe(341)?.pix;   // { spiParticipationType: 'Direta', pixParticipationType: 'Obrigatória', ... }

React (web)

import { logoCdnUrl } from 'logos-bancos-br';
<img src={logoCdnUrl(banco.codigo) ?? iconeGenerico} width={40} alt={banco.nome} />

React Native (Expo / Metro)

import logos from 'logos-bancos-br/react-native'; // mapa require() estático
<Image source={logos[codigoBanco.padStart(4, '0')]} style={{ width: 40, height: 40 }} />

As chaves do mapa aceitam o COMPE com 4 dígitos ('0341') e o ISPB ('60701190';

instituições só-Pix aparecem apenas pelo ISPB; afiliadas apontam para o asset compartilhado do

sistema). Importar esse entry adiciona os 160 logos distintos (~1,7 MB) ao bundle. Se

preferir empacotar só alguns, use o CLI abaixo e faça require() dos arquivos copiados.

Node (caminho dos arquivos no disco)

import { logoPngPath, logoSvgPath } from 'logos-bancos-br/node';
logoPngPath('341'); // /…/node_modules/logos-bancos-br/logos/png/60701190.png

Qualquer stack (Flutter, Kotlin, Swift, PHP, .NET…)

Vendorize os assets no seu projeto — sem dependência de runtime:

npx logos-bancos-br copy --dest ./assets/banks            # 0341.png, ... (por COMPE; só-Pix ficam de fora)
npx logos-bancos-br copy --dest ./assets/banks --by ispb  # 60701190.png, ... (todas, incl. só-Pix)
npx logos-bancos-br copy --dest ./assets/banks --format both --only 341,001,260
npx logos-bancos-br list                                  # tabela COMPE · ISPB · nome · tem logo

Rode de novo a cada atualização do pacote para receber lista e logos novos.

CDN — sem instalar nada

O caminho é sempre logos/{png|svg}/{ispb}.{png|svg}:

https://cdn.jsdelivr.net/npm/logos-bancos-br@0/logos/png/60701190.png
https://cdn.jsdelivr.net/npm/logos-bancos-br@0/logos/svg/18236120.svg

@0 acompanha automaticamente a versão mais recente da série 0.x — os logos e os dados ficam frescos sem você publicar nada (a atualização semanal vira release sozinha). Prefere imutabilidade? Fixe a versão exata (ex.: @0.5.0).

Para resolver COMPE→ISPB, nome oficial e existência de logo em qualquer stack, sem instalar nada, há um índice compacto (~60 KB, ~15 KB gzip):

https://cdn.jsdelivr.net/npm/logos-bancos-br@0/data/cdn-index.min.json

Formato: {"institutions": {"60701190": ["341", "Itaú Unibanco S.A.", 3]}} — cada entrada é [compe, nome, flags], com flags 0 = sem logo, 1 = só PNG, 3 = PNG+SVG. Afiliadas de sistemas cooperativos compartilham o arquivo do sistema: nesses casos há um 4º elemento com o ISPB do arquivo, que é o que deve entrar na URL (ex.: ["16", "…SICOOB CREDITRAN", 3, "04891850"] → logos/svg/04891850.svg).

E se você só quer a URL do logo pronta por ISPB, sem montar caminho nem escolher formato, há um mapa já resolvido ({ISPB: url}, SVG quando existe senão PNG, só quem tem logo):

https://cdn.jsdelivr.net/npm/logos-bancos-br@0/data/logo-urls.min.json

Aí o consumo é direto: logoUrl = mapa[ispb] (ou null se não tiver).

Só os dados

import bancos from 'logos-bancos-br/data/bancos.json';            // lista principal (COMPE)
import soPix from 'logos-bancos-br/data/instituicoes-pix.json';   // só-Pix (sem COMPE)

Referência rápida da API

| Import | Função | Retorna | |---|---|---| | logos-bancos-br | banks() | lista principal — instituições com COMPE (Bank[]) | | | pixInstitutions() | só-Pix, sem COMPE (PixInstitution[]) | | | allInstitutions() | os dois conjuntos (Institution[]) | | | byCompe(codigo) | Bank \| undefined — 341, '341' e '0341' são equivalentes | | | byIspb(ispb) | Institution \| undefined — resolve nos dois conjuntos | | | findBank(codigo) | Institution \| undefined — mais de 4 dígitos trata como ISPB | | | logoCdnUrl(codigo, { format?, version? }) | URL do jsDelivr, ou null se não houver logo | | | normalizeCompe(x) · normalizeIspb(x) | '0341' · '60701190' | | | version | versão do pacote (string) | | logos-bancos-br/node | logoPngPath(codigo) · logoSvgPath(codigo) | caminho absoluto do asset, ou null | | | copyLogos({ dest, format?, by?, only? }) | copia os assets para um diretório (o que o CLI usa) | | logos-bancos-br/react-native | logos (default export) | mapa require() com chaves COMPE4 e ISPB |

Tipos TypeScript exportados: Bank, PixInstitution, Institution, BankLogo, BankLogoSource, PixInfo.

O dataset

Um registro de data/bancos.json:

{
  "ispb": "60701190",
  "compe": "341",
  "compe4": "0341",
  "name": "Itaú Unibanco S.A.",
  "shortName": "ITAÚ UNIBANCO S.A.",
  "pix": {
    "spiParticipationType": "Direta",
    "pixParticipationType": "Obrigatória",
    "modality": "Provedor de Conta Transacional",
    "institutionType": "Banco Múltiplo",
    "authorizedByBcb": true
  },
  "logo": {
    "png": "logos/png/60701190.png",
    "svg": "logos/svg/60701190.svg",
    "source": {
      "type": "openfinance",
      "org": "ITAU UNIBANCO S.A.",
      "cnpj": "60701190000104",
      "uri": "https://www.itau.com.br/…/Novo_itau.svg",
      "sha256": "…",
      "updatedAt": "2026-07-17"
    }
  }
}

logo.png — PNG normalizado 256×256, fundo transparente, fit: contain.
logo.svg — vetor original, presente só quando passa na sanitização.
logo.source — proveniência completa: de onde veio, hash e quando mudou. source.type:

openfinance (diretório Open Finance, match automático por ISPB ou revisado), direct-uri (URL no site oficial da instituição, revisada à mão) ou override (arte mantida no repo).

logo: null — instituição sem logo nas fontes oficiais (use seu fallback).
logo.source.type: "brand" — logo herdado do sistema cooperativo (campo brand diz qual,

ex.: "SICOOB"); o arquivo é compartilhado entre as afiliadas do sistema.

pix — atributos verbatim da lista de participantes ativos do Pix do BCB; null quando a

instituição não é participante ativa.

Em instituicoes-pix.json, cada registro tem compe: null, cnpj (14 dígitos) e pix

sempre presente.

Como funciona a atualização automática

Espinha dorsal: a união, por ISPB, de dois CSVs públicos do Banco Central — a lista de

participantes do STR (ParticipantesSTR.csv: ISPB + COMPE + nomes oficiais) e a **lista de participantes ativos do Pix** (arquivo diário datado, que acrescenta as instituições sem COMPE e os atributos de participação). Ambos atualizados diariamente pelo BCB.

Logos: o diretório público de participantes do Open Finance Brasil traz, por CNPJ, o logo

que cada instituição publica para ser exibido por terceiros.

Ponte: ISPB == 8 primeiros dígitos do CNPJ (é assim que o BCB os atribui na esmagadora

maioria dos casos). Quando não bate — segundas marcas como XP CCTVM, Nu Invest, Bradesco BBI — entra o forcedMatches, revisado à mão a partir das sugestões do relatório.

Sistemas cooperativos: afiliadas que carregam a marca do sistema no nome oficial

(Sicoob, Sicredi, Cresol, Unicred) recebem o logo do sistema por regra curada — explícita e auditável, não semelhança fuzzy — e compartilham um único arquivo por marca (nada de centenas de cópias do mesmo PNG).

Fora do Open Finance: ferramentas de descoberta (npm run discover e discover:ai)

acham o ícone publicado no site oficial da instituição; nada entra sem curadoria visual (o revisor confere marca e domínio) — aprovados viram forcedUris.

Normalização: cada arte vira PNG 256×256; o SVG original é mantido quando seguro.
Cadência: o workflow roda toda segunda-feira (e sob demanda), regenera

data/bancos.json, logos/, PREVIEW.md e react-native.js, e abre um PR com o relatório e o diff visual dos PNGs. Diffs só de dados passam por testes e são **mergeados e publicados no npm automaticamente**; diffs que alteram logos aguardam revisão visual humana — e o release após o merge é automático. Nada é editado à mão.

Detalhes de manutenção (rodar o pipeline localmente, promover sugestões, overrides, denylist): CONTRIBUTING.md.

Limitações conhecidas

Cobertura de logos: 473 de 1.113 instituições (153 na lista principal; o restante são

afiliadas com logo de sistema e só-Pix); cresce conforme o ecossistema e a curadoria. **Sua instituição está sem logo?** Abra uma issue com o template "Sugestão de match"/"Adicionar logo" apontando a URL no domínio oficial — promovemos rápido.

Algumas instituições publicam no diretório o logo da sua marca de produto (ex.: Banco CSF →

cartão Atacadão). É a escolha oficial da própria instituição; se preferir outra arte no seu app, use um override local seu.

Instituições em processo de adesão ao Pix (segunda seção da lista do BCB) e participantes

sem ISPB publicado (18 hoje) não entram — só participantes ativos com ISPB.

Marcas e remoção

Os logos são marcas das respectivas instituições financeiras e não são cobertos pela licença MIT deste repositório. Eles são redistribuídos para uso nominativo (identificar a instituição em interfaces), a partir de artes que as próprias instituições publicam no diretório público do Open Finance Brasil. Detalhes e base de uso: DISCLAIMER.md.

Representa uma instituição e quer corrigir ou remover um logo? Abra uma issue com o template "Remoção de marca" — removemos prontamente.

Para ferramentas e assistentes de IA

Um resumo machine-readable do projeto está em llms.txt (também incluído no pacote npm). Fatos-chave: **a lista de instituições e os logos são regenerados automaticamente toda semana** a partir do Banco Central (STR) e do Open Finance Brasil; arquivos nomeados por ISPB; consultas por COMPE ou ISPB; dataset completo em data/bancos.json.

Licença

Código e dataset sob MIT. Logos: ver DISCLAIMER.md.

🔗 More in this category