Protocolo de Resiliência Ativo

cadastral Endpoints

Documentação detalhada para o domínio cadastral. Projetado para redundância extrema.

[ CNDs Consolidadas (Trabalhista + FGTS + Federal) ]

Habilitação em Licitações
Degradação Graciosa por Nó
GET/api/v1/cadastral/cnd/{cnpj}

Visão Geral

Emite e valida em paralelo as TRÊS certidões negativas exigidas para habilitação em licitações e contratações públicas: CNDT do TST (Lei 12.440/2011), CRF do FGTS (Caixa Econômica) e Certidão Conjunta PGFN/Receita Federal (Portaria 1.751/2014). Engine roda os três clients simultaneamente via virtual threads em CompletableFuture.supplyAsync — p99 ≈ latência do nó mais lento (~1.6s), não a soma serial (~3.6s). Vantagens arquiteturais decisivas: (1) DEGRADAÇÃO GRACIOSA — se o nó Caixa devolver 503 (cenário recorrente em janelas de pico fiscal), a resposta NÃO quebra com 500: o sub-record fgts vem com status=INDISPONIVEL + motivo, e o cliente recebe trabalhista + federal úteis para tomar decisão parcial. Só quando os três nós caem simultaneamente o gateway lança 503 — não faz sentido devolver um envelope vazio. (2) PARSE ASP.NET VIEWSTATE VIA JSOUP — o portal Caixa Consulta Regularidade é WebForms puro, exige handshake com __VIEWSTATE/__EVENTVALIDATION; nosso FgtsCndClient faz GET inicial parseia os hiddens com Jsoup, captura cookies e replica o POST autenticado em ~1.2s (Selenium custaria ~3s + 250MB residentes). (3) API OCULTA DO TST — engenharia reversa do endpoint POST /certidao/emitir que o frontend React do tst.jus.br consome; resposta JSON estruturada, sem parsing HTML, latência consistente p50 ~800ms. (4) CIRCUIT BREAKERS DEDICADOS POR NÓ (tstCndCB, fgtsCndCB, federalCndCB) — falha de uma certidão não envenena as outras. Resposta carrega certidoesResolvidas (0–3) e degradado:boolean para sinalizar reprocessamento. Casos de uso: due diligence em M&A, habilitação automatizada em pregão eletrônico, score de risco de inadimplência tributária em concessão de crédito.

Estratégia
Busca Paralela O(1) + Degradação Graciosa no FGTS
Soft: 3h / Hard: 6h
Provedores
TST (API oculta certidao.tst.jus.br)Caixa CRF-FGTS (ASP.NET WebForms)PGFN/Receita Federal (Certidão Conjunta)
Parâmetros
NomeTipoDescrição
cnpjstringCNPJ com 14 dígitos numéricos, sem pontuação (sanitizado pela camada de validação).
Request Inspector
{
  "cnpj": "00000000000191",
  "trabalhista": {
    "status": "NEGATIVA",
    "dataEmissao": "2026-05-13",
    "dataValidade": "2026-11-09",
    "urlPdf": "https://certidao.tst.jus.br/certidao/PDF/000000000019120260513.pdf",
    "numeroCertidao": "184523456/2026",
    "motivoIndisponibilidade": null
  },
  "fgts": {
    "status": "INDISPONIVEL",
    "dataEmissao": null,
    "dataValidade": null,
    "urlPdf": null,
    "numeroCertidao": null,
    "motivoIndisponibilidade": "FGTS indisponível — HttpServerErrorException: Caixa devolveu HTTP 503 — degradação graciosa acionada."
  },
  "federal": {
    "status": "NEGATIVA",
    "dataEmissao": "2026-05-13",
    "dataValidade": "2026-11-09",
    "urlPdf": "https://servicos.receita.fazenda.gov.br/Servicos/certidaointernet/PJ/Emitir/PDF.aspx?ID=A1B2C3D4",
    "numeroCertidao": "A1B2.C3D4.E5F6.G7H8",
    "motivoIndisponibilidade": null
  },
  "certidoesResolvidas": 2,
  "degradado": true
}

