Protocolo de Resiliência Ativo

cadastral Endpoints

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

[ 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
}