{ "x-nota": "borda-json: clientes de IA de fora (ChatGPT, Claude, Cursor) e integradores externos que só leem OpenAPI em JSON",
  "openapi": "3.1.0",
  "info": {
    "title": "Wortic CNPJ",
    "version": "1.1.0",
    "description": "Consulta de empresas brasileiras pelos dados abertos do CNPJ da Receita Federal, pela Wortic. O mês da base vem no cabeçalho x-base-cnpj (AAAA-MM) das respostas sem chave.\n\nSem chave, é grátis: 60 consultas por minuto e 2.000 por dia, por IP. O dia vira à meia-noite de Brasília. Quem passa do limite do minuto ou do dia recebe HTTP 402 com o código limite_gratis e o cabeçalho retry-after, em segundos.\n\nEscada de bloqueio, sem chave: cada minuto em que o IP passa do limite do minuto conta uma vez. Com 10 minutos assim, o IP fica bloqueado por 1 hora (HTTP 429, código bloqueado). Depois de 3 bloqueios de 1 hora, o seguinte é de 6 horas. Depois de 3 bloqueios de 6 horas, o IP é banido (HTTP 403, código banido). Passar do limite do dia não conta para a escada.\n\nCom a chave no cabeçalho x-api-key, vale o limite do plano e a escada não se aplica. As rotas /v1 são do plano Pro: sem chave, respondem HTTP 402 com o código plano_pro.",
    "contact": { "name": "Wortic", "url": "https://wortic.com.br/contato" },
    "termsOfService": "https://cnpj.wortic.com/termos"
  },
  "servers": [{ "url": "https://cnpj.wortic.com" }],
  "paths": {
    "/cnpj/{cnpj}": {
      "get": {
        "operationId": "consultarCnpj",
        "summary": "Ficha da empresa pelo CNPJ",
        "description": "A ficha completa de uma empresa. Aceita o CNPJ com ou sem pontuação, numérico ou alfanumérico, com o zero da frente.",
        "security": [{}, { "chave": [] }],
        "parameters": [{ "$ref": "#/components/parameters/cnpjPath" }],
        "responses": {
          "200": {
            "description": "Ficha encontrada. Sem chave, traz os cabeçalhos do limite do dia e o mês da base.",
            "headers": {
              "x-base-cnpj": { "$ref": "#/components/headers/xBaseCnpj" },
              "x-ratelimit-limit-dia": { "$ref": "#/components/headers/xRatelimitLimitDia" },
              "x-ratelimit-restante-dia": { "$ref": "#/components/headers/xRatelimitRestanteDia" }
            },
            "content": { "application/json": {
              "schema": { "$ref": "#/components/schemas/Ficha" },
              "example": {
                "cnpj": "37853407000171", "cnpj_formatado": "37.853.407/0001-71", "razao_social": "WORTIC LTDA", "nome_fantasia": "",
                "tipo": { "codigo": 1, "descricao": "Matriz" },
                "situacao": { "codigo": 2, "descricao": "Ativa", "desde": "2020-07-24" },
                "abertura": "2020-07-24",
                "cnae_principal": { "codigo": "6202300", "descricao": "Desenvolvimento e licenciamento de programas de computador customizáveis" },
                "cnaes_secundarios": [
                  { "codigo": "6201501", "descricao": "Desenvolvimento de programas de computador sob encomenda" },
                  { "codigo": "6203100", "descricao": "Desenvolvimento e licenciamento de programas de computador não-customizáveis" },
                  { "codigo": "6204000", "descricao": "Consultoria em tecnologia da informação" },
                  { "codigo": "6209100", "descricao": "Suporte técnico, manutenção e outros serviços em tecnologia da informação" },
                  { "codigo": "6311900", "descricao": "Tratamento de dados, provedores de serviços de aplicação e serviços de hospedagem na internet" },
                  { "codigo": "6319400", "descricao": "Portais, provedores de conteúdo e outros serviços de informação na internet" }
                ],
                "natureza_juridica": { "codigo": "2062", "descricao": "Sociedade Empresária Limitada" },
                "capital_social": 20000.0,
                "porte": { "codigo": "01", "descricao": "Microempresa" },
                "simples": true, "mei": false,
                "endereco": { "tipo_logradouro": "RUA", "logradouro": "ALEXANDRE DUMAS", "numero": "1562", "complemento": "ANDAR 6                   CONJ  63", "bairro": "CHACARA SANTO ANTONIO (ZONA SUL)", "cep": "04717914", "cidade": "SAO PAULO", "cidade_ibge": 3550308, "uf": "SP" },
                "telefone": "(11) 91568557",
                "email": "contato@exemplo.com.br",
                "fonte": "Receita Federal, dados abertos do CNPJ (base Wortic)"
              }
            } }
          },
          "400": { "$ref": "#/components/responses/CnpjInvalido" },
          "401": { "$ref": "#/components/responses/ChaveInvalida" },
          "402": { "$ref": "#/components/responses/LimiteGratis" },
          "403": { "$ref": "#/components/responses/Banido" },
          "404": { "$ref": "#/components/responses/NaoEncontrado" },
          "429": { "$ref": "#/components/responses/Bloqueado" }
        }
      }
    },
    "/cnpj/{cnpj}/socios": {
      "get": {
        "operationId": "listarSocios",
        "summary": "Sócios da empresa, com o CPF sempre mascarado",
        "description": "Os sócios e administradores da empresa. O CPF de pessoa física nunca sai inteiro: vem só a máscara. Para um CNPJ válido sem sócio registrado, a lista vem vazia (total 0).",
        "security": [{}, { "chave": [] }],
        "parameters": [{ "$ref": "#/components/parameters/cnpjPath" }],
        "responses": {
          "200": {
            "description": "Lista de sócios",
            "content": { "application/json": {
              "schema": { "$ref": "#/components/schemas/Socios" },
              "example": {
                "itens": [{ "tipo": { "codigo": "2", "descricao": "Pessoa física" }, "nome": "NOME DO SOCIO", "documento": "***********", "qualificacao": { "codigo": "49", "descricao": "Sócio-Administrador" }, "desde": "2026-09-04", "faixa_etaria": { "codigo": "4", "descricao": "31 a 40 anos" } }],
                "total": 1
              }
            } }
          },
          "400": { "$ref": "#/components/responses/CnpjInvalido" },
          "401": { "$ref": "#/components/responses/ChaveInvalida" },
          "402": { "$ref": "#/components/responses/LimiteGratis" },
          "403": { "$ref": "#/components/responses/Banido" },
          "429": { "$ref": "#/components/responses/Bloqueado" }
        }
      }
    },
    "/empresas": {
      "get": {
        "operationId": "buscarEmpresas",
        "summary": "Busca de empresas ativas pelo nome",
        "description": "Empresas ativas cujo nome fantasia ou razão social começa com o termo. Devolve até 50 empresas. O estado é opcional.",
        "security": [{}, { "chave": [] }],
        "parameters": [{ "$ref": "#/components/parameters/nome" }, { "$ref": "#/components/parameters/ufNome" }],
        "responses": {
          "200": {
            "description": "Empresas que começam com o termo",
            "content": { "application/json": {
              "schema": { "$ref": "#/components/schemas/Busca" },
              "example": {
                "empresas": [
                  { "cnpj": "20885605000114", "cnpj_formatado": "20.885.605/0001-14", "razao_social": "WORTICE ENERGIA LTDA EM RECUPERACAO JUDICIAL", "nome_fantasia": "", "matriz": true, "estabelecimentos_ativos": 2, "uf": "SP", "cidade": "SERTAOZINHO", "situacao": "Ativa" },
                  { "cnpj": "37853407000171", "cnpj_formatado": "37.853.407/0001-71", "razao_social": "WORTIC LTDA", "nome_fantasia": "", "matriz": true, "estabelecimentos_ativos": 1, "uf": "SP", "cidade": "SAO PAULO", "situacao": "Ativa" }
                ],
                "fonte": "Receita Federal, dados abertos do CNPJ (base Wortic); só empresas ativas",
                "termo": "wortic",
                "total": 2
              }
            } }
          },
          "400": { "$ref": "#/components/responses/TermoCurto" },
          "401": { "$ref": "#/components/responses/ChaveInvalida" },
          "402": { "$ref": "#/components/responses/LimiteGratis" },
          "403": { "$ref": "#/components/responses/Banido" },
          "429": { "$ref": "#/components/responses/Bloqueado" },
          "503": { "$ref": "#/components/responses/Indisponivel" }
        }
      }
    },
    "/v1/empresas/busca": {
      "get": {
        "operationId": "buscaPro",
        "summary": "Busca Pro: as empresas que passam nos filtros, por página",
        "description": "Plano Pro. Informe pelo menos um de cnae, uf, municipio, raio ou caixa. Cada página conta uma consulta. Sem chave, responde 402 com o código plano_pro.",
        "security": [{ "chave": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/cnae" }, { "$ref": "#/components/parameters/uf" }, { "$ref": "#/components/parameters/municipio" },
          { "$ref": "#/components/parameters/raio" }, { "$ref": "#/components/parameters/caixa" }, { "$ref": "#/components/parameters/porte" },
          { "$ref": "#/components/parameters/situacao" }, { "$ref": "#/components/parameters/capitalMin" }, { "$ref": "#/components/parameters/capitalMax" },
          { "$ref": "#/components/parameters/aberturaDe" }, { "$ref": "#/components/parameters/aberturaAte" }, { "$ref": "#/components/parameters/classeRenda" },
          { "$ref": "#/components/parameters/idhMin" }, { "$ref": "#/components/parameters/telefone" }, { "$ref": "#/components/parameters/email" },
          { "$ref": "#/components/parameters/matriz" }, { "$ref": "#/components/parameters/limite" }, { "$ref": "#/components/parameters/cursor" },
          { "$ref": "#/components/parameters/formato" }
        ],
        "responses": {
          "200": {
            "description": "Uma página. Em JSON, traz cursor e mais. Em csv e jsw, o cabeçalho x-cursor traz o cursor da próxima página, quando houver.",
            "headers": {
              "x-cursor": { "description": "Cursor da próxima página, quando houver.", "schema": { "type": "string" } },
              "x-pagina": { "description": "Quantas empresas vieram nesta página.", "schema": { "type": "integer" } },
              "x-examinadas": { "description": "Quantas empresas foram examinadas para montar a página.", "schema": { "type": "integer" } }
            },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Pagina" } },
              "text/csv": { "schema": { "type": "string" } },
              "application/vnd.wortic.jsonw": { "schema": { "type": "string", "format": "binary" } }
            }
          },
          "400": {
            "description": "Filtro ou parâmetro inválido. O código é o nome do parâmetro (ex.: uf, cnae), ou filtro_largo quando falta um dos filtros obrigatórios. A mensagem diz o formato certo. Não gasta consulta.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } }
          },
          "401": { "$ref": "#/components/responses/ChaveInvalida" },
          "402": { "$ref": "#/components/responses/PlanoPro" },
          "403": { "description": "Chave sem a busca Pro (sem_plano_pro), chave sem plano para esta consulta (sem_plano) ou espaço inativo (espaco_inativo). Não gasta consulta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
          "429": { "$ref": "#/components/responses/LimiteDoPlano" },
          "500": { "description": "A busca não saiu (codigo busca). Tente de novo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
          "503": { "$ref": "#/components/responses/Indisponivel" }
        }
      }
    },
    "/v1/empresas/parecidas": {
      "get": {
        "operationId": "parecidasPro",
        "summary": "Empresas ativas mais parecidas com uma, com nota e motivos",
        "description": "Plano Pro. Dado o CNPJ de uma empresa de referência, devolve as empresas ativas mais parecidas com ela, da maior nota para a menor, com os motivos de cada semelhança. Uma consulta por pedido. O CNPJ é conferido antes de gastar consulta.",
        "security": [{ "chave": [] }],
        "parameters": [{ "$ref": "#/components/parameters/cnpjQuery" }, { "$ref": "#/components/parameters/parecidasK" }],
        "responses": {
          "200": {
            "description": "As empresas parecidas, da maior nota para a menor",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Parecidas" } } }
          },
          "400": {
            "description": "CNPJ inválido (cnpj_invalido) ou k fora de 1 a 50 (codigo k). Não gasta consulta.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } }
          },
          "401": { "$ref": "#/components/responses/ChaveInvalida" },
          "402": { "$ref": "#/components/responses/PlanoPro" },
          "403": { "description": "Chave sem a rota Pro (sem_plano_pro), sem plano para esta consulta (sem_plano) ou espaço inativo (espaco_inativo).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
          "404": { "$ref": "#/components/responses/NaoEncontrado" },
          "429": { "$ref": "#/components/responses/LimiteDoPlano" },
          "503": { "$ref": "#/components/responses/Indisponivel" }
        }
      }
    },
    "/v1/empresas/avaliar": {
      "get": {
        "operationId": "avaliarPro",
        "summary": "As empresas de um filtro, avaliadas pelos critérios que você pesa",
        "description": "Plano Pro. Usa os mesmos filtros da busca e avalia as primeiras empresas do filtro, na ordem do CNPJ (amostra). Cada critério em pesos vai de 0 a 10. Devolve as k melhores, com a nota e quanto cada critério somou. Uma consulta por avaliação. Os pesos e o filtro são conferidos antes de gastar consulta.",
        "security": [{ "chave": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/cnae" }, { "$ref": "#/components/parameters/uf" }, { "$ref": "#/components/parameters/municipio" },
          { "$ref": "#/components/parameters/raio" }, { "$ref": "#/components/parameters/caixa" }, { "$ref": "#/components/parameters/porte" },
          { "$ref": "#/components/parameters/situacao" }, { "$ref": "#/components/parameters/capitalMin" }, { "$ref": "#/components/parameters/capitalMax" },
          { "$ref": "#/components/parameters/aberturaDe" }, { "$ref": "#/components/parameters/aberturaAte" }, { "$ref": "#/components/parameters/classeRenda" },
          { "$ref": "#/components/parameters/idhMin" }, { "$ref": "#/components/parameters/telefone" }, { "$ref": "#/components/parameters/email" },
          { "$ref": "#/components/parameters/matriz" },
          { "$ref": "#/components/parameters/pesos" }, { "$ref": "#/components/parameters/avaliarK" }, { "$ref": "#/components/parameters/amostra" }
        ],
        "responses": {
          "200": {
            "description": "As k melhores, com o quanto cada critério somou",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Avaliadas" } } }
          },
          "400": {
            "description": "Filtro, pesos, k ou amostra inválidos (o código é o nome do parâmetro, ou pesos). Não gasta consulta.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } }
          },
          "401": { "$ref": "#/components/responses/ChaveInvalida" },
          "402": { "$ref": "#/components/responses/PlanoPro" },
          "403": { "description": "Chave sem a rota Pro (sem_plano_pro), sem plano para esta consulta (sem_plano) ou espaço inativo (espaco_inativo).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
          "429": { "$ref": "#/components/responses/LimiteDoPlano" },
          "503": { "$ref": "#/components/responses/Indisponivel" }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcpPublico",
        "summary": "Conector MCP aberto (JSON-RPC 2.0), sem chave",
        "description": "O servidor MCP da API aberta. Ferramentas: consultar_cnpj, listar_socios e buscar_empresa. Cada chamada de ferramenta conta no limite do IP e na escada de bloqueio. Quando o limite estoura, a ferramenta responde com isError e a mensagem, sem HTTP 402. Só responde POST; GET responde 405. A versão do protocolo é a negociada no initialize (2025-06-18, 2025-03-26 ou 2024-11-05).",
        "security": [{}],
        "requestBody": {
          "required": true,
          "content": { "application/json": {
            "schema": { "$ref": "#/components/schemas/PedidoMcp" },
            "examples": {
              "listarFerramentas": { "summary": "Listar as ferramentas", "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } },
              "consultarCnpj": { "summary": "Consultar um CNPJ", "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "consultar_cnpj", "arguments": { "cnpj": "37853407000171" } } } }
            }
          } }
        },
        "responses": {
          "200": {
            "description": "Resposta JSON-RPC: result, ou error com código -32700 (JSON inválido), -32600 (pedido inválido), -32601 (método desconhecido) ou -32602 (parâmetros inválidos).",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RespostaMcp" } } }
          }
        }
      }
    },
    "/saude": {
      "get": {
        "operationId": "saude",
        "summary": "Verificação do serviço",
        "description": "Diz se o serviço está no ar. Não conta no limite.",
        "security": [{}],
        "responses": {
          "200": {
            "description": "Serviço no ar",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": ["ok"] }, "example": { "ok": true } } }
          }
        }
      }
    },
    "/cnpj": {
      "get": {
        "operationId": "cnpjSemNumero",
        "summary": "Sem CNPJ na rota",
        "description": "/cnpj e /cnpj/ sem o número respondem 400 cnpj_invalido, sem gastar consulta. Para consultar, use /cnpj/{cnpj}.",
        "security": [{}],
        "responses": {
          "400": { "$ref": "#/components/responses/CnpjInvalido" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "chave": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Chave do plano da Wortic. Sem ela, vale o limite grátis por IP." }
    },
    "parameters": {
      "cnpjPath": { "name": "cnpj", "in": "path", "required": true, "description": "14 caracteres, com ou sem pontuação. Aceita o CNPJ alfanumérico.", "schema": { "type": "string" }, "example": "37853407000171" },
      "cnpjQuery": { "name": "cnpj", "in": "query", "required": true, "description": "O CNPJ da empresa de referência, com ou sem pontuação.", "schema": { "type": "string" }, "example": "37853407000171" },
      "nome": { "name": "nome", "in": "query", "required": true, "description": "Razão social ou nome fantasia, pelo menos 4 letras.", "schema": { "type": "string", "minLength": 4 }, "example": "wortic" },
      "ufNome": { "name": "uf", "in": "query", "required": false, "description": "Sigla do estado.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "SP" },
      "cnae": { "name": "cnae", "in": "query", "description": "Códigos CNAE de 7 dígitos, separados por vírgula (até 50). Vale o CNAE principal.", "schema": { "type": "string" }, "example": "1091102" },
      "uf": { "name": "uf", "in": "query", "description": "Siglas dos estados, separadas por vírgula.", "schema": { "type": "string" }, "example": "RS,SC" },
      "municipio": { "name": "municipio", "in": "query", "description": "Códigos IBGE de 7 dígitos, separados por vírgula (até 100).", "schema": { "type": "string" }, "example": "4314902" },
      "raio": { "name": "raio", "in": "query", "description": "lat,lon,km: municípios cujo centro fica a até km do ponto (até 500 km).", "schema": { "type": "string" }, "example": "-30.0346,-51.2177,15" },
      "caixa": { "name": "caixa", "in": "query", "description": "lat_sul,lon_oeste,lat_norte,lon_leste: a área do mapa.", "schema": { "type": "string" }, "example": "-23.7,-46.8,-23.4,-46.4" },
      "porte": { "name": "porte", "in": "query", "schema": { "type": "string", "enum": ["me", "epp", "demais", "nao_informado"] } },
      "situacao": { "name": "situacao", "in": "query", "description": "Padrão: ativa.", "schema": { "type": "string", "enum": ["ativa", "suspensa", "inapta", "baixada", "nula"] } },
      "capitalMin": { "name": "capital_min", "in": "query", "description": "Capital social mínimo em reais, até 2 casas decimais.", "schema": { "type": "string", "pattern": "^[0-9]+([.,][0-9]{1,2})?$" }, "example": "150000" },
      "capitalMax": { "name": "capital_max", "in": "query", "description": "Capital social máximo em reais, até 2 casas decimais.", "schema": { "type": "string", "pattern": "^[0-9]+([.,][0-9]{1,2})?$" }, "example": "1500.50" },
      "aberturaDe": { "name": "abertura_de", "in": "query", "description": "Data de abertura, AAAA-MM-DD.", "schema": { "type": "string", "format": "date" } },
      "aberturaAte": { "name": "abertura_ate", "in": "query", "description": "Data de abertura, AAAA-MM-DD.", "schema": { "type": "string", "format": "date" } },
      "classeRenda": { "name": "classe_renda", "in": "query", "description": "Classes de renda do CEP da empresa, de A a E, separadas por vírgula. Fonte: IBGE, Censo 2022.", "schema": { "type": "string", "pattern": "^[A-Ea-e](,[A-Ea-e])*$" }, "example": "A,B" },
      "idhMin": { "name": "idh_min", "in": "query", "description": "IDH mínimo do CEP da empresa, de 0 a 1.", "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "example": 0.8 },
      "telefone": { "name": "telefone", "in": "query", "description": "1 só com telefone, 0 só sem.", "schema": { "type": "integer", "enum": [0, 1] } },
      "email": { "name": "email", "in": "query", "description": "1 só com e-mail, 0 só sem.", "schema": { "type": "integer", "enum": [0, 1] } },
      "matriz": { "name": "matriz", "in": "query", "description": "1 só matrizes, 0 só filiais.", "schema": { "type": "integer", "enum": [0, 1] } },
      "limite": { "name": "limite", "in": "query", "description": "Empresas por página.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } },
      "cursor": { "name": "cursor", "in": "query", "description": "O cursor da página anterior, de 14 caracteres.", "schema": { "type": "string", "minLength": 14, "maxLength": 14 } },
      "formato": { "name": "formato", "in": "query", "description": "json traz a ficha inteira de cada empresa; csv serve para planilha; jsw é o arquivo jsonW, com esquema e conferência SHA-256 de cada bloco.", "schema": { "type": "string", "enum": ["json", "csv", "jsw"], "default": "json" } },
      "pesos": { "name": "pesos", "in": "query", "required": true, "description": "Critério:peso separados por vírgula. Critérios: capital, contato, idh, novas e maduras. Peso de 0 a 10.", "schema": { "type": "string" }, "example": "capital:2,contato:1" },
      "avaliarK": { "name": "k", "in": "query", "description": "Quantas empresas devolver, de 1 a 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } },
      "parecidasK": { "name": "k", "in": "query", "description": "Quantas empresas devolver, de 1 a 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } },
      "amostra": { "name": "amostra", "in": "query", "description": "Quantas empresas do filtro avaliar, na ordem do CNPJ, de 100 a 2.000.", "schema": { "type": "integer", "minimum": 100, "maximum": 2000, "default": 500 } }
    },
    "headers": {
      "xBaseCnpj": { "description": "Mês da base da Receita Federal, AAAA-MM.", "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" } },
      "xRatelimitLimitDia": { "description": "Teto diário sem chave, por IP: 2000.", "schema": { "type": "integer" } },
      "xRatelimitRestanteDia": { "description": "Consultas que ainda cabem hoje, sem chave, por IP.", "schema": { "type": "integer" } },
      "retryAfter": { "description": "Segundos até tentar de novo. No limite do minuto, 60. No limite do dia, os segundos até a meia-noite de Brasília. No bloqueio, os segundos que faltam.", "schema": { "type": "integer" } },
      "paymentRequired": { "description": "Desafio x402 v2 em base64 (JSON com accepts, valor em centavos e moeda BRL).", "schema": { "type": "string" } },
      "wwwAuthenticate": { "description": "Desafio MPP (Payment), com o método pix.", "schema": { "type": "string" } }
    },
    "responses": {
      "CnpjInvalido": { "description": "CNPJ com dígitos verificadores que não conferem. Não gasta consulta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "example": { "erro": { "codigo": "cnpj_invalido", "mensagem": "CNPJ invalido (confira os digitos)." } } } } },
      "TermoCurto": { "description": "Busca por nome com menos de 4 letras.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "example": { "erro": { "codigo": "termo_curto", "mensagem": "Digite pelo menos 4 letras do nome da empresa." } } } } },
      "NaoEncontrado": { "description": "CNPJ válido que não está na base da Receita.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "CNPJ nao encontrado na base da Receita." } } } } },
      "LimiteGratis": {
        "description": "Sem chave, passou do limite do minuto (60) ou do dia (2.000) por IP (codigo limite_gratis). A resposta traz os planos com o link de compra de cada um. O retry-after diz quanto esperar: 60 segundos no minuto, e até a meia-noite de Brasília no dia.",
        "headers": {
          "retry-after": { "$ref": "#/components/headers/retryAfter" },
          "payment-required": { "$ref": "#/components/headers/paymentRequired" },
          "www-authenticate": { "$ref": "#/components/headers/wwwAuthenticate" }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroPlanos" } } }
      },
      "PlanoPro": {
        "description": "Rota do plano Pro chamada sem x-api-key (codigo plano_pro). A resposta traz o plano Pro, mensal e anual, com o link de compra.",
        "headers": {
          "payment-required": { "$ref": "#/components/headers/paymentRequired" },
          "www-authenticate": { "$ref": "#/components/headers/wwwAuthenticate" }
        },
        "content": { "application/json": {
          "schema": { "$ref": "#/components/schemas/ErroPlanos" },
          "example": {
            "erro": { "codigo": "plano_pro", "mensagem": "Esta rota é do plano Pro. Assine um plano ou mande a sua chave no cabeçalho x-api-key." },
            "planos": [
              { "plano": "api-dados-pro", "periodo": "mensal", "centavos": 9900, "moeda": "BRL", "compra": "https://app.wortic.com/comprar/api-dados-pro-mensal" },
              { "plano": "api-dados-pro", "periodo": "anual", "centavos": 99000, "moeda": "BRL", "compra": "https://app.wortic.com/comprar/api-dados-pro-anual" }
            ]
          }
        } }
      },
      "Bloqueado": { "description": "IP bloqueado pela escada (codigo bloqueado). O retry-after traz os segundos que faltam. Enquanto o bloqueio dura, a resposta é 429, não 402.", "headers": { "retry-after": { "$ref": "#/components/headers/retryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
      "Banido": { "description": "IP banido da API aberta por estourar a escada (codigo banido). Para usar a API, fale com a Wortic.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "example": { "erro": { "codigo": "banido", "mensagem": "Este IP foi banido da API aberta por estourar o limite repetidas vezes. Para usar a API, fale com a Wortic." } } } } },
      "ChaveInvalida": { "description": "Chave inválida ou revogada (codigo chave_invalida, 401), ou cabeçalho x-api-key repetido ou grande demais (codigo chave_repetida ou chave_invalida, 400).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
      "LimiteDoPlano": { "description": "Com chave, o limite do plano acabou (codigo limite_do_plano): no minuto, no dia ou no mês, conforme a mensagem.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
      "Indisponivel": { "description": "Serviço indisponível agora (codigo indisponivel). Tente de novo em seguida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }
    },
    "schemas": {
      "Erro": {
        "type": "object",
        "required": ["erro"],
        "properties": { "erro": { "type": "object", "required": ["codigo", "mensagem"], "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" } } } }
      },
      "Plano": {
        "type": "object",
        "required": ["plano", "periodo", "centavos", "moeda", "compra"],
        "properties": {
          "plano": { "type": "string" },
          "periodo": { "type": "string", "enum": ["mensal", "anual"] },
          "centavos": { "type": "integer", "description": "Preço em centavos de real." },
          "moeda": { "type": "string", "example": "BRL" },
          "compra": { "type": "string", "format": "uri" }
        }
      },
      "ErroPlanos": {
        "type": "object",
        "required": ["erro", "planos"],
        "properties": {
          "erro": { "type": "object", "required": ["codigo", "mensagem"], "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" } } },
          "planos": { "type": "array", "items": { "$ref": "#/components/schemas/Plano" } }
        }
      },
      "Codigo": {
        "type": "object",
        "properties": { "codigo": { "type": ["string", "integer"] }, "descricao": { "type": "string" } }
      },
      "Ficha": {
        "type": "object",
        "required": ["cnpj", "cnpj_formatado", "razao_social", "situacao", "abertura", "cnae_principal", "cnaes_secundarios", "natureza_juridica", "capital_social", "porte", "simples", "mei", "endereco", "telefone", "email", "fonte"],
        "properties": {
          "cnpj": { "type": "string", "description": "14 caracteres, numéricos ou alfanuméricos." },
          "cnpj_formatado": { "type": "string" },
          "razao_social": { "type": "string" },
          "nome_fantasia": { "type": "string", "description": "Vazio quando a empresa não tem." },
          "tipo": { "$ref": "#/components/schemas/Codigo" },
          "situacao": { "type": "object", "required": ["codigo", "descricao"], "properties": { "codigo": { "type": "integer" }, "descricao": { "type": "string" }, "desde": { "type": ["string", "null"], "format": "date" } } },
          "abertura": { "type": ["string", "null"], "format": "date" },
          "cnae_principal": { "$ref": "#/components/schemas/Codigo" },
          "cnaes_secundarios": { "type": "array", "items": { "$ref": "#/components/schemas/Codigo" } },
          "natureza_juridica": { "$ref": "#/components/schemas/Codigo" },
          "capital_social": { "type": ["number", "null"] },
          "porte": { "$ref": "#/components/schemas/Codigo" },
          "simples": { "type": ["boolean", "null"] },
          "mei": { "type": ["boolean", "null"] },
          "endereco": {
            "type": "object",
            "properties": {
              "tipo_logradouro": { "type": "string" }, "logradouro": { "type": "string" }, "numero": { "type": "string" },
              "complemento": { "type": "string" }, "bairro": { "type": "string" }, "cep": { "type": "string" },
              "cidade": { "type": "string" }, "cidade_ibge": { "type": ["integer", "null"] }, "uf": { "type": "string" }
            }
          },
          "telefone": { "type": "string", "description": "O telefone que a empresa informou à Receita. Pode estar vazio ou desatualizado." },
          "email": { "type": "string", "description": "O e-mail que a empresa informou à Receita. Pode estar vazio ou desatualizado." },
          "fonte": { "type": "string" }
        }
      },
      "Socios": {
        "type": "object",
        "required": ["itens", "total"],
        "properties": {
          "itens": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tipo": { "$ref": "#/components/schemas/Codigo" },
                "nome": { "type": "string" },
                "documento": { "type": "string", "description": "Sempre mascarado para pessoa física." },
                "qualificacao": { "$ref": "#/components/schemas/Codigo" },
                "desde": { "type": ["string", "null"], "format": "date" },
                "faixa_etaria": { "$ref": "#/components/schemas/Codigo" }
              }
            }
          },
          "total": { "type": "integer" }
        }
      },
      "Busca": {
        "type": "object",
        "required": ["empresas", "fonte", "termo", "total"],
        "properties": {
          "empresas": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "cnpj": { "type": "string" }, "cnpj_formatado": { "type": "string" }, "razao_social": { "type": "string" },
                "nome_fantasia": { "type": "string" }, "matriz": { "type": "boolean" }, "estabelecimentos_ativos": { "type": "integer" },
                "uf": { "type": "string" }, "cidade": { "type": "string" }, "situacao": { "type": "string" }
              }
            }
          },
          "fonte": { "type": "string" },
          "termo": { "type": "string" },
          "total": { "type": "integer" }
        }
      },
      "Pagina": {
        "type": "object",
        "required": ["empresas", "cursor", "mais"],
        "properties": {
          "empresas": { "type": "array", "items": { "$ref": "#/components/schemas/Ficha" } },
          "cursor": { "type": ["string", "null"] },
          "mais": { "type": "boolean" }
        }
      },
      "Parecidas": {
        "type": "object",
        "required": ["referencia", "empresas"],
        "properties": {
          "referencia": { "type": "object", "properties": { "cnpj": { "type": "string" }, "cnae": { "type": ["string", "null"] }, "ramo": { "type": ["string", "null"] } } },
          "empresas": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "cnpj": { "type": "string" }, "razao_social": { "type": ["string", "null"] }, "cidade": { "type": ["string", "null"] }, "uf": { "type": ["string", "null"] },
                "nota": { "type": "integer", "minimum": 0, "maximum": 100 },
                "cnae": { "type": ["string", "null"] }, "ramo": { "type": ["string", "null"] },
                "motivos": { "type": "array", "items": { "type": "string" } }
              }
            }
          }
        }
      },
      "Avaliadas": {
        "type": "object",
        "required": ["avaliadas", "completo", "medida", "empresas"],
        "properties": {
          "avaliadas": { "type": "integer", "description": "Quantas empresas do filtro foram avaliadas (até a amostra)." },
          "completo": { "type": "boolean", "description": "true quando o filtro coube inteiro na amostra." },
          "medida": { "type": "object", "properties": { "coleta_ms": { "type": "integer" }, "nota_ms": { "type": "integer" } } },
          "empresas": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "cnpj": { "type": "string" }, "razao_social": { "type": ["string", "null"] }, "cidade": { "type": ["string", "null"] }, "uf": { "type": ["string", "null"] },
                "nota": { "type": "number", "description": "Nota com uma casa decimal." },
                "por_eixo": { "type": "object", "description": "Quanto cada critério pesado somou na nota.", "additionalProperties": { "type": "number" } }
              }
            }
          }
        }
      },
      "PedidoMcp": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "integer", "null"] },
          "method": { "type": "string", "enum": ["initialize", "tools/list", "tools/call", "ping"] },
          "params": { "type": "object" }
        }
      },
      "RespostaMcp": {
        "type": "object",
        "required": ["jsonrpc"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "integer", "null"] },
          "result": { "type": "object" },
          "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } }
        }
      }
    }
  }
}