[ Sintegra / Inscrição Estadual (IE) ]

Cobertura Nacional via CCC + Agregador
Hedge Inteligente (Empty ≠ Vitória)
GET/api/v1/cadastral/sintegra/{cnpj}/{uf}

Visão Geral

Inscrição estadual unificada via hedge entre o Cadastro Centralizado de Contribuintes do SVRS (consolida ~22 UFs sem CAPTCHA severo) e um agregador aberto que cobre SP/MG/RJ — estados que mantêm portais próprios blindados. UF é opcional: rota /api/v1/cadastral/sintegra/{cnpj} varre nacionalmente, /api/v1/cadastral/sintegra/{cnpj}/{uf} faz o recorte direto (mais barato em quota). Decisão arquitetural não-óbvia — HEDGE COM "EMPTY-AS-FAILURE": o hedge clássico retorna o primeiro sucesso, mas se o CCC respondesse rapidamente com 404 para uma empresa de SP (UF que ele não cobre), enterraria o agregador que estaria a milissegundos de devolver o resultado real. Solução: cada provedor que devolve Optional.empty() é interceptado e re-lançado como falha transitória, fazendo o HedgedExecutor esperar pelo outro. Se AMBOS terminarem empty, o service distingue causa "EMPTY:" e devolve 404 (recurso inexistente) ao invés de 503 (indisponível) — preservando a semântica do GlobalExceptionHandler. Trade-off aceito: ambos provedores são sempre chamados em paralelo, pagando banda do agregador (caro) mesmo quando o CCC teria respondido sozinho — aceitável porque cada chamada Sintegra é cacheada por dias e o ganho de cobertura supera o custo bruto. Parser Jsoup ancorado em rótulos (não posição de coluna), tolerante a reordenação no portal SVRS. Casos de uso: validação cadastral fiscal antes de emissão de NF-e (rejeição em SEFAZ-destino), auditoria de cadeia de fornecedores, anti-fraude em onboarding B2B.

Estratégia
Hedged Request com Empty-as-Failure (CCC/SVRS ‖ Agregador) + RAC
Soft: 2d / Hard: 7d
Provedores
CCC/SVRS (Cadastro Centralizado de Contribuintes — SEFAZ-RS)Sintegra-Agregador (cobertura SP/MG/RJ + fallback nacional)
Parâmetros
NomeTipoDescrição
cnpjstringCNPJ com 14 dígitos numéricos, sem pontuação.
ufstringSigla da Unidade Federativa (2 letras). OPCIONAL — quando omitida, varre todas as UFs cobertas. Caminho com UF é ~600ms p50 (CCC vence); sem UF, p95 sobe para ~1.4s (agregador domina).
Request Inspector
{
  "cnpj": "07526557000100",
  "ie": "0732030210114",
  "uf": "RS",
  "situacaoCadastral": "ATIVA",
  "dataSituacao": "2019-04-15",
  "regimeApuracao": "SIMPLES_NACIONAL",
  "fonte": "CCC-SVRS"
}

[ Simples Nacional (Enquadramento + SIMEI) ]

Histórico de Exclusões Exclusivo
Captcha-Aware Fallback
GET/api/v1/cadastral/simples/{cnpj}

Visão Geral

