{ "x-nota": "borda-json: clientes de IA de fora e integradores externos que leem OpenAPI",
  "openapi": "3.1.0",
  "info": { "title": "Wortic CEP", "version": "1.0.0", "description": "Endereços brasileiros pelo CEP, com o código IBGE da cidade, a partir da base dos Correios (eDNE). Também acha o CEP pela rua. Sem login: 60 consultas por minuto por IP. Quem passa do limite 10 vezes (cada minuto conta uma vez) fica bloqueado por 1 hora; depois de 3 bloqueios de 1 hora, o seguinte é de 6 horas; depois de 3 de 6 horas, o IP é banido de vez (403). Com chave (cabeçalho x-api-key) vale o limite do plano.", "contact": { "name": "Wortic", "url": "https://wortic.com.br" } },
  "servers": [{ "url": "https://cep.wortic.com" }],
  "paths": {
    "/cep/{cep}": { "get": { "operationId": "consultarCep", "summary": "Endereço pelo CEP",
      "parameters": [{ "name": "cep", "in": "path", "required": true, "description": "8 números, com ou sem traço.", "schema": { "type": "string" }, "example": "01001000" }],
      "responses": {
        "200": { "description": "Endereço encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Endereco" } } } },
        "400": { "description": "CEP sem 8 números (cep_invalido)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
        "404": { "description": "CEP não encontrado na base dos Correios (nao_encontrado)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
        "403": { "description": "IP banido da API aberta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
        "429": { "description": "Limite por minuto atingido (retry-after: 60) ou IP bloqueado por 1 ou 6 horas (retry-after com os segundos que faltam)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } },
    "/cep/buscar": { "get": { "operationId": "buscarCepPelaRua", "summary": "CEPs de uma rua numa cidade",
      "parameters": [
        { "name": "uf", "in": "query", "required": true, "description": "Sigla do estado.", "schema": { "type": "string" }, "example": "SP" },
        { "name": "cidade", "in": "query", "required": true, "description": "Nome da cidade, com ou sem acento.", "schema": { "type": "string" }, "example": "São Paulo" },
        { "name": "logradouro", "in": "query", "required": true, "description": "Parte do nome da rua, pelo menos 3 letras.", "schema": { "type": "string" }, "example": "Alexandre Dumas" },
        { "name": "limite", "in": "query", "required": false, "description": "Quantos CEPs devolver, de 1 a 50. Padrão 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }],
      "responses": {
        "200": { "description": "Lista de CEPs (vazia se nada combinar)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } },
        "400": { "description": "UF inválida (uf_invalida) ou rua com menos de 3 letras (busca_curta)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
        "422": { "description": "Falta uf, cidade ou logradouro, ou o limite está fora de 1 a 50", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } },
        "403": { "description": "IP banido da API aberta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
        "429": { "description": "Limite por minuto atingido ou IP bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }
  },
  "components": { "schemas": {
    "Endereco": { "type": "object", "properties": {
      "cep": { "type": "string", "example": "01001000" },
      "cep_formatado": { "type": "string", "example": "01001-000" },
      "logradouro": { "type": "string", "example": "Praça da Sé" },
      "complemento": { "type": "string", "description": "Trecho ou número que o CEP cobre, quando a base traz" },
      "bairro": { "type": "string", "example": "Sé" },
      "cidade": { "type": "string", "example": "São Paulo" },
      "cidade_ibge": { "type": "integer", "example": 3550308 },
      "uf": { "type": "string", "example": "SP" },
      "unidade": { "type": "string", "description": "Nome do prédio ou da unidade, quando o CEP é de um só endereço" },
      "fonte": { "type": "string", "example": "Correios eDNE (base Wortic)" } } },
    "Lista": { "type": "object", "properties": { "itens": { "type": "array", "items": { "$ref": "#/components/schemas/Endereco" } }, "total": { "type": "integer" } } },
    "Erro": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" } } } } } } }
}
