{"openapi":"3.1.0","info":{"title":"MyCEP API","version":"1.0.0","description":"Consulta de CEPs e endereços do Brasil, enriquecimento geográfico/fiscal, autocomplete, geocoding reverso e consultas cadastrais. Autenticação por chave Bearer do assinante — sem necessidade de IP fixo.\n\n**Fontes dos dados.** Coordenadas geográficas: Cadastro Nacional de Endereços para Fins Estatísticos (CNEFE), Censo Demográfico 2022 — IBGE. Códigos e divisões territoriais: IBGE. Base de CEPs: Correios.","contact":{"name":"MyCEP","url":"https://mycep.app.br"}},"servers":[{"url":"https://mycep.app.br"}],"tags":[{"name":"Busca","description":"CEP, endereço, autocomplete e geocoding reverso"},{"name":"Cadastros","description":"CNPJ, feriados e validadores"}],"components":{"securitySchemes":{"subscriberKey":{"type":"http","scheme":"bearer","description":"Chave do assinante (`cep_live_…` ou `cep_test_…`), criada em /account/api-keys. O valor completo é exibido uma única vez, na criação."}},"schemas":{"Address":{"type":"object","properties":{"cep":{"type":"string","example":"18540-023"},"tipoLogradouro":{"type":"string","nullable":true,"example":"Rua"},"logradouro":{"type":"string","example":"Cardoso Pimentel"},"bairro":{"type":"string","nullable":true,"example":"Centro"},"cidade":{"type":"string","example":"Porto Feliz"},"uf":{"type":"string","example":"SP"},"ibge":{"type":"string","example":"3540606"},"cepKind":{"type":"string","enum":["GRANDES CLIENTES","AGENCIAS CORREIOS","CAIXA POSTAL","CEP ESPECIAL","CEP UNICO"],"description":"Categoria do CEP quando não é de logradouro comum. Omitido no caso normal. Antes de 2026-08-24 este valor vinha, incorretamente, dentro de tipoLogradouro. `CEP UNICO` indica CEP que cobre o município inteiro (cidade sem CEP por logradouro): nesse caso `logradouro` vem vazio e `bairro` nulo, porque nenhum logradouro isolado responde por ele — a mesma convenção do ViaCEP."},"latitude":{"type":"number","description":"Somente em planos com enriquecimento e quando a base tem a coordenada. Fonte: CNEFE — Censo Demográfico 2022 (IBGE). Leia junto com `geoPrecision`: o ponto representa um trecho de logradouro, nunca o número da porta.","example":-23.56747},"longitude":{"type":"number","example":-46.64951},"geoPrecision":{"type":"string","enum":["street","city"],"description":"`street` = coordenada do logradouro. `city` = este CEP não tem coordenada própria e o valor devolvido é o centro do município — serve para enquadrar um mapa, não para cravar um alfinete."},"siafi":{"type":"string"},"ddd":{"type":"string"},"timezone":{"type":"string","example":"America/Sao_Paulo"},"ibgeMesoregion":{"type":"string","description":"Somente em planos com enriquecimento."},"ibgeMicroregion":{"type":"string","description":"Somente em planos com enriquecimento."},"ibgeImmediateRegion":{"type":"string","description":"Somente em planos com enriquecimento."},"ibgeIntermediateRegion":{"type":"string","description":"Somente em planos com enriquecimento."}},"required":["cep","logradouro","cidade","uf","ibge"]},"Error":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}},"security":[{"subscriberKey":[]}],"paths":{"/api/v1/search/cep/{cep}":{"get":{"tags":["Busca"],"summary":"Endereço por CEP","description":"Sem chave, a rota responde ao limite público de 5 consultas/min por IP e sem campos de enriquecimento.","parameters":[{"name":"cep","in":"path","required":true,"schema":{"type":"string","example":"18540023"}}],"responses":{"200":{"description":"Endereço encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}},"400":{"description":"CEP fora do formato de 8 dígitos (`invalid_cep`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"404":{"description":"CEP não encontrado.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"429":{"description":"Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}}}}},"/api/v1/search/address/{cidade}/{logradouro}":{"get":{"tags":["Busca"],"summary":"CEPs por logradouro","parameters":[{"name":"cidade","in":"path","required":true,"schema":{"type":"string","example":"Rio de Janeiro"},"description":"UTF-8 percent-encoded (ex.: \"Peçanha\" vira \"Pe%C3%A7anha\"). Byte cru ou sequência que não é UTF-8 válido (ex.: ISO-8859-1) é recusado com 400, e \"%\" literal precisa virar %25."},{"name":"logradouro","in":"path","required":true,"schema":{"type":"string","example":"Avenida Nilo Peçanha"},"description":"UTF-8 percent-encoded (ex.: \"Peçanha\" vira \"Pe%C3%A7anha\"). Byte cru ou sequência que não é UTF-8 válido (ex.: ISO-8859-1) é recusado com 400, e \"%\" literal precisa virar %25."}],"responses":{"200":{"description":"Lista de endereços (até 50).","content":{"application/json":{"schema":{"type":"object","properties":{"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}}}}}}},"400":{"description":"Cidade ou logradouro curtos demais (`invalid_query`), ou caminho que não é UTF-8 percent-encoded válido.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"429":{"description":"Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}}}}},"/api/v1/search/autocomplete":{"get":{"tags":["Busca"],"summary":"Sugestões de logradouro (Growth+)","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":3},"description":"Menos de 3 caracteres retorna lista vazia, não erro. UTF-8 percent-encoded (ex.: \"Peçanha\" vira \"Pe%C3%A7anha\"). Byte cru ou sequência que não é UTF-8 válido (ex.: ISO-8859-1) é recusado com 400, e \"%\" literal precisa virar %25."},{"name":"uf","in":"query","schema":{"type":"string","example":"SP"}}],"responses":{"200":{"description":"Até 5 sugestões.","content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Chave ausente, inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"403":{"description":"O plano da chave não inclui este recurso (`plan_upgrade_required`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"429":{"description":"Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}}}}},"/api/v1/search/reverse":{"get":{"tags":["Busca"],"summary":"Endereço mais próximo de uma coordenada (Business+)","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number"}},{"name":"lng","in":"query","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Endereço ou cidade mais próxima.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}},"400":{"description":"Coordenadas inválidas (`invalid_coordinates`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"404":{"description":"Nada dentro do raio configurado.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"403":{"description":"O plano da chave não inclui este recurso (`plan_upgrade_required`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"429":{"description":"Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}}}}},"/api/v1/registry/cnpj/{cnpj}":{"get":{"tags":["Cadastros"],"summary":"Consulta cadastral de CNPJ (Business+)","description":"Servido a partir de base local carregada de dados abertos/licenciados. Enquanto a base não estiver carregada, responde 503 `dataset_unavailable`.","parameters":[{"name":"cnpj","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Empresa encontrada."},"400":{"description":"CNPJ inválido (dígitos verificadores).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"404":{"description":"CNPJ não consta na base.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"503":{"description":"Base cadastral ainda não carregada.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"403":{"description":"O plano da chave não inclui este recurso (`plan_upgrade_required`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"429":{"description":"Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}}}}},"/api/v1/registry/holidays":{"get":{"tags":["Cadastros"],"summary":"Feriados nacionais, estaduais e municipais (Business+)","parameters":[{"name":"ano","in":"query","schema":{"type":"integer","example":2026},"description":"Padrão: ano corrente."},{"name":"uf","in":"query","schema":{"type":"string","example":"SP"}},{"name":"ibge","in":"query","schema":{"type":"string","example":"3550308"}}],"responses":{"200":{"description":"Feriados do período.","content":{"application/json":{"schema":{"type":"object","properties":{"ano":{"type":"integer"},"feriados":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Ano (`invalid_year`) ou código IBGE (`invalid_ibge`) inválido.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"403":{"description":"O plano da chave não inclui este recurso (`plan_upgrade_required`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"429":{"description":"Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}}}}},"/api/v1/validate/{kind}":{"get":{"tags":["Cadastros"],"summary":"Validadores locais de CEP, CPF, CNPJ, telefone e chave PIX (Growth+)","description":"Verifica formato e dígitos verificadores. NÃO afirma que o número está emitido nem que a chave PIX está registrada em algum banco.","parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["cep","cpf","cnpj","phone","pix"]}},{"name":"valor","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resultado da validação."},"400":{"description":"Tipo (`invalid_kind`) ou valor (`invalid_value`) ausente ou inválido.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"403":{"description":"O plano da chave não inclui este recurso (`plan_upgrade_required`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}},"429":{"description":"Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}}}}}}}