Brasões e Bandeiras do Brasil

Acervo de imagens dos brasões de armas dos municípios brasileiros, destinado ao uso na DANFSE (Documento Auxiliar Nota fiscal de serviço eletrônica) e em outros documentos que exigem a identificação visual dos municípios.

Início rápido

PHP

composer require cristianomzn/brasoes-e-bandeiras-do-brasil

<?php
require 'vendor/autoload.php';

use CristianoMzn\Bbb\Bbb;

echo Bbb::get('SP', '3550308');
// /caminho/do/projeto/vendor/cristianomzn/brasoes-e-bandeiras-do-brasil/brasao-de-armas-municipal/SP/3550308.jpg

Node.js

npm install @cristianomzn/brasoes-e-bandeiras-do-brasil

import { Bbb } from '@cristianomzn/brasoes-e-bandeiras-do-brasil';

console.log(Bbb.get('SP', '3550308'));
// /caminho/do/projeto/node_modules/@cristianomzn/brasoes-e-bandeiras-do-brasil/brasao-de-armas-municipal/SP/3550308.jpg

Requisitos

| Plataforma | Versão mínima | |------------|---------------| | PHP | 8.0+ | | Node.js | 18+ |

API

Bbb.get(uf, ibgeCode)

Retorna o caminho absoluto para a imagem do brasão de armas de um município brasileiro, ou false/null se a imagem não existir no acervo.

| Parâmetro | Tipo | Descrição | |-----------|------|-----------| | uf | string | Sigla da unidade federativa (ex: 'SP', 'RJ', 'MG') | | ibgeCode | string \| number | Código IBGE do município com exatamente 7 dígitos (ex: '3550308' ou 3550308) |

Retorno: string | false (PHP) ou string | null (Node.js) — caminho absoluto para o arquivo .jpg ou false/null se a imagem não existir no acervo.

Exceções (lançadas em caso de erro na lib):

| Exceção | PHP | Node.js | Motivo | |---------|-----|---------|--------| | UF inválida | InvalidArgumentException | Error | Sigla de estado não existe | | Código IBGE inválido | InvalidArgumentException | Error | Não contém exatamente 7 dígitos | | Diretório da UF não encontrado | RuntimeException | Error | Lib instalada incorretamente ou corrompida |

UFs válidas: AC, AL, AM, AP, BA, CE, DF, ES, GO, MA, MG, MS, MT, PA, PB, PE, PI, PR, RJ, RN, RO, RR, RS, SC, SE, SP, TO

Exemplo: renderização HTML

PHP:

<?php
require 'vendor/autoload.php';

use CristianoMzn\Bbb\Bbb;

$uf = 'SP';
$codigoIbge = '3550308';
$brasao = Bbb::get($uf, $codigoIbge);

if ($brasao !== false) {
    $img = base64_encode(file_get_contents($brasao));
    $html = "<img src='data:image/jpeg;base64,{$img}' alt='Brasão de {$uf}'>";
} else {
    $html = "<span class='placeholder'>Brasão não disponível</span>";
}

echo $html;

Node.js:

import { Bbb } from '@cristianomzn/brasoes-e-bandeiras-do-brasil';
import { readFileSync } from 'fs';

const uf = 'SP';
const codigoIbge = '3550308';
const brasao = Bbb.get(uf, codigoIbge);

let html;

if (brasao !== null) {
    const img = readFileSync(brasao);
    const base64 = img.toString('base64');
    html = `<img src="data:image/jpeg;base64,${base64}" alt="Brasão de ${uf}">`;
} else {
    html = `<span class="placeholder">Brasão não disponível</span>`;
}

console.log(html);

Exemplo: geração de PDF

PHP com TCPDF:

<?php
require 'vendor/autoload.php';
require 'vendor/tcpdf/tcpdf.php';

use CristianoMzn\Bbb\Bbb;

$uf = 'SP';
$codigoIbge = '3550308';
$brasao = Bbb::get($uf, $codigoIbge);

$pdf = new TCPDF();
$pdf->AddPage();

if ($brasao !== false) {
    $pdf->Image($brasao, 10, 10, 30);
} else {
    $pdf->Cell(0, 10, 'Brasão não disponível para este município.', 0, 1, 'C');
}

$pdf->Output('documento.pdf');

Node.js com PDFKit:

import { Bbb } from '@cristianomzn/brasoes-e-bandeiras-do-brasil';
import PDFDocument from 'pdfkit';
import { createWriteStream } from 'fs';

const uf = 'SP';
const codigoIbge = '3550308';
const brasao = Bbb.get(uf, codigoIbge);

const doc = new PDFDocument();
doc.pipe(createWriteStream('documento.pdf'));

if (brasao !== null) {
    doc.image(brasao, 10, 10, { width: 30 });
} else {
    doc.fontSize(12).text('Brasão não disponível para este município.', 10, 20);
}

doc.end();

Tratamento de erros

A função lança erro quando:

• A UF fornecida não é válida
• O código IBGE não contém exatamente 7 dígitos
• O diretório da UF não existe (lib corrompida)