Resolve o enquadramento da PJ nos regimes Simples Nacional e SIMEI consultando o portal oficial Consulta Optantes da Receita Federal via engenharia reversa de JSF — captura cookies de sessão, parseia o input javax.faces.ViewState, monta o POST do form e extrai a tabela de resultado com Jsoup. Estratégia em CASCATA (não hedge): o provedor primário oficial carrega informação EXCLUSIVA que o fallback REST não devolve — data de exclusão do regime para empresas desenquadradas, dado decisivo para due diligence (M&A, abertura de crédito, análise de risco). Disparar os dois em paralelo faria o fallback ReceitaWS (~600ms) vencer sistematicamente sobre o scraper (~1.8s) e descartaríamos a informação rica. Captcha-Aware Fallback: o portal Consulta Optantes liga hCaptcha em janelas de pico (8h–18h dias úteis); ao detectar o marcador .h-captcha na resposta, o SimplesNacionalReceitaClient lança ResourceUnavailableException explicando o motivo e o SimplesNacionalService cascateia imediatamente para o SimplesNacionalFallbackClient, que reutiliza a integração ReceitaWS — agregador que já entrega os campos opcao_pelo_simples, data_opcao_pelo_simples, opcao_pelo_mei e data_opcao_pelo_mei no payload de CNPJ. Circuit Breakers dedicados (simplesReceitaCB + simplesFallbackCB) impedem que rate-limit do agregador (3 req/min no tier gratuito) ou downtime do portal contagiem o caminho crítico. Resposta carrega o campo fonte para auditoria de SLA — BI consegue medir quantos % do tráfego foi resolvido pelo oficial vs. fallback. Casos de uso: cálculo de tributos em emissor de NF-e (alíquota varia por enquadramento), validação de prerrogativa para licitações de ME/EPP, score de risco em concessão de crédito.

Estratégia
Cascata Inteligente (Scraper Oficial → ReceitaWS) + Parse ViewState via Jsoup
Soft: 12h / Hard: 24h
Provedores
Receita Federal — Portal Consulta Optantes (scraper JSF/ViewState)ReceitaWS (fallback agregador com Simples/SIMEI no payload de CNPJ)
Parâmetros
NomeTipoDescrição
cnpjstringCNPJ com 14 dígitos numéricos, sem pontuação.
Request Inspector
{
  "cnpj": "11222333000181",
  "optanteSimples": true,
  "dataOpcaoSimples": "2018-01-01",
  "optanteSimei": false,
  "dataOpcaoSimei": null,
  "fonte": "ReceitaFederal-OptantesScraper"
}

[ CEP (Endereçamento + Geocodificação) ]

Geocodificação Embutida
GET/api/v1/cep/{cep}

Visão Geral

Consulta de endereços completos com corrida de provedores e geocodificação opcional integrada — sem necessidade de chamar Google Maps Geocoding na sequência. O endpoint permanece sob /api/v1/cep/{cep} (contrato preservado); o campo location é uma adição backward-compatible, nullable. Engine de Resiliência em DUAS camadas: (1) TIER 1 — endereço base via hedge paralelo entre ViaCEP, BrasilAPI v1 e AwesomeAPI; o primeiro a responder vence, os perdedores são cancelados. AwesomeAPI já devolve lat/lng nativamente para a maioria dos CEPs urbanos — quando vence o hedge, a geo vem grátis no caminho rápido. (2) TIER 2 — backfill de geocodificação em CASCATA (não hedge — Nominatim público é rate-limited 1 req/s e merece parcimônia): BrasilAPI v2 /api/cep/v2/{cep} primeiro (cache do lado deles, latência estável), Nominatim OSM direto como rede de proteção. A filtragem de coordenada replica a heurística da BrasilAPI: postcode exato 8 dígitos → precisão EXATA; prefixo 5 dígitos → precisão APROXIMADA (escala de bairro); sem match → location segue null. DEGRADAÇÃO GRACIOSA: se ambos providers de geo falharem (CB aberto, rate-limit, timeout), a resposta CEP é entregue SEM location ao invés de 503 — endereço é o core do contrato, geo é enriquecimento. Casos de uso típicos: roteirização (cálculo de frete por distância real, não geodésica), mapas em apps de delivery, geofencing de motoristas, anti-fraude (validar se endereço bate com IP/GPS do cliente em onboarding KYC). Resposta enriquecida (endereço + IBGE + geo) entra no cache 30d, então hits subsequentes não pagam Nominatim.

