logos-bancos-br 0.2.0 → 0.4.0

package/README.en.md

@@ -1,8 +1,10 @@
 # logos-bancos-br
 
-> **Brazilian bank list + official logos, always up to date.** Everything is derived from
-> official sources only (Central Bank of Brazil and Open Finance Brasil) and **rebuilt
-> automatically every week by CI** — with verifiable per-logo provenance.
+> **Dataset + logos of Brazil's financial and payment institutions** — banks, fintechs, payment
+> institutions and credit unions — **always up to date**. Everything is derived from three named
+> official sources: the **STR participants list** and the **active Pix participants list**, both
+> from the **Central Bank of Brazil (BCB)**, plus the **Open Finance Brasil participants
+> directory**. Rebuilt automatically every week by CI, with verifiable per-logo provenance.
 > **[Versão em português](README.md)**
 
 [![CI](https://github.com/rzmt/logos-bancos-br/actions/workflows/ci.yml/badge.svg)](https://github.com/rzmt/logos-bancos-br/actions/workflows/ci.yml)
@@ -28,15 +30,18 @@
 
 ## What this package gives you
 
-1. **The list of institutions — auto-updated.** Every institution with a COMPE code in the
-   Central Bank of Brazil STR participants list (currently 470), with official name, short name,
-   COMPE code and ISPB, in [`data/bancos.json`](data/bancos.json). You never hand-maintain a
-   bank list again.
-2. **Official logos.** Currently 152, as 256×256 PNGs (+ SVG when available), from two origins —
-   both official and identified in the dataset (`logo.source.type`): the public **Open Finance
-   Brasil** directory (`openfinance`), where each institution publishes its own brand, and the
-   **institution's own official website** (`direct-uri`), visually curated before shipping.
-   Every file carries provenance: source URI, SHA-256 and date.
+1. **The list of institutions — auto-updated, in two sets.** The **main list**
+   ([`data/bancos.json`](data/bancos.json)) carries the **470 institutions with a COMPE code**
+   from the Central Bank STR participants list. The **643 Pix-only institutions** (fintechs,
+   payment institutions, cooperative affiliates — no COMPE) live in a separate dataset
+   ([`data/instituicoes-pix.json`](data/instituicoes-pix.json)) — the main list stays clean,
+   and the full Pix universe is one import away.
+2. **Official logos, deduplicated.** **473 institutions with a logo** backed by **160 distinct
+   files** (~1.7 MB): affiliates of single-brand cooperative systems (Sicoob, Sicredi, Cresol,
+   Unicred) **share one file per system**, marked `logo.source.type: "brand"`. Own logos come
+   from the public **Open Finance Brasil** directory (`openfinance`) or the **institution's own
+   official website** (`direct-uri`, visually curated). Every file carries provenance: source
+   URI, SHA-256 and date.
 3. **Automatic updates, no manual curation.** Every Monday a GitHub Action
    ([`update-logos.yml`](.github/workflows/update-logos.yml)) rebuilds **both the list AND the
    logos** from the sources and opens a PR with the visual diff. A bank created, renamed or
@@ -45,15 +50,15 @@
    copies the assets into Flutter/Kotlin/Swift/.NET/PHP projects, CDN URLs with no install — or
    just the JSON.
 
-## Why not a hand-maintained list?
+## Why official sources?
 
-Because it rots: the Central Bank adds, renames and removes institutions throughout the year,
-and banks redesign their brands. Existing libraries ship either **data only** (no logos) or
-logos **hand-collected** from assorted websites with no traceability. The approach here:
+Hand-maintained lists rot: the Central Bank adds, renames and removes institutions throughout
+the year, and banks redesign their brands. Existing libraries ship either **data only** (no
+logos) or logos **collected from assorted websites** with no traceability. The approach here:
 
-- **Official sources, and only them** — the STR participants CSV (updated daily by the Central
-  Bank itself), the Open Finance Brasil participants directory and, for non-participants, the
-  icon the institution publishes **on its own official website** (hand-reviewed). No images
+- **Official sources, and only them** — the STR and Pix participants CSVs (updated daily by the
+  Central Bank itself), the Open Finance Brasil participants directory and, for non-participants,
+  the icon the institution publishes **on its own official website** (hand-reviewed). No images
   "found on Google" or from aggregators. Open Finance purists can filter:
   `banks().filter(b => b.logo?.source.type === 'openfinance')`.
 - **Per-logo provenance** — `data/bancos.json` records each logo's source URI, SHA-256 of the
@@ -63,10 +68,10 @@ logos **hand-collected** from assorted websites with no traceability. The approa
   In a banking context, a wrong logo is worse than no logo.
 - **Safe assets** — https-only downloads with size/pixel caps; SVGs redistributed only after
   sanitization (no scripts, event handlers, `foreignObject` or external references).
-- **Honest trade-off** — 152 of the 470 institutions have a logo (all Open Finance participants
-  plus ~45 banks/payment institutions covered via official sites — the vast majority of accounts
-  in Brazil). The rest are small credit unions/SCDs/brokers — your app picks the fallback, and
-  coverage grows every release.
+- **Honest trade-off** — 473 of the 1,113 institutions have a logo (Open Finance participants,
+  cooperative-system affiliates and ~45 institutions covered via official sites — the vast
+  majority of accounts in Brazil). The rest are small SCDs/brokers/payment institutions — your
+  app picks the fallback, and coverage grows every release.
 
 ## Install & use
 
@@ -78,7 +83,10 @@ Requires **Node ≥ 20** for Node/CLI usage (web and React Native follow your bu
 environment). Zero runtime dependencies. Published with **npm provenance** — verify integrity
 with `npm audit signatures`.
 
-Files are named by **ISPB** (8 digits). Lookups accept **COMPE or ISPB**.
+Files are named by **ISPB** (8 digits). `banks()` is the main list (COMPE holders);
+`pixInstitutions()` is the separate Pix-only set; `allInstitutions()` is both; `byIspb()`
+resolves across the two. Each institution carries a `pix` block (participation attributes,
+verbatim from the BCB list) or `null`.
 
 ```ts
 import { banks, byCompe, byIspb, logoCdnUrl } from 'logos-bancos-br';
@@ -88,8 +96,9 @@ byIspb('00000000');  // Banco do Brasil
 logoCdnUrl(341);     // https://cdn.jsdelivr.net/npm/logos-bancos-br@x.y.z/logos/png/60701190.png
 ```
 
-**React Native (Expo/Metro)** — static require() map (bundles all logos, ~1.3 MB; keys accept
-both the 4-digit COMPE and the 8-digit ISPB):
+**React Native (Expo/Metro)** — static require() map (bundles the 160 distinct logos, ~1.7 MB; keys accept both
+the 4-digit COMPE and the 8-digit ISPB — Pix-only institutions by ISPB only; affiliates point at
+the shared system asset):
 
 ```tsx
 import logos from 'logos-bancos-br/react-native';
@@ -113,23 +122,26 @@ npx logos-bancos-br list
 **CDN, no install** (always pin a version):
 
 ```
-https://cdn.jsdelivr.net/npm/logos-bancos-br@0.1.0/logos/png/60701190.png
+https://cdn.jsdelivr.net/npm/logos-bancos-br@0.3.0/logos/png/60701190.png
 ```
 
-**Data only** (the bank list):
+**Data only**:
 
 ```ts
-import data from 'logos-bancos-br/data/bancos.json';
+import banks from 'logos-bancos-br/data/bancos.json';          // main list (COMPE)
+import pixOnly from 'logos-bancos-br/data/instituicoes-pix.json'; // Pix-only
 ```
 
 ### API quick reference
 
 | Import | Function | Returns |
 |---|---|---|
-| `logos-bancos-br` | `banks()` | every institution (`Bank[]`) |
+| `logos-bancos-br` | `banks()` | main list — COMPE institutions (`Bank[]`) |
+| | `pixInstitutions()` | Pix-only set (`PixInstitution[]`) |
+| | `allInstitutions()` | both sets (`Institution[]`) |
 | | `byCompe(code)` | `Bank \| undefined` — `341`, `'341'` and `'0341'` are equivalent |
-| | `byIspb(ispb)` | `Bank \| undefined` |
-| | `findBank(code)` | `Bank \| undefined` — more than 4 digits is treated as ISPB |
+| | `byIspb(ispb)` | `Institution \| undefined` — resolves across both sets |
+| | `findBank(code)` | `Institution \| undefined` — more than 4 digits is treated as ISPB |
 | | `logoCdnUrl(code, { format?, version? })` | jsDelivr URL, or `null` when there is no logo |
 | | `normalizeCompe(x)` · `normalizeIspb(x)` | `'0341'` · `'60701190'` |
 | | `version` | package version (string) |
@@ -137,7 +149,7 @@ import data from 'logos-bancos-br/data/bancos.json';
 | | `copyLogos({ dest, format?, by?, only? })` | copies assets into a directory (what the CLI uses) |
 | `logos-bancos-br/react-native` | `logos` (default export) | require() map keyed by COMPE4 **and** ISPB |
 
-Exported TypeScript types: `Bank`, `BankLogo`, `BankLogoSource`.
+Exported TypeScript types: `Bank`, `PixInstitution`, `Institution`, `BankLogo`, `BankLogoSource`, `PixInfo`.
 
 ## Dataset shape
 
@@ -148,6 +160,7 @@ Exported TypeScript types: `Bank`, `BankLogo`, `BankLogoSource`.
   "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",
@@ -157,13 +170,18 @@ Exported TypeScript types: `Bank`, `BankLogo`, `BankLogoSource`.
 ```
 
 `logo.png` is a normalized transparent 256×256 PNG; `logo.svg` is the original vector when safely
-redistributable; `logo: null` means the institution has no logo in the official sources.
+redistributable; `logo: null` means no logo in the official sources; `logo.source.type: "brand"`
+marks a logo inherited from the institution's cooperative system (shared asset, `brand` says
+which); `pix: null` marks a non-Pix participant. Pix-only records (separate dataset) always have
+`compe: null`, a 14-digit `cnpj` and a `pix` block.
 
 ## How the auto-update works
 
-The pipeline joins the STR list (which institutions exist) with the Open Finance directory
-(their logos), bridged by `ISPB == first 8 digits of the CNPJ`; hand-reviewed `forcedMatches`
-cover second brands (XP CCTVM, Nu Invest, Bradesco BBI…). For institutions outside Open Finance,
+The pipeline unions the Central Bank's STR and active-Pix participants lists (which institutions
+exist, keyed by ISPB) and joins them with the Open Finance directory (their logos), bridged by
+`ISPB == first 8 digits of the CNPJ`; hand-reviewed `forcedMatches` cover second brands (XP
+CCTVM, Nu Invest, Bradesco BBI…), and a curated brand rule gives cooperative-system affiliates
+(Sicoob/Sicredi/Cresol/Unicred) their system's logo. For institutions outside Open Finance,
 discovery tools (`npm run discover` / `discover:ai`) find the icon published on the institution's
 official website — nothing ships without visual curation (brand + domain reviewed); approvals
 become `forcedUris` (`source.type: "direct-uri"`). The weekly workflow regenerates

