{
    "status": "info",
    "api": "Consulta de Registros de Prospecção por CNPJ",
    "versao": "2.0.0",
    "descricao": "Retorna eventos e registros de prospecção associados a um CNPJ específico, com filtros otimizados usando índices.",
    "metodo_esperado": "POST",
    "content_type": "application\/json",
    "formato_corpo": "JSON (não form-urlencoded)",
    "autenticacao": {
        "obrigatorio": "id_do_usuario (preferencial) OU ip",
        "observacao": "O uso de id_do_usuario é fortemente recomendado por segurança"
    },
    "parametros_obrigatorios": {
        "cnpj": {
            "tipo": "string",
            "formato": "exatamente 14 dígitos numéricos (sem pontos, traços ou barras)",
            "exemplo": "12345678000195"
        }
    },
    "parametros_opcionais": {
        "id_do_usuario": {
            "tipo": "integer",
            "descricao": "ID do usuário no sistema Linktudo",
            "exemplo": 4587
        },
        "ip": {
            "tipo": "string",
            "descricao": "Endereço IP do usuário (fallback - menos seguro)",
            "exemplo": "189.45.67.123"
        },
        "status": {
            "tipo": "string",
            "descricao": "Filtrar por status da prospecção (usa índice idx_status)",
            "exemplos": [
                "Aberto",
                "Fechado",
                "Agendado",
                "Perdido",
                "Ganho"
            ]
        },
        "tipo_evento": {
            "tipo": "string",
            "descricao": "Tipo específico do evento (usa índice idx_tipo_evento)",
            "exemplos": [
                "Reunião",
                "Ligação",
                "Proposta Enviada",
                "Visita Técnica"
            ]
        },
        "apenas_agendados": {
            "tipo": "boolean (1 ou 0)",
            "descricao": "Retornar apenas registros que possuem data de agendamento (usa índice idx_data_agendamento)"
        },
        "data_inicio": {
            "tipo": "date",
            "formato": "YYYY-MM-DD",
            "descricao": "Data inicial (base: data_hora_registro - usa índice idx_data_registro)"
        },
        "data_fim": {
            "tipo": "date",
            "formato": "YYYY-MM-DD",
            "descricao": "Data final (base: data_hora_registro - usa índice idx_data_registro)"
        },
        "ordenar_por": {
            "tipo": "string",
            "valores_permitidos": [
                "mais_recente",
                "agendamento",
                "valor_desc",
                "mais_antigo"
            ],
            "padrao": "mais_recente",
            "observacao": "Para melhor performance, use ordenação que utilize índices existentes"
        },
        "limite": {
            "tipo": "integer",
            "descricao": "Quantidade máxima de registros retornados",
            "padrao": 150,
            "intervalo": "1–500"
        },
        "pagina": {
            "tipo": "integer",
            "descricao": "Número da página para paginação",
            "padrao": 1,
            "minimo": 1
        },
        "itens_por_pagina": {
            "tipo": "integer",
            "descricao": "Itens por página para paginação",
            "padrao": 50,
            "intervalo": "1–100"
        },
        "excluir_datas_zero": {
            "tipo": "boolean (1 ou 0)",
            "descricao": "Excluir campos de data com valor zero (0000-00-00) do formato ISO",
            "padrao": 1
        },
        "campos": {
            "tipo": "string (separados por vírgula)",
            "descricao": "Lista de campos específicos para retornar",
            "exemplo": "id,cnpj,nome,data_hora_registro,valor_acordado"
        },
        "cpf": {
            "tipo": "string",
            "descricao": "Filtrar também por CPF (usa índice idx_cpf)",
            "formato": "11 dígitos numéricos",
            "exemplo": "12345678901"
        },
        "data_agendamento_inicio": {
            "tipo": "date",
            "formato": "YYYY-MM-DD",
            "descricao": "Data inicial para agendamentos (usa índice idx_data_agendamento)"
        },
        "data_agendamento_fim": {
            "tipo": "date",
            "formato": "YYYY-MM-DD",
            "descricao": "Data final para agendamentos (usa índice idx_data_agendamento)"
        },
        "data_prazo_inicio": {
            "tipo": "date",
            "formato": "YYYY-MM-DD",
            "descricao": "Data inicial para prazo de entrega (usa índice idx_data_prazo_entrega)"
        },
        "data_prazo_fim": {
            "tipo": "date",
            "formato": "YYYY-MM-DD",
            "descricao": "Data final para prazo de entrega (usa índice idx_data_prazo_entrega)"
        }
    },
    "indices_utilizados": {
        "idx_cnpj": "Busca principal por CNPJ",
        "idx_usuario": "Filtro por usuário",
        "idx_usuario_status": "Usuário + Status",
        "idx_usuario_tipo": "Usuário + Tipo de Evento",
        "idx_status": "Filtro por Status",
        "idx_tipo_evento": "Filtro por Tipo de Evento",
        "idx_data_registro": "Filtro por Data de Registro",
        "idx_data_agendamento": "Filtro por Data de Agendamento",
        "idx_cpf": "Filtro por CPF",
        "idx_data_prazo_entrega": "Filtro por Prazo de Entrega"
    },
    "exemplo_requisicao_minima": {
        "cnpj": "12345678000195",
        "id_do_usuario": 4587
    },
    "exemplo_requisicao_completa": {
        "cnpj": "12345678000195",
        "id_do_usuario": 4587,
        "status": "Aberto",
        "tipo_evento": "Reunião",
        "apenas_agendados": true,
        "data_inicio": "2025-11-01",
        "data_fim": "2026-02-28",
        "data_agendamento_inicio": "2026-01-01",
        "data_agendamento_fim": "2026-02-28",
        "ordenar_por": "agendamento",
        "limite": 50,
        "pagina": 1,
        "itens_por_pagina": 20,
        "excluir_datas_zero": true,
        "campos": "id,cnpj,nome,data_hora_registro,valor_acordado,status_prospeccao"
    },
    "campos_disponiveis": [
        "id",
        "id_do_usuario___linktudo",
        "cnpj",
        "nome",
        "cpf",
        "entidade",
        "data_hora_registro",
        "data_hora_agendamento",
        "assunto",
        "descricao",
        "tipo_evento",
        "contato_estabelecido_via",
        "valor_acordado",
        "status_prospeccao",
        "data_hora_prazo_acordado_entrega",
        "observacao",
        "data_hora_atualizacao"
    ],
    "observacoes": [
        "Enviar dados no corpo da requisição como JSON",
        "Datas \"0000-00-00 00:00:00\" são tratadas como inválidas e retornam null no formato ISO",
        "Consulta otimizada para usar índices MySQL disponíveis",
        "Máximo de 500 registros por requisição (sem paginação)",
        "Para melhor performance, combine filtros que usam índices compostos"
    ],
    "codigos_http": {
        "200": "Sucesso ou documentação",
        "400": "Parâmetros inválidos ou insuficientes",
        "405": "Método não permitido (esperado: POST)",
        "500": "Erro interno no servidor"
    }
}