Estratégia
Hedged Request + RAC + Geo Backfill em Cascata
Soft: 7d / Hard: 30d (resposta enriquecida)
Provedores
ViaCEPBrasilAPI v1AwesomeAPI (com lat/lng)BrasilAPI v2 (geo)OpenStreetMap-Nominatim
Parâmetros
NomeTipoDescrição
cepstringCEP de 8 dígitos numéricos (com ou sem hífen — sanitizado automaticamente).
Request Inspector
{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "ibge": "3550308",
  "siafi": "7107",
  "ddd": 11,
  "localizacao": {
    "latitude": -23.5505,
    "longitude": -46.6333,
    "precisao": "EXATA",
    "fonte": "OpenStreetMap-Nominatim"
  }
}

[ CEP - Busca (Autocompletar por Endereço) ]

GET/api/v1/cep/busca

Visão Geral

Consulta o ViaCEP buscando CEPs a partir do endereço textual informado (UF, cidade e logradouro). Retorna uma lista de candidatos — útil para autocompletar campos de endereço ou confirmar o CEP de uma rua antes de cadastrá-lo. O logradouro deve ter no mínimo 3 caracteres e o resultado é limitado a 50 registros pelo upstream.

Estratégia
Upstream Direto (ViaCEP)
None
Provedores
ViaCEP
Parâmetros
NomeTipoDescrição
ufstringSigla da UF em caixa alta (ex: SP).
cidadestringNome do município (mínimo 2 caracteres).
logradourostringNome do logradouro (mínimo 3 caracteres).
Request Inspector
{
  "total": 1,
  "candidatos": [
    {
      "cep": "01001-000",
      "logradouro": "Praça da Sé",
      "complemento": "lado ímpar",
      "bairro": "Sé",
      "localidade": "São Paulo",
      "uf": "SP",
      "ibge": "3550308",
      "siafi": "7107",
      "ddd": 11,
      "localizacao": null
    }
  ]
}

[ CEP - Reverso (Geocodificação Reversa) ]

Geocodificação Reversa
GET/api/v1/cep/reverso

Visão Geral

Realiza geocodificação reversa via Nominatim/OpenStreetMap: dado um par de coordenadas WGS84 (latitude e longitude), retorna o endereço brasileiro e o CEP correspondentes ao ponto. Caso de uso principal: o usuário clica num mapa (Leaflet, Google Maps, etc.) e a aplicação obtém o CEP sem que o usuário precise digitar nada. Se o ponto estiver em área sem CEP cadastrado, a lista virá vazia (total: 0).

Estratégia
Upstream Direto (Nominatim OSM)
None
Provedores
OpenStreetMap-Nominatim
Parâmetros
NomeTipoDescrição
latnumberLatitude WGS84 em graus decimais (ex: -23.5505).
lonnumberLongitude WGS84 em graus decimais (ex: -46.6333).
Request Inspector
{
  "total": 1,
  "candidatos": [
    {
      "cep": "01001-000",
      "logradouro": "Praça da Sé",
      "complemento": "",
      "bairro": "Sé",
      "localidade": "São Paulo",
      "uf": "SP",
      "ibge": "3550308",
      "siafi": "7107",
      "ddd": 11,
      "localizacao": {
        "latitude": -23.5505,
        "longitude": -46.6333,
        "precisao": "EXATA",
        "fonte": "OpenStreetMap-Nominatim"
      }
    }
  ]
}

[ CNPJ Consolidado (Básica + QSA + Empresa) ]

Engine de Resiliência 5×
Fail-Soft 1/5 Sobrevivente
LGPD-safe (QSA Mascarado)
GET/api/v1/cadastral/cnpj/{cnpj}

Visão Geral

