{"openapi":"3.0.3","info":{"title":"Prospector API","version":"1.0.0","description":"API pública do Prospector.\n\n## Autenticação\nEnvie o token no cabeçalho `Authorization: Bearer psk_...` (o header `x-api-key` também é aceito).\nOs tokens são criados em Configurações → API, e o valor completo aparece uma única vez.\n\n## Limite de uso\nCada token tem um teto por minuto (padrão 60). As respostas trazem `X-RateLimit-Limit` e\n`X-RateLimit-Remaining`; ao estourar, a API responde 429 com `Retry-After` em segundos.\n\n## Escopos\n- `leads:read`\n- `leads:write`\n- `search:run`\n- `enrich:run`\n\n## Webhooks\nCadastre URLs em Configurações → API para receber eventos. Cada entrega leva o cabeçalho\n`X-Prospector-Signature: sha256=<hmac>`, calculado sobre o corpo exato com o segredo do endpoint.\nEventos: `lead.created`, `lead.stage_changed`, `lead.replied`, `cadence.failed`, `company.new`."},"servers":[{"url":"https://prospector.machinenodes.com.br/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token no formato psk_..."}},"schemas":{"Lead":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"razao_social":{"type":"string","nullable":true},"cnpj":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"whatsapp":{"type":"string","nullable":true},"emails":{"type":"array","items":{"type":"string"}},"website":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"partners":{"type":"array","items":{"type":"string"}},"stage":{"type":"string","nullable":true},"status":{"type":"string"},"contacted":{"type":"boolean"},"replied":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"paths":{"/leads":{"get":{"operationId":"listarLeads","summary":"Lista leads","description":"Escopo necessário: `leads:read`.","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"Nome, razão social, CNPJ ou telefone."},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string"},"description":"Sigla da UF."},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"},"description":"RAW_UNVALIDATED, VALIDATED_WHATSAPP, DISCARDED..."},{"name":"contacted","in":"query","schema":{"type":"boolean"}},{"name":"created_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Lista paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"401":{"description":"Token ausente ou inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite por minuto atingido"}}},"post":{"operationId":"criarLead","summary":"Cria um lead","description":"Escopo: `leads:write`. Se já existir lead com o mesmo telefone, devolve o existente com `duplicated: true`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"phone":{"type":"string"},"emails":{"type":"array","items":{"type":"string"}},"website":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"category":{"type":"string"},"cnpj":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Já existia"},"201":{"description":"Criado"}}}},"/leads/{id}":{"get":{"operationId":"obterLead","summary":"Detalhe do lead, com o histórico da conversa","description":"Escopo: `leads:read`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Não encontrado"}}}},"/search":{"get":{"operationId":"listarNichos","summary":"Catálogo de nichos disponíveis","description":"Escopo: `leads:read`.","responses":{"200":{"description":"OK"}}},"post":{"operationId":"buscarEmpresas","summary":"Busca empresas na base de prospecção e importa as inéditas","description":"Escopo: `search:run`. Respeita a cota de leads do plano.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["niche_id","uf"],"properties":{"niche_id":{"type":"string"},"sub_filter_id":{"type":"string"},"uf":{"type":"string"},"municipio":{"type":"string"},"portes":{"type":"array","items":{"type":"string","enum":["01","03","05"]}},"max_results":{"type":"integer","default":50,"maximum":200}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Limite do plano"}}}},"/enrich":{"post":{"operationId":"enriquecerLeads","summary":"Enfileira leads para enriquecimento","description":"Escopo: `enrich:run`. Processamento assíncrono.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lead_ids"],"properties":{"lead_ids":{"type":"array","items":{"type":"string"},"maxItems":100}}}}}},"responses":{"200":{"description":"OK"}}}}}}