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

Nome	Tipo	Descrição
cnpj	string	CNPJ 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

Nome	Tipo	Descrição
cnpj	string	CNPJ com 14 dígitos numéricos, sem pontuação.
uf	string	Sigla 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

Nome	Tipo	Descrição
cnpj	string	CNPJ 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

Nome	Tipo	Descrição
cep	string	CEP 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",
  "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

Nome	Tipo	Descrição
uf	string	Sigla da UF em caixa alta (ex: SP).
cidade	string	Nome do município (mínimo 2 caracteres).
logradouro	string	Nome 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",
      "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

Nome	Tipo	Descrição
lat	number	Latitude WGS84 em graus decimais (ex: -23.5505).
lon	number	Longitude 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",
      "localizacao": {
        "latitude": -23.5505,
        "longitude": -46.6333,
        "precisao": "EXATA",
        "fonte": "OpenStreetMap-Nominatim"
      }
    }
  ]
}

[ CNPJ (Cadastro de Empresas) ]

GET/v1/cnpj/{cnpj}

Visão Geral

Dados cadastrais completos de empresas. Utiliza Refresh-Ahead para garantir que consultas recorrentes no dia útil sejam instantâneas.

Estratégia

Hedged Request + RAC

Soft: 6h / Hard: 24h

Provedores

BrasilAPIReceitaWSMinhaReceita

Parâmetros

Nome	Tipo	Descrição
cnpj	string	CNPJ (14 dígitos numéricos).

Request Inspector

{
  "cnpj": "00000000000191",
  "razao_social": "BANCO DO BRASIL S.A.",
  "data_abertura": "1966-08-01",
  "situacao": "ATIVA",
  "natureza_juridica": "Sociedade Anônima Aberta",
  "cnae_principal": "6422100"
}

[ 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

Nome	Tipo	Descrição
isbn	string	ISBN-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

Nome	Tipo	Descrição
codigo	string	Có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

Nome	Tipo	Descriçã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

Nome	Tipo	Descrição
codeOrSigla	string	Sigla (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

Nome	Tipo	Descrição
sigla	string	Sigla da UF (2 letras).

Request Inspector

[
  {
    "nome": "SÃO PAULO",
    "codigo_ibge": "3550308"
  }
]

[ 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). 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

Nome	Tipo	Descrição
busca	string	Termo de busca numérico (código exato) ou texto (substring flexível).

Request Inspector

[
  {
    "nome": "SÃO PAULO",
    "codigo_ibge": "3550308"
  }
]

[ 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

Nome	Tipo	Descrição
busca	string	Parte 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

Nome	Tipo	Descrição
codigo	string	Có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

Nome	Tipo	Descrição
ddd	string	Có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
}