ENGINE CANÔNICA DE CNPJ — agrega Consulta Básica, QSA e Empresa (3 contratos oficiais RFB) em UM ÚNICO payload rico unificado por merge campo-a-campo entre 5 providers gratuitos disparados em PARALELO via virtual threads (Project Loom). Cada provider tem timeout duro de 10s; quem responder dentro do deadline entra na lista determinística de fontes sobreviventes — expostas no header X-CNPJ-Sources e no array fontesSobreviventes do payload. ENGINE DE RESILIÊNCIA: (1) PRIMÁRIO ALTA VELOCIDADE — CNPJ.WS e OpenCNPJ rodam contra snapshots públicos com latência p50 sub-200ms, formando a espinha dorsal do merge; (2) SECUNDÁRIO COMPLEMENTAR — CNPJá entrega tabela qualificada de sócios e enquadramento Simples/MEI consolidado por período; (3) FALLBACK CONTROLADO — ReceitaWS protegida por @RateLimiter local (Bucket4j 3 req/min) que NUNCA estoura o tier público para evitar HTTP 429, com fallback graceful pré-flight quando o bucket esgota; (4) APÓLICE DE SEGURO — Archive CNPJ.PW serve fragmentos JSON do dump RFB com cadência horária quando todas as APIs REST online caem simultaneamente. NORMALIZAÇÕES MANDATÓRIAS DO MERGER: (a) capitalSocial entregue como inteiro em centavos (formato Serpro) é estritamente DIVIDIDO POR 100 para reais com 2 casas; (b) tipoEstabelecimento inferido de '1'→MATRIZ e '2'→FILIAL; (c) Empresário Individual (NJ 213-5) força QSA vazio sem NPE — proteção contra dados sujos de dumps; (d) QSA limitado a 300 sócios via cap defensivo; (e) documentos CPF/CNPJ de sócios sempre mascarados (***.NNN.NNN-** / **.NNN.NNN/NNNN-**) em conformidade LGPD. CACHE LONGO: dados cadastrais de PJ têm volatilidade baixíssima — hard-TTL 30 dias absorve 99% das consultas; soft-TTL 24h via Refresh-Ahead-Cache dispara revalidação em background, propagando qualquer alteração de razão social/situação em ≤ 1 dia útil sem martelar os 5 providers no hot path. Casos de uso: onboarding B2B, emissão de NF-e, due diligence M&A, validação fiscal pré-SEFAZ, score anti-fraude.

