{"openapi":"3.1.0","info":{"title":"Faro — API","version":"1.0.0","description":"API pública do Faro (BRV Prospect): pesquisa na base de CNPJs da Receita Federal, leads e \"não quero contato\".\n\nAutenticação: crie a chave no painel (Configurações › API) e envie `Authorization: Bearer pk_live_...`. A chave age com os escopos escolhidos, limitados ao acesso atual de quem a criou. Limite por chave e por minuto; a pesquisa tem teto próprio de 20/min. Valores em centavos; datas civis em AAAA-MM-DD."},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"pk_live_..."}},"schemas":{}},"paths":{"/health":{"get":{"summary":"Status do serviço","tags":["Saúde"],"responses":{"200":{"description":"Default Response"}}}},"/v1/me":{"get":{"summary":"A chave em uso","tags":["Conta"],"description":"Empresa da chave e as permissões que ela tem AGORA (escopos ∩ acesso atual de quem a criou).","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/empresas":{"get":{"summary":"Pesquisar empresas","tags":["Base da Receita"],"description":"Parâmetros (query string; listas separadas por vírgula):\n- `openedFrom` (obrigatório, AAAA-MM-DD) e `openedTo`: período de abertura;\n- `uf`, `cities` (códigos), `cnaes` (7 dígitos), `secondary` (true = CNAE secundária também);\n- `status` (ativa, baixada, inapta, suspensa, nula — padrão ativa), `sizes` (mei, me, epp, demais);\n- `hasPhone`, `hasMobile`, `hasEmail`, `onlyLandline` (true/false);\n- `legalNature`, `district`, `zip`, `ddd`, `capitalMin`/`capitalMax` (centavos), `branch` (matriz|filial);\n- `page` (1–200).","parameters":[{"schema":"object","in":"query","name":"type"},{"schema":{"type":"string"},"in":"query","name":"additionalProperties"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/empresas/{cnpj}":{"get":{"summary":"Ficha de uma empresa","tags":["Base da Receita"],"parameters":[{"schema":{"type":"string","pattern":"^\\d{14}$"},"in":"path","name":"cnpj","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/empresas/{cnpj}/enriquecimento":{"get":{"summary":"Site, e-mail e contratos com o governo","tags":["Base da Receita"],"description":"O que vem de fora da base, à parte da ficha porque é mais lento: o site do domínio do e-mail (fora provedores gratuitos) e os contratos federais da empresa como fornecedora (Portal da Transparência). Cada fonte falha sozinha, com `error`.","parameters":[{"schema":{"type":"string","pattern":"^\\d{14}$"},"in":"path","name":"cnpj","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/atividades":{"get":{"summary":"CNAEs e naturezas jurídicas da base","tags":["Base da Receita"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/municipios":{"get":{"summary":"Municípios de uma UF","tags":["Base da Receita"],"parameters":[{"schema":{"type":"string","enum":["AC","AL","AM","AP","BA","CE","DF","ES","GO","MA","MG","MS","MT","PA","PB","PE","PI","PR","RJ","RN","RO","RR","RS","SC","SE","SP","TO"]},"in":"query","name":"uf","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/pesquisa-ia":{"post":{"summary":"Pesquisa por IA: texto livre vira filtros","tags":["Base da Receita"],"description":"Recebe o pedido em português (\"padarias abertas em Campinas desde setembro, com e-mail\") e devolve os filtros de `GET /v1/empresas` preenchidos: CNAEs reais da base, códigos de município, UF, período, porte, contato. A IA só entende o pedido; os códigos vêm da base. Sem período no texto, usa o último mês completo. Gasta uma sugestão de IA da franquia do plano.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":3,"maxLength":300}},"required":["text"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/leads":{"get":{"summary":"Listar leads","tags":["Leads"],"description":"Filtros: `stage` (NEW, CONTACTED, QUALIFIED, WON, LOST), `owner` (id do responsável ou `none`), `uf`, `q` (nome, cidade ou CNPJ), `page`. 50 por página.","parameters":[{"schema":{"type":"string","enum":["NEW","CONTACTED","QUALIFIED","WON","LOST"]},"in":"query","name":"stage","required":false},{"schema":{"type":"string","maxLength":40},"in":"query","name":"owner","required":false},{"schema":{"type":"string","maxLength":100},"in":"query","name":"q","required":false},{"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"in":"query","name":"uf","required":false},{"schema":{"type":"integer","minimum":1,"maximum":10000,"default":1},"in":"query","name":"page","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Salvar empresas da base como leads","tags":["Leads"],"description":"Até 50 CNPJs por chamada. Os dados vêm da base da Receita, nunca do corpo. Cada CNPJ recusado volta em `skipped` com o motivo: ALREADY_LEAD, OPTED_OUT, NOT_FOUND ou PLAN_LIMIT.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cnpjs":{"type":"array","items":{"type":"string","pattern":"^\\d{14}$"},"minItems":1,"maxItems":50}},"required":["cnpjs"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/leads/{id}":{"get":{"summary":"Um lead, com as atividades","tags":["Leads"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":40},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}},"patch":{"summary":"Alterar etapa, responsável, notas ou motivo de perda","tags":["Leads"],"description":"Trocar o responsável (`ownerId`) exige o escopo `leads.ver_todos`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stage":{"type":"string","enum":["NEW","CONTACTED","QUALIFIED","WON","LOST"]},"ownerId":{"type":"string","minLength":1,"maxLength":40,"nullable":true},"notes":{"type":"string","maxLength":10000,"nullable":true},"lostReason":{"type":"string","maxLength":300,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":40},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Excluir um lead","tags":["Leads"],"description":"Exclusão lógica: o lead continua contando no limite mensal do plano.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":40},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nao-contatar":{"get":{"summary":"Listar CNPJs com pedido de não contato","tags":["Não quero contato"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":10000,"default":1},"in":"query","name":"page","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Registrar pedido de não contato","tags":["Não quero contato"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cnpj":{"type":"string","pattern":"^\\d{14}$"},"reason":{"type":"string","maxLength":300}},"required":["cnpj"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nao-contatar/{cnpj}":{"delete":{"summary":"Desfazer o pedido de não contato","tags":["Não quero contato"],"parameters":[{"schema":{"type":"string","pattern":"^\\d{14}$"},"in":"path","name":"cnpj","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://api.faroprospect.com"}]}