package/README.md

@@ -1,8 +1,11 @@
 # logos-bancos-br
 
-> **Lista de bancos brasileiros + logos oficiais, sempre atualizados.** Tudo derivado de fontes
-> 100% oficiais (Banco Central e Open Finance Brasil) e **reconstruído automaticamente toda
-> semana por CI** — com proveniência verificável por logo. **[English version](README.en.md)**
+> **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](README.en.md)**
 
 [![CI](https://github.com/rzmt/logos-bancos-br/actions/workflows/ci.yml/badge.svg)](https://github.com/rzmt/logos-bancos-br/actions/workflows/ci.yml)
 [![atualização](https://github.com/rzmt/logos-bancos-br/actions/workflows/update-logos.yml/badge.svg)](https://github.com/rzmt/logos-bancos-br/actions/workflows/update-logos.yml)
@@ -27,15 +30,20 @@
 
 ## O que este pacote entrega
 
-1. **A lista de instituições — atualizada automaticamente.** Todas as instituições com código
-   COMPE da lista de participantes do STR do **Banco Central** (hoje 470), com nome oficial,
-   nome reduzido, código COMPE e ISPB, em [`data/bancos.json`](data/bancos.json). Você nunca
-   mais mantém uma lista de bancos à mão.
-2. **Logos oficiais.** Hoje 152, em PNG 256×256 (+ SVG quando disponível), de duas origens —
-   ambas oficiais e identificadas no dataset (`logo.source.type`): o diretório público do
-   **Open Finance Brasil** (`openfinance`), onde cada instituição publica a própria marca, e o
-   **site oficial da própria instituição** (`direct-uri`), com curadoria visual antes de entrar.
-   Cada arquivo carrega proveniência: URI de origem, SHA-256 e data.
+1. **A lista de instituições — atualizada automaticamente, em dois conjuntos.** A **lista
+   principal** ([`data/bancos.json`](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`](data/instituicoes-pix.json)) — a lista principal permanece
+   limpa e quem precisa do universo completo do Pix tem tudo. Ambos com nomes oficiais, ISPB,
+   CNPJ (só-Pix) e atributos de participação no Pix. Você nunca mais mantém uma lista de
+   instituições no seu projeto.
+2. **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.
 3. **Atualização automática, sem curadoria manual.** Toda segunda-feira um GitHub Action
    ([`update-logos.yml`](.github/workflows/update-logos.yml)) reconstrói **a lista E os logos**
    a partir das fontes e abre um PR com o diff visual. Banco criado, renomeado ou extinto pelo
@@ -44,17 +52,17 @@
    copia os assets para projetos Flutter/Kotlin/Swift/.NET/PHP, URLs de CDN sem instalar nada —
    ou só o JSON.
 
-## Por que não manter uma lista à mão?
+## Por que fontes oficiais?
 
-Porque ela envelhece: 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 manualmente** de sites variados, sem rastreabilidade. A abordagem aqui:
+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** — o CSV de participantes do STR (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')`.
+- **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).
@@ -63,10 +71,10 @@ redesenham suas marcas. As bibliotecas existentes ou trazem **só dados** (sem l
 - **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** — 152 das 470 instituições têm logo (todas as participantes do Open
-  Finance + ~45 bancos e IPs cobertos pelos sites oficiais, o que inclui a esmagadora maioria
-  das contas do país). As demais são SCDs/cooperativas/corretoras pequenas; para elas seu app
-  usa o fallback que preferir — e a cobertura cresce a cada release.
+- **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.
 
 ## Instalação e uso
 
@@ -78,19 +86,27 @@ Requer **Node ≥ 20** para uso via Node/CLI (em web e React Native vale o ambie
 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 — inclusive para
-instituições Pix sem COMPE, no roadmap). As consultas aceitam **COMPE ou ISPB**.
+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)
 
 ```ts
-import { banks, byCompe, byIspb, logoCdnUrl } from 'logos-bancos-br';
+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)
@@ -109,9 +125,10 @@ 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'`).
-> Importar esse entry adiciona **todos** os logos (~1,3 MB) ao bundle. Se preferir empacotar só
-> alguns, use o CLI abaixo e faça `require()` dos arquivos copiados.
+> 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)
 
@@ -126,8 +143,8 @@ logoPngPath('341'); // /…/node_modules/logos-bancos-br/logos/png/60701190.png
 Vendorize os assets no seu projeto — sem dependência de runtime:
 
 ```bash
-npx logos-bancos-br copy --dest ./assets/banks            # 0341.png, 0001.png, ... (por COMPE)
-npx logos-bancos-br copy --dest ./assets/banks --by ispb  # 60701190.png, ...
+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
 ```
@@ -137,28 +154,30 @@ Rode de novo a cada atualização do pacote para receber lista e logos novos.
 ### CDN — sem instalar nada
 
 ```
-https://cdn.jsdelivr.net/npm/logos-bancos-br@0.1.0/logos/png/60701190.png
-https://cdn.jsdelivr.net/npm/logos-bancos-br@0.1.0/logos/svg/18236120.svg
+https://cdn.jsdelivr.net/npm/logos-bancos-br@0.3.0/logos/png/60701190.png
+https://cdn.jsdelivr.net/npm/logos-bancos-br@0.3.0/logos/svg/18236120.svg
 ```
 
-Fixe sempre uma versão (`@0.1.0`) — a correspondência COMPE→ISPB está em
+Fixe sempre uma versão (`@0.3.0`) — a correspondência COMPE→ISPB está em
 [`data/bancos.json`](data/bancos.json).
 
-### Só os dados (lista de bancos)
+### Só os dados
 
 ```ts
-import dados from 'logos-bancos-br/data/bancos.json';
-// todas as instituições: ispb, compe, compe4, nome oficial, nome reduzido, logo (ou null)
+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()` | todas as instituições (`Bank[]`) |
+| `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)` | `Bank \| undefined` |
-| | `findBank(codigo)` | `Bank \| undefined` — mais de 4 dígitos trata como ISPB |
+| | `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) |
@@ -166,7 +185,7 @@ import dados from 'logos-bancos-br/data/bancos.json';
 | | `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`, `BankLogo`, `BankLogoSource`.
+Tipos TypeScript exportados: `Bank`, `PixInstitution`, `Institution`, `BankLogo`, `BankLogoSource`, `PixInfo`.
 
 ## O dataset
 
@@ -179,6 +198,13 @@ Um registro de `data/bancos.json`:
   "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",
@@ -200,22 +226,33 @@ Um registro de `data/bancos.json`:
   `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
 
-1. **Espinha dorsal**: o CSV público de participantes do STR do Banco Central define *quais
-   instituições existem* (ISPB + COMPE + nomes oficiais). O BCB atualiza esse arquivo
-   diariamente.
+1. **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.
 2. **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.
 3. **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.
-4. **Fora do Open Finance**: ferramentas de descoberta (`npm run discover` e `discover:ai`)
+4. **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).
+5. **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`.
-5. **Normalização**: cada arte vira PNG 256×256; o SVG original é mantido quando seguro.
-6. **Cadência**: o workflow roda **toda segunda-feira** (e sob demanda), regenera
+6. **Normalização**: cada arte vira PNG 256×256; o SVG original é mantido quando seguro.
+7. **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. Depois da revisão e merge, o mantenedor publica uma
    nova versão no npm (Release no GitHub). Nada é editado à mão.
@@ -225,14 +262,15 @@ Detalhes de manutenção (rodar o pipeline localmente, promover sugestões, over
 
 ## Limitações conhecidas
 
-- Cobertura de logos: 152 hoje (Open Finance + sites oficiais curados); 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.
+- 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 **sem** código COMPE (participantes só do Pix) ainda não entram — o naming por ISPB
-  já foi desenhado para recebê-las sem breaking change (roadmap).
+- 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