Estratégia
Multi-Fallback Paralelo (Virtual Threads) + RAC
Soft: 24h / Hard: 30d
Provedores
CNPJ.WS (Primário Alta Velocidade)OpenCNPJ (Primário Alta Velocidade)CNPJá! (Secundário Complementar)ReceitaWS (Fallback Controlado · ≤3 rpm)Archive CNPJ.PW (Background Dump Horário)
Parâmetros
NomeTipoDescrição
cnpjstringCNPJ com ou sem máscara (14 dígitos no total). Sanitização automática no boundary.
Request Inspector
{
  "ni": "00000000000191",
  "tipoEstabelecimento": "MATRIZ",
  "nomeEmpresarial": "BANCO DO BRASIL SA",
  "nomeFantasia": "BB",
  "situacaoCadastral": {
    "codigo": "02",
    "descricao": "ATIVA",
    "data": "2005-11-03",
    "motivo": "SEM MOTIVO"
  },
  "naturezaJuridica": {
    "codigo": "203-4",
    "descricao": "Sociedade de Economia Mista"
  },
  "dataAbertura": "1966-08-01",
  "cnaePrincipal": {
    "codigo": "6422100",
    "descricao": "Bancos múltiplos, com carteira comercial"
  },
  "cnaeSecundarias": [
    {
      "codigo": "6499999",
      "descricao": "Outras atividades de serviços financeiros"
    },
    {
      "codigo": "6619302",
      "descricao": "Correspondentes de instituições financeiras"
    },
    {
      "codigo": "6435201",
      "descricao": "Sociedades de crédito imobiliário"
    }
  ],
  "enderecoCompleto": {
    "logradouro": "QUADRA SAUN QUADRA 5 LOTE B TORRES I, II E III",
    "numero": "S/N",
    "complemento": "ANDAR 1 A 16 E SUBSOLO",
    "bairro": "ASA NORTE",
    "cep": "70040912",
    "municipio": {
      "codigoIbge": "5300108",
      "nome": "Brasília"
    },
    "uf": "DF"
  },
  "contatos": {
    "telefones": [
      {
        "ddd": "61",
        "numero": "34939002"
      },
      {
        "ddd": "61",
        "numero": "34939003"
      }
    ],
    "correioEletronico": "sac@bb.com.br"
  },
  "capitalSocial": "120000000000.00",
  "porte": "DEMAIS",
  "informacoesSimplesMei": {
    "optanteSimples": false,
    "optanteMei": false,
    "listaPeriodos": []
  },
  "qsa": [
    {
      "nome": "TARCIANA PAULA GOMES MEDEIROS",
      "cpfCnpjMascarado": "***.456.789-**",
      "qualificacao": "Diretor",
      "pais": "BRASIL",
      "dataEntrada": "2023-01-12"
    },
    {
      "nome": "CARLOS RENATO BONETTI",
      "cpfCnpjMascarado": "***.321.654-**",
      "qualificacao": "Vice-Presidente",
      "pais": "BRASIL",
      "dataEntrada": "2023-02-15"
    },
    {
      "nome": "GIULIANO ALVES RIBEIRO",
      "cpfCnpjMascarado": "***.987.012-**",
      "qualificacao": "Vice-Presidente",
      "pais": "BRASIL",
      "dataEntrada": "2023-02-15"
    },
    {
      "nome": "JOSE RICARDO SASSERON",
      "cpfCnpjMascarado": "***.555.444-**",
      "qualificacao": "Vice-Presidente",
      "pais": "BRASIL",
      "dataEntrada": "2023-02-15"
    },
    {
      "nome": "JOAO CARLOS GONCALVES PEREIRA",
      "cpfCnpjMascarado": "***.111.222-**",
      "qualificacao": "Vice-Presidente",
      "pais": "BRASIL",
      "dataEntrada": "2023-02-15"
    },
    {
      "nome": "FELIPE GUIMARAES GEISSLER PRINCE",
      "cpfCnpjMascarado": "***.222.333-**",
      "qualificacao": "Vice-Presidente",
      "pais": "BRASIL",
      "dataEntrada": "2023-04-20"
    },
    {
      "nome": "MARCO ANTONIO MARCONDES PEREIRA",
      "cpfCnpjMascarado": "***.333.444-**",
      "qualificacao": "Vice-Presidente",
      "pais": "BRASIL",
      "dataEntrada": "2023-02-15"
    },
    {
      "nome": "JOAO PAULO DOS REIS VELLOSO FILHO",
      "cpfCnpjMascarado": "***.444.555-**",
      "qualificacao": "Conselheiro de Administração",
      "pais": "BRASIL",
      "dataEntrada": "2023-05-30"
    },
    {
      "nome": "MARGARETH MOREIRA",
      "cpfCnpjMascarado": "***.555.666-**",
      "qualificacao": "Conselheiro de Administração",
      "pais": "BRASIL",
      "dataEntrada": "2023-04-28"
    },
    {
      "nome": "KELLY RODRIGUES GUEDES NASCIMENTO",
      "cpfCnpjMascarado": "***.666.777-**",
      "qualificacao": "Conselheiro Fiscal",
      "pais": "BRASIL",
      "dataEntrada": "2024-04-19"
    },
    {
      "nome": "RENATA WAGNER",
      "cpfCnpjMascarado": "***.777.888-**",
      "qualificacao": "Conselheiro Fiscal",
      "pais": "BRASIL",
      "dataEntrada": "2024-04-19"
    },
    {
      "nome": "PEDRO PAULO LUCIANO MAGALHAES",
      "cpfCnpjMascarado": "***.888.999-**",
      "qualificacao": "Auditor",
      "pais": "BRASIL",
      "dataEntrada": "2024-01-05"
    }
  ],
  "fontesSobreviventes": [
    "CnpjWs",
    "OpenCnpj",
    "CnpjA",
    "ReceitaWS",
    "ArchiveCnpjPw"
  ]
}

[ ISBN (Dados Bibliográficos) ]

