{
    "tipo": "documentacao",
    "versao": "1.0",
    "titulo": "API de Consulta CNAE",
    "descricao": "API para consulta da Classificação Nacional de Atividades Econômicas (CNAE)",
    "seguranca": {
        "aviso": "Esta documentação contém apenas informações conceituais sobre o uso da API.",
        "dados_sensiveis": "Nenhuma credencial, configuração interna ou dados sensíveis são expostos."
    },
    "endpoint": {
        "url": "https:\/\/linktudo.com.br\/apis\/linktudo.com.br\/cnpj\/api\/v1\/busca_cnae___endpoint_api.php",
        "metodo": "POST",
        "formato": "application\/json"
    },
    "parametros": [
        {
            "nome": "termo_de_busca",
            "tipo": "string",
            "obrigatorio": true,
            "descricao": "Termo para buscar CNAEs. Pode ser o código (ex: \"5229099\") ou parte da descrição (ex: \"transporte\")."
        },
        {
            "nome": "modo",
            "tipo": "string",
            "obrigatorio": false,
            "valores_permitidos": [
                "detalhado",
                "sugestoes"
            ],
            "padrao": "detalhado",
            "descricao": "Modo de consulta: \"detalhado\" retorna estatísticas completas, \"sugestoes\" retorna apenas códigos e descrições (ideal para autocomplete)."
        },
        {
            "nome": "limite",
            "tipo": "integer",
            "obrigatorio": false,
            "padrao": 1000,
            "maximo": 1000000,
            "descricao": "Número máximo de resultados a serem retornados. Use valores menores para melhor performance."
        }
    ],
    "exemplos": [
        {
            "titulo": "Busca por código CNAE",
            "descricao": "Buscar um CNAE específico pelo código",
            "requisicao": {
                "termo_de_busca": "5229099",
                "modo": "detalhado"
            }
        },
        {
            "titulo": "Busca por descrição (autocomplete)",
            "descricao": "Buscar sugestões de CNAEs que contenham \"transporte\"",
            "requisicao": {
                "termo_de_busca": "transporte",
                "modo": "sugestoes",
                "limite": 10
            }
        }
    ],
    "resposta": {
        "estrutura": {
            "status": {
                "tipo": "string",
                "descricao": "Estado da operação: \"sucesso\" ou \"erro\""
            },
            "mensagem": {
                "tipo": "string",
                "descricao": "Texto descritivo sobre o resultado da operação"
            },
            "info": {
                "tipo": "object",
                "propriedades": {
                    "tempo_processamento": {
                        "tipo": "string",
                        "descricao": "Tempo de processamento da consulta em segundos"
                    },
                    "total_encontrado": {
                        "tipo": "integer",
                        "descricao": "TOTAL de atividades que correspondem à busca (incluindo as não exibidas)"
                    },
                    "quantidade_exibida": {
                        "tipo": "integer",
                        "descricao": "Número de resultados retornados (limitado pelo parâmetro \"limite\")"
                    },
                    "modo_consulta": {
                        "tipo": "string",
                        "descricao": "Modo de consulta utilizado"
                    },
                    "autenticacao_ativa": {
                        "tipo": "boolean",
                        "descricao": "Indica se a autenticação por token está ativa"
                    }
                }
            },
            "resultados": {
                "tipo": "array",
                "descricao": "Lista de CNAEs encontrados (prioriza os que começam com o termo)",
                "itens": {
                    "cnae_codigo": {
                        "tipo": "string",
                        "descricao": "Código CNAE de 7 dígitos"
                    },
                    "descricao": {
                        "tipo": "string",
                        "descricao": "Descrição preferida (alternativa ou oficial)"
                    },
                    "descricao_oficial": {
                        "tipo": "string",
                        "descricao": "Descrição oficial do CNAE conforme IBGE"
                    },
                    "descricao_alternativa": {
                        "tipo": "string",
                        "descricao": "Descrição alternativa (quando disponível)"
                    },
                    "estatisticas": {
                        "tipo": "object",
                        "descricao": "Estatísticas de uso do CNAE (apenas no modo detalhado)",
                        "propriedades": {
                            "principal": {
                                "tipo": "integer",
                                "descricao": "Quantidade de estabelecimentos com este CNAE como principal"
                            },
                            "secundario": {
                                "tipo": "integer",
                                "descricao": "Quantidade de estabelecimentos com este CNAE como secundário"
                            },
                            "total": {
                                "tipo": "integer",
                                "descricao": "Total de estabelecimentos com este CNAE"
                            }
                        }
                    }
                }
            }
        },
        "exemplo_completo": {
            "status": "sucesso",
            "mensagem": "5 resultado(s) encontrado(s) para o termo: \"transporte\"",
            "info": {
                "tempo_processamento": "0.0123s",
                "total_encontrado": 47,
                "quantidade_exibida": 5,
                "modo_consulta": "detalhado",
                "autenticacao_ativa": false
            },
            "resultados": [
                {
                    "cnae_codigo": "5229099",
                    "descricao": "Transporte rodoviário de cargas",
                    "descricao_oficial": "Transporte rodoviário de carga, exceto produtos perigosos",
                    "descricao_alternativa": "Transporte de cargas",
                    "estatisticas": {
                        "principal": 1500,
                        "secundario": 300,
                        "total": 1800
                    }
                }
            ]
        }
    },
    "codigos_http": [
        {
            "codigo": 200,
            "descricao": "Sucesso - Requisição processada corretamente",
            "icone": "✅"
        },
        {
            "codigo": 400,
            "descricao": "Erro de requisição - Parâmetros inválidos ou ausentes",
            "icone": "❌"
        },
        {
            "codigo": 401,
            "descricao": "Não autorizado - Token inválido (quando autenticação está ativa)",
            "icone": "🔒"
        },
        {
            "codigo": 403,
            "descricao": "Acesso negado - Token expirado ou sem permissão",
            "icone": "🚫"
        },
        {
            "codigo": 405,
            "descricao": "Método não permitido - Use POST",
            "icone": "⛔"
        },
        {
            "codigo": 500,
            "descricao": "Erro interno do servidor",
            "icone": "💥"
        }
    ],
    "dicas": [
        "Use o modo \"sugestoes\" para implementar autocomplete em formulários.",
        "Para melhor performance, sempre defina um \"limite\" adequado à sua necessidade.",
        "O campo \"descricao\" retorna a melhor descrição disponível (alternativa ou oficial).",
        "As estatísticas mostram a relevância do CNAE no mercado.",
        "O campo \"total_encontrado\" mostra quantas atividades existem no total para o termo buscado.",
        "Os resultados são ordenados priorizando os que COMEÇAM com o termo de busca."
    ],
    "informacoes_tecnicas": {
        "charset": "UTF-8",
        "formato_resposta": "JSON",
        "cors": "Habilitado para todos os domínios",
        "metodos_aceitos": [
            "POST",
            "OPTIONS"
        ]
    }
}