PHP:

<?php
require 'vendor/autoload.php';

use CristianoMzn\Bbb\Bbb;

try {
    $path = Bbb::get('XX', '1234567');
} catch (InvalidArgumentException $e) {
    // UF ou código IBGE com formato inválido
    echo "Erro de validação: " . $e->getMessage();
} catch (RuntimeException $e) {
    // Diretório não existe — lib corrompida
    echo "Erro de instalação: " . $e->getMessage();
}

Node.js:

import { Bbb } from '@cristianomzn/brasoes-e-bandeiras-do-brasil';

try {
    const path = Bbb.get('XX', '1234567');
} catch (e) {
    console.error(`Erro: ${e.message}`);
}

Estrutura do projeto

brasao-de-armas-municipal/
├── AC/
│   ├── 1200054.jpg
│   ├── 1200104.jpg
│   └── ...
├── AL/
│   ├── 2700105.jpg
│   └── ...
├── GO/
│   ├── 5200050.jpg
│   └── ...
└── ...

As imagens são organizadas por unidade federativa (UF) e nomeadas pelo código IBGE do município.

Formato das imagens

| Propriedade | Valor | |-------------|-------| | Formato | JPEG | | Resolução | 192 × 192 px | | Fundo | Branco |

As imagens seguem o layout sugerido para inserção na DANFSE.

Cobertura atual

Resumo geral

| Métrica | Valor | |---------|-------| | Total de imagens | 3.266 | | Estados cobertos | 27 | | Municípios abrangidos | 3.266 | | Total de municípios no Brasil | 5.569 | | Cobertura nacional | 58,6% |

Detalhamento por UF

| UF | Cobertos | Total | Cobertura | | |----|----------|-------|-----------|--| | RR | 15 | 15 | 100% | █████████████ | | RS | 433 | 497 | 87,1% | ███████████░░ | | SP | 554 | 645 | 85,9% | ███████████░░ | | RJ | 75 | 92 | 81,5% | ██████████░░░ | | PB | 180 | 223 | 80,7% | ██████████░░░ | | SC | 214 | 295 | 72,5% | █████████░░░░ | | MG | 607 | 853 | 71,2% | █████████░░░░ | | RO | 34 | 52 | 65,4% | ████████░░░░░ | | ES | 51 | 78 | 65,4% | ████████░░░░░ | | RN | 106 | 167 | 63,5% | ████████░░░░░ | | CE | 100 | 184 | 54,3% | ███████░░░░░░ | | AL | 49 | 102 | 48,0% | ██████░░░░░░░ | | AC | 10 | 22 | 45,5% | ██████░░░░░░░ | | AM | 28 | 62 | 45,2% | ██████░░░░░░░ | | SE | 34 | 75 | 45,3% | ██████░░░░░░░ | | MS | 35 | 79 | 44,3% | █████░░░░░░░░ | | GO | 107 | 246 | 43,5% | █████░░░░░░░░ | | MT | 60 | 142 | 42,3% | █████░░░░░░░░ | | PA | 60 | 144 | 41,7% | █████░░░░░░░░ | | PR | 196 | 399 | 49,1% | ██████░░░░░░░ | | BA | 146 | 417 | 35,0% | █████░░░░░░░░ | | PE | 58 | 184 | 31,5% | ████░░░░░░░░░ | | AP | 5 | 16 | 31,3% | ████░░░░░░░░░ | | MA | 45 | 217 | 20,7% | ███░░░░░░░░░░ | | TO | 23 | 139 | 16,5% | ██░░░░░░░░░░░ | | PI | 40 | 224 | 17,9% | ██░░░░░░░░░░░ | | DF - Brasília | 1 | 1 | 100% | █████████████ |

Como contribuir

Contribuições são muito bem-vindas! Os principais tipos de contribuição esperados são:

• Enviar imagens de brasões de municípios ainda ausentes no acervo.
• Substituir imagens existentes por versões mais legíveis e de maior qualidade.

Regras obrigatórias

• Formato: JPEG (extensão .jpg).
• Resolução: 192 × 192 px exatos.
• Proporção de aspecto original preservada — imagens com distorção (esticamento ou compressão) serão rejeitadas.
• Nome do arquivo: código IBGE do município (ex: 1200054.jpg).
• A imagem deve ser de domínio público ou licenciada para uso livre.
• Incluir a fonte da imagem no pull request (ex: Wikipédia, portal da prefeitura).

Passo a passo

1. Faça um fork do repositório.
2. Adicione ou substitua a imagem na pasta da UF correspondente.
3. Abra um pull request com a descrição da alteração e a fonte da imagem.

Fontes

As imagens são obtidas de fontes públicas na internet, como:

• Wikipédia
• Portais oficiais de prefeituras municipais
• Outras fontes de domínio público

Importante: Somente imagens de domínio público ou licenciadas para uso livre serão aceitas neste projeto.

Ao contribuir, informe a origem da imagem utilizada.

Licença

Este projeto está licenciado sob a Licença MIT.