Configuração Opcional
Dica: Melhore a Resiliência

Para garantir o fallback direto na CBL em caso de falha dos outros provedores, configure a variável GATEWAY_ISBN_CBL_API_KEY no seu ambiente.

GET/v1/isbn/{isbn}

Visão Geral

Consulta de dados bibliográficos por ISBN-10 ou ISBN-13. Enriquecimento de capas via Open Library e detalhamento local via CBL.

Estratégia
Hedged Parallel
Soft: 90d / Hard: 365d
Provedores
BrasilAPICBLGoogle BooksOpen Library
Parâmetros
NomeTipoDescrição
isbnstringISBN-10 ou ISBN-13 (com ou sem hífens).
Request Inspector
{
  "isbn": "9788532530803",
  "title": "Harry Potter e a Pedra Filosofal",
  "authors": [
    "J. K. Rowling"
  ],
  "publisher": "Rocco",
  "year": 2017,
  "page_count": 264,
  "cover_url": "https://covers.openlibrary.org/b/isbn/9788532530803-L.jpg",
  "provider": "BrasilAPI"
}

[ CNAE (Classificação Econômica) ]

GET/v1/cadastral/cnae/{codigo}

Visão Geral

Descrição oficial CONCLA para subclasses CNAE. Possui snapshot local de ~1.3k registros para garantir resiliência total.

Estratégia
Sequential Fallback
Hard: 30d
Provedores
IBGELocal Snapshot
Parâmetros
NomeTipoDescrição
codigostringCódigo CNAE (7 dígitos).
Request Inspector
{
  "codigo": "6422100",
  "descricao": "Bancos múltiplos, com carteira comercial"
}

[ IBGE - Estados (UFs) ]

GET/api/v1/cadastral/ibge/uf

Visão Geral

Lista as 27 unidades federativas. Prioriza o portal de serviços do IBGE; BrasilAPI entra como fallback automático para garantir disponibilidade em caso de downtime governamental.

Estratégia
Cascata Hierárquica (Oficial → BrasilAPI)
Soft: 30d / Hard: 365d
Provedores
IBGE (Oficial)BrasilAPI
Parâmetros
NomeTipoDescrição
Request Inspector
[
  {
    "id": 35,
    "sigla": "SP",
    "nome": "São Paulo",
    "regiao_sigla": "SE",
    "regiao_nome": "Sudeste",
    "capital": "São Paulo"
  }
]

[ IBGE - Detalhe UF ]

GET/api/v1/cadastral/ibge/uf/{codeOrSigla}

Visão Geral

Detalhes de uma UF com estimativa populacional (best-effort). O fallback BrasilAPI já integra a população na resposta principal, evitando round-trips extras.

Estratégia
Cascata Hierárquica (Oficial → BrasilAPI)
Soft: 30d / Hard: 365d
Provedores
IBGE (Oficial)BrasilAPI
Parâmetros
NomeTipoDescrição
codeOrSiglastringSigla (ex: SP) ou código IBGE (ex: 35).
Request Inspector
{
  "id": 35,
  "sigla": "SP",
  "nome": "São Paulo",
  "regiao_sigla": "SE",
  "regiao_nome": "Sudeste",
  "capital": "São Paulo",
  "populacao_estimada": 44411238,
  "periodo": "2025"
}

[ IBGE - Municípios (Por UF) ]

GET/api/v1/cadastral/ibge/uf/{sigla}/municipios

Visão Geral

Hedge em paralelo entre IBGE-Gov e DadosAbertosBR (Tier 1). Caso ambos falhem, dispara fallback sequencial para BrasilAPI (Tier 2).

Estratégia
Tiered Hedge (Hedge Interno → BrasilAPI Fallback)
Soft: 30d / Hard: 365d
Provedores
IBGE (Oficial)DadosAbertosBRBrasilAPI
Parâmetros
NomeTipoDescrição
siglastringSigla da UF (2 letras).
Request Inspector
[
  {
    "nome": "SÃO PAULO",
    "codigo_ibge": "3550308",
    "latitude": -23.5505,
    "longitude": -46.6333,
    "capital": true,
    "siafi": "7107",
    "ddd": 11,
    "fuso_horario": "America/Sao_Paulo"
  }
]

[ IBGE - Busca Global de Municípios ]

Base Local Indexada (5.5k+ cidades)
GET/api/v1/cadastral/ibge/municipios

Visão Geral

Super-motor de busca de municípios em memória com latência O(1). Permite busca exata pelo código IBGE (7 dígitos) ou busca textual fonética/substring (ignorando acentos e case). O motor utiliza uma base local enriquecida (dataset Kelvins) que complementa os dados oficiais com coordenadas geográficas, códigos SIAFI, DDD e fuso horário. Caso a busca por código falhe localmente, aciona fallback em cascata para a API oficial do IBGE.

Estratégia
In-Memory Index + Cascata API
Hard: 365d
Provedores
IBGE Base LocalIBGE (Oficial)
Parâmetros
NomeTipoDescrição
buscastringTermo de busca numérico (código exato) ou texto (substring flexível).
Request Inspector
[
  {
    "nome": "SÃO PAULO",
    "codigo_ibge": "3550308",
    "latitude": -23.5505,
    "longitude": -46.6333,
    "capital": true,
    "siafi": "7107",
    "ddd": 11,
    "fuso_horario": "America/Sao_Paulo"
  }
]

[ CBO - Catálogo de Ocupações ]

Catálogo Oficial MTE (2.5k+ CBOs)
GET/api/v1/cadastral/cbo

Visão Geral

Motor de busca fonética para a Classificação Brasileira de Ocupações (CBO) servido via índice em memória de alta performance. Varre o catálogo canônico de 6 dígitos instantaneamente filtrando profissões por substring, ignorando casing e acentuação.

Estratégia
In-Memory Index
None (In-Memory)
Provedores
MTE (Base Local)
Parâmetros
NomeTipoDescrição
buscastringParte do título da ocupação (ex: "medico", "operador").
Request Inspector
[
  {
    "codigo": "225125",
    "titulo": "MÉDICO CLÍNICO"
  },
  {
    "codigo": "225124",
    "titulo": "MÉDICO PEDIATRA"
  }
]

[ CBO - Detalhe por Código ]

Lookup O(1) Canônico
GET/api/v1/cadastral/cbo/{codigo}

Visão Geral

Traz o título exato de um CBO com base no código de 6 dígitos. Possui malha de resiliência acionável via integrações do CNES/MTE para códigos não listados no catálogo base de 2.562 ocupações.

Estratégia
O(1) Memory Lookup + Malha Resiliência
None (In-Memory)
Provedores
MTE (Base Local)CNES (Fallback)
Parâmetros
NomeTipoDescrição
codigostringCódigo numérico exato de 6 dígitos (ex: 225125).
Request Inspector
{
  "codigo": "225125",
  "titulo": "MÉDICO CLÍNICO"
}

[ DDD (ANATEL) ]

GET/v1/cadastral/ddd/{ddd}

Visão Geral

Consulta oficial DDD -> UF e cidades. BrasilAPI atua como rede de proteção caso o snapshot da ANATEL não consiga ser carregado.

Estratégia
Cascata Hierárquica (ANATEL → BrasilAPI)
Soft: 90d / Hard: 365d
Provedores
ANATEL (Oficial)BrasilAPI
Parâmetros
NomeTipoDescrição
dddstringCódigo de 2 dígitos (ex: 11).
Request Inspector
{
  "state": "SP",
  "cities": [
    "SÃO PAULO",
    "OSASCO",
    "GUARULHOS"
  ]
}

Erros & Status Codes

Padrão RFC 7807 para reportar falhas críticas.

HTTP 503 SERVICE UNAVAILABLE
{
  "type": "error/fallback-exhausted",
  "status": 503,
  "hedged_attempts": 3
}
HTTP 404 NOT FOUND
{
  "type": "error/not-found",
  "status": 404
}