A base da Receita e os seus leads, no seu sistema

Pesquisar escrevendo, sem montar filtro

Quem integra nem sempre sabe CNAE ou código de município. A pesquisa por IA recebe o pedido em português e devolve os filtros prontos. O seu sistema mostra o que foi entendido, a pessoa confirma e a pesquisa roda.

Escopos:prospeccao.ver

1. 1

   Mande o pedido como ele veio

   POST/v1/pesquisa-ia

   Pode ser o tipo de empresa ("padarias em Curitiba") ou o que você vende ("vendo software para clínicas odontológicas em BH"): no segundo caso vêm os ramos de quem compra. Os CNAEs e municípios saem da base; o que não deu para entender volta em notes.

   Requisição

   curl -X POST -H "Authorization: Bearer pk_live_SUA_CHAVE" \
     -H "Content-Type: application/json" \
     -d '{ "text": "vendo software de gestão para clínicas odontológicas em Belo Horizonte e Contagem, só com WhatsApp" }' \
     "https://api.faroprospect.com/v1/pesquisa-ia"

   Resposta (resumida)

   {
     "data": {
       "filters": {
         "openedFrom": "2026-10-01", "openedTo": "2026-10-31",
         "uf": "MG", "cities": [4123, 4371], "cnaes": [8630504, 3250706], "hasMobile": true
       },
       "query": "openedFrom=2026-10-01&openedTo=2026-10-31&uf=MG&cities=4123%2C4371&cnaes=8630504%2C3250706&hasMobile=true",
       "activities": [{ "name": "Clínicas odontológicas", "cnaes": [{ "code": 8630504, "description": "Atividade odontológica" }, …] }],
       "cities": [{ "code": 4123, "name": "BELO HORIZONTE", "uf": "MG" }, { "code": 4371, "name": "CONTAGEM", "uf": "MG" }],
       "notes": ["Sem período no texto: usei o último mês completo, de 01/10/2026 a 31/10/2026."]
     }
   }

2. 2

   Pesquise com a query devolvida

   GET/v1/empresas

   query já está no formato da pesquisa: é só colar depois do ?. Se a pessoa ajustou algo na tela, monte a query a partir de filters.

   Requisição

   curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
     "https://api.faroprospect.com/v1/empresas?openedFrom=2026-10-01&openedTo=2026-10-31&uf=MG&cities=4123%2C4371&cnaes=8630504%2C3250706&hasMobile=true"

• Cada chamada gasta uma sugestão de IA da franquia do plano. Para a mesma pesquisa repetida, guarde query e chame só GET /v1/empresas.

Encontrar empresas recém-abertas e salvar como leads

O fluxo básico de prospecção: escolher onde e o quê, pesquisar na base da Receita, conferir a ficha, salvar as empresas que interessam e marcar a primeira abordagem. O exemplo procura padarias abertas em Curitiba desde setembro, com e-mail.

Escopos:prospeccao.verleads.criarleads.editar

1. 1

   Ache o código do município

   GET/v1/municipios

   A pesquisa filtra município pelo código da Receita, não pelo nome. Guarde a lista em cache: ela só muda com a base.

   Requisição

   curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
     "https://api.faroprospect.com/v1/municipios?uf=PR"

   Resposta (resumida)

   {
     "data": [
       { "code": 7535, "description": "CURITIBA" },
       { "code": 7667, "description": "LONDRINA" }
     ]
   }

2. 2

   Escolha as atividades (CNAE)

   GET/v1/atividades

   A lista completa de CNAEs e naturezas jurídicas da base. Para padaria, servem a de produção própria e a de revenda.

   Requisição

   curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
     "https://api.faroprospect.com/v1/atividades"

   Resposta (resumida)

   {
     "data": {
       "cnaes": [
         { "code": 1091102, "description": "Fabricação de produtos de padaria e confeitaria com predominância de produção própria" },
         { "code": 4721102, "description": "Padaria e confeitaria com predominância de revenda" }
       ],
       "legalNatures": [ … ]
     }
   }

3. 3

   Pesquise

   GET/v1/empresas

   Só openedFrom é obrigatório; UF, município e atividade deixam a consulta rápida. Vêm 50 por página: siga com page=2, page=3 enquanto page × 50 for menor que total. Quem pediu para não ser contatado já vem fora, e lead diz se a empresa já é sua.

   Requisição

   curl -G -H "Authorization: Bearer pk_live_SUA_CHAVE" "https://api.faroprospect.com/v1/empresas" \
     --data-urlencode "openedFrom=2026-09-01" \
     --data-urlencode "uf=PR" \
     --data-urlencode "cities=7535" \
     --data-urlencode "cnaes=1091102,4721102" \
     --data-urlencode "hasEmail=true"

   Resposta (resumida)

   {
     "data": [
       { "cnpj": "12345678000199", "companyName": "PADARIA CENTRAL LTDA", "city": "Curitiba",
         "phones": ["4133330000", "41999990000"], "email": "contato@padariacentral.com.br", "lead": null },
       …
     ],
     "page": 1, "pageSize": 50, "total": 183, "totalCapped": false,
     "base": { "folder": "2026-10-11" }
   }

4. 4

   Abra a ficha antes de abordar

   GET/v1/empresas/{cnpj}

   A ficha diz com quem falar (partners, com o provável decisor marcado), o tamanho da operação (branches, group) e o que pede cuidado (publicRecords: sanções, dívida ativa e contratos públicos do PNCP). signals resume tudo em frases curtas. Para o site e os contratos federais do Portal da Transparência, chame também /enriquecimento.

   Requisição

   curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
     "https://api.faroprospect.com/v1/empresas/12345678000199"

   Resposta (resumida)

   {
     "data": {
       "cnpj": "12345678000199", "companyName": "PADARIA CENTRAL LTDA", …,
       "partners": { "available": true, "partners": [
         { "name": "ANA SOUZA", "kind": "PF", "qualification": "Sócio-Administrador", "sinceYear": 2026, "likelyDecisionMaker": true }
       ] },
       "signals": [{ "kind": "new", "tone": "positive", "label": "Aberta há 51 dias" }]
     }
   }

5. 5

   Salve as que interessam

   POST/v1/leads

   Mande só os CNPJs, até 50 por chamada: os dados são relidos da base no servidor. O que não entrou volta em skipped com o motivo, e nada falha por inteiro.

   Requisição

   curl -X POST -H "Authorization: Bearer pk_live_SUA_CHAVE" \
     -H "Content-Type: application/json" \
     -d '{ "cnpjs": ["12345678000199", "98765432000110"] }' \
     "https://api.faroprospect.com/v1/leads"

   Resposta (resumida)

   {
     "data": {
       "created": [{ "cnpj": "12345678000199", "leadId": "cm3x9k2v10001abcd" }],
       "skipped": [{ "cnpj": "98765432000110", "reason": "ALREADY_LEAD", "message": "Já está nos seus leads." }],
       "limitMessage": null
     }
   }

6. 6

   Registre a primeira abordagem

   PATCH/v1/leads/{id}

   Depois do contato, avance a etapa. A troca fica no histórico do lead, visível no painel e em GET /v1/leads/{id}.

   Requisição

   curl -X PATCH -H "Authorization: Bearer pk_live_SUA_CHAVE" \
     -H "Content-Type: application/json" \
     -d '{ "stage": "CONTACTED", "notes": "Falei com a Ana, retorno dia 10." }' \
     "https://api.faroprospect.com/v1/leads/cm3x9k2v10001abcd"

   Resposta (resumida)

   {
     "data": { "id": "cm3x9k2v10001abcd", "stage": "CONTACTED", "notes": "Falei com a Ana, retorno dia 10.", … }
   }

Puxar as empresas novas a cada atualização da base

A Receita publica a base uma vez por mês. Em vez de pesquisar todo dia, a sua rotina olha a versão em base.folder e, quando ela muda, traz as empresas abertas no período e salva em lotes de 50.

Escopos:prospeccao.verleads.criar

1. 1

   Rode uma vez por dia e compare a versão da base

   GET/v1/empresas

   Se base.folder é a mesma da última execução, não há empresa nova: encerre. Se mudou, percorra as páginas, pule quem já é lead e salve o resto. Respeite o teto de 20 pesquisas por minuto e o Retry-After do 429.

   Node.js 18+

   const API = "https://api.faroprospect.com";
   const headers = { Authorization: `Bearer ${process.env.FARO_API_KEY}`, "Content-Type": "application/json" };
   
   async function call(path, init = {}) {
     for (;;) {
       const res = await fetch(API + path, { ...init, headers });
       if (res.status !== 429) return res.json();
       await new Promise((r) => setTimeout(r, Number(res.headers.get("Retry-After") ?? 5) * 1000));
     }
   }
   
   export async function syncNovasEmpresas(ultimaBase, openedFrom) {
     const filtros = new URLSearchParams({ openedFrom, uf: "PR", cnaes: "1091102,4721102", hasEmail: "true" });
     const novos = [];
     let base = ultimaBase;
     for (let page = 1; ; page++) {
       filtros.set("page", String(page));
       const r = await call(`/v1/empresas?${filtros}`);
       base = r.base?.folder ?? base;
       if (base === ultimaBase) return { base, salvos: 0 };
       novos.push(...r.data.filter((e) => e.lead === null).map((e) => e.cnpj));
       if (page * r.pageSize >= r.total || page === 200) break;
     }
     let salvos = 0;
     for (let i = 0; i < novos.length; i += 50) {
       const r = await call("/v1/leads", { method: "POST", body: JSON.stringify({ cnpjs: novos.slice(i, i + 50) }) });
       salvos += r.data.created.length;
       if (r.data.limitMessage) break; // teto mensal do plano: o resto volta como PLAN_LIMIT
     }
     return { base, salvos };
   }

• Guarde base e a data usada em openedFrom entre execuções. Na próxima base, comece de onde a anterior parou.
• limitMessage preenchido quer dizer que o teto mensal de leads do plano acabou: os CNPJs restantes voltam em skipped como PLAN_LIMIT e podem entrar no mês seguinte.

Manter o funil em dia com o seu CRM

Quando o CRM é a fonte da verdade do time comercial, a integração lê os leads do Faro e devolve cada mudança de etapa. Assim o painel, os relatórios e o histórico continuam certos.

Escopos:leads.verleads.editar

1. 1

   Leia os leads por etapa

   GET/v1/leads

   Filtre por stage (e uf, owner ou q) e pagine de 50 em 50. Sem o escopo leads.ver_todos, a chave só vê os leads de quem a criou.

   Requisição

   curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
     "https://api.faroprospect.com/v1/leads?stage=NEW&page=1"

   Resposta (resumida)

   {
     "data": [{ "id": "cm3x9k2v10001abcd", "cnpj": "12345678000199", "stage": "NEW", "owner": { "id": "cm3membro0001", "name": "Ana Souza" }, … }],
     "page": 1, "pageSize": 50, "total": 37
   }

2. 2

   Devolva o resultado do CRM

   PATCH/v1/leads/{id}

   Negócio fechado vira WON; perdido vira LOST com o motivo em lostReason, que aparece no histórico. Mande só o que mudou.

   Requisição

   curl -X PATCH -H "Authorization: Bearer pk_live_SUA_CHAVE" \
     -H "Content-Type: application/json" \
     -d '{ "stage": "LOST", "lostReason": "Já tem fornecedor com contrato até 2027" }' \
     "https://api.faroprospect.com/v1/leads/cm3x9k2v10001abcd"

3. 3

   Consulte o histórico quando precisar

   GET/v1/leads/{id}

   O lead vem com as últimas 100 atividades: criação, trocas de etapa e de responsável, inclusive as feitas pela API.

   Requisição

   curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
     "https://api.faroprospect.com/v1/leads/cm3x9k2v10001abcd"

Registrar o descadastro que chegou pelo seu canal

Se alguém responde ao seu e-mail, liga ou escreve pedindo para não ser procurado, registre no mesmo dia. A empresa some da pesquisa, o lead fica marcado e ninguém da equipe volta a abordá-la por engano.

Escopos:prospeccao.nao_contatarprospeccao.ver

1. 1

   Registre o pedido

   POST/v1/nao-contatar

   Diga em reason como e quando o pedido chegou: é a sua prova de que atendeu. A chamada é idempotente.

   Requisição

   curl -X POST -H "Authorization: Bearer pk_live_SUA_CHAVE" \
     -H "Content-Type: application/json" \
     -d '{ "cnpj": "12345678000199", "reason": "Respondeu ao e-mail pedindo para sair em 03/11" }' \
     "https://api.faroprospect.com/v1/nao-contatar"

   Resposta (resumida)

   {
     "data": { "cnpj": "12345678000199", "optedOut": true, "changed": true }
   }

2. 2

   Concilie com a sua lista de descadastro

   GET/v1/nao-contatar

   A lista da sua empresa, 100 por página, do pedido mais recente para o mais antigo. Daqui em diante, POST /v1/leads devolve esse CNPJ em skipped como OPTED_OUT.

   Requisição

   curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
     "https://api.faroprospect.com/v1/nao-contatar?page=1"

A chave em uso

Diz qual chave está em uso, de que empresa, e quais permissões ela tem AGORA: os escopos escolhidos ao criar, cruzados com o acesso atual de quem a criou. Use para conferir a configuração antes de integrar.

curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  "https://api.faroprospect.com/v1/me"

{
  "data": {
    "key": { "id": "cm3chave0001", "name": "CRM" },
    "company": { "id": "cm3empresa0001", "name": "Minha Empresa LTDA" },
    "scopes": ["prospeccao.ver", "leads.ver", "leads.criar"]
  }
}

Pesquisar empresas

A mesma pesquisa da tela, sobre a base pública de CNPJs da Receita Federal. Só o início do período de abertura é obrigatório; os demais filtros refinam. Empresas com pedido de não contato (da sua empresa ou público) não aparecem. Cada linha diz se o CNPJ já é lead da sua empresa.

curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  "https://api.faroprospect.com/v1/empresas?openedFrom=2026-09-01&uf=PR&cnaes=1091102&hasEmail=true&page=1"

{
  "data": [
    {
      "cnpj": "12345678000199",
      "companyName": "PADARIA CENTRAL LTDA",
      "tradeName": "Padaria Central",
      "status": 2,
      "openedOn": "2026-09-14",
      "mainCnae": 1091102,
      "mainCnaeDescription": "Fabricação de produtos de padaria e confeitaria com predominância de produção própria",
      "isHeadquarters": true,
      "size": 1,
      "mei": false,
      "simples": true,
      "shareCapitalCents": 5000000,
      "legalNature": 2062,
      "district": "CENTRO",
      "city": "Curitiba",
      "uf": "PR",
      "zipCode": "80010000",
      "address": "RUA XV DE NOVEMBRO, 100",
      "phones": ["4133330000", "41999990000"],
      "hasMobile": true,
      "email": "contato@padariacentral.com.br",
      "lead": null
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 183,
  "totalCapped": false,
  "base": { "folder": "2026-10-11" }
}

• total conta até 10.000; acima disso vem 10000 com totalCapped: true.
• status e size seguem os códigos da Receita: situação 1 nula, 2 ativa, 3 suspensa, 4 inapta, 8 baixada; porte 1 ME, 3 EPP, 5 demais (0 não informado). mei é um campo à parte.
• base.folder é a versão da base da Receita em uso (data da publicação).
• Pesquisa sem UF, município ou atividade num período longo pode estourar o tempo e voltar 422 query_timeout: encurte o período ou acrescente um filtro.

Pesquisa por IA: texto livre vira filtros

Escreva a pesquisa como falaria com alguém do time e receba os filtros de GET /v1/empresas já preenchidos: CNAEs, UF, códigos de município, período, porte, contato, capital. A IA só entende o pedido. Os códigos vêm da base: cada atividade é casada com os CNAEs reais por similaridade, e cada cidade com a lista de municípios da Receita. Nada é inventado. A rota não pesquisa: confira `filters`, ajuste se quiser e chame GET /v1/empresas com `query`.

curl -X POST -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "text": "padarias abertas em Curitiba desde setembro, com e-mail" }' \
  "https://api.faroprospect.com/v1/pesquisa-ia"

{
  "data": {
    "filters": {
      "openedFrom": "2026-09-01",
      "uf": "PR",
      "cities": [7535],
      "cnaes": [1091102, 4721102],
      "hasEmail": true
    },
    "query": "openedFrom=2026-09-01&uf=PR&cities=7535&cnaes=1091102%2C4721102&hasEmail=true",
    "activities": [
      {
        "name": "Padarias",
        "reason": "Empresas do ramo de padaria e confeitaria",
        "cnaes": [
          { "code": 1091102, "description": "Fabricação de produtos de padaria e confeitaria com predominância de produção própria" },
          { "code": 4721102, "description": "Padaria e confeitaria com predominância de revenda" }
        ]
      }
    ],
    "cities": [{ "code": 7535, "name": "CURITIBA", "uf": "PR" }],
    "notes": []
  }
}

• Sem período no texto, vale o mesmo padrão do painel: o último mês completo. A suposição vem em notes.
• notes também diz o que ficou de fora: cidade que não está na base, cidade sem estado, atividade sem CNAE correspondente, filtro inválido. Mostre a quem pediu.
• Cada chamada gasta uma sugestão de IA da franquia mensal do plano, a mesma da sugestão de atividades do painel. Franquia esgotada responde 403 ai_quota.
• Texto que não descreve uma pesquisa ("olá") responde 422 ai_failed.

Ficha de uma empresa

Tudo o que a ficha do painel mostra sobre um CNPJ, lido ao vivo na base: os campos de uma linha da pesquisa, os detalhes completos (situação e motivo, CNAEs secundárias, Simples e MEI com datas, endereço por partes), o quadro societário, filiais, grupo econômico, sanções (CEIS e CNEP), dívida ativa da União (PGFN) e os sinais tirados disso. Empresa com pedido de não contato responde 404, mesmo pedida pelo CNPJ.

curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  "https://api.faroprospect.com/v1/empresas/12345678000199"

{
  "data": {
    "cnpj": "12345678000199",
    "companyName": "PADARIA CENTRAL LTDA",
    "tradeName": "Padaria Central",
    "…": "os demais campos de uma linha da pesquisa",
    "lead": null,
    "linkedinSearchUrl": "https://www.linkedin.com/search/results/companies/?keywords=Padaria%20Central",
    "details": {
      "legalNature": "Sociedade Empresária Limitada",
      "size": "Microempresa (ME)",
      "status": "Ativa",
      "statusDate": "2026-09-14",
      "statusReason": null,
      "mainCnae": { "code": 1091102, "description": "Fabricação de produtos de padaria e confeitaria com predominância de produção própria" },
      "secondaryCnaes": [{ "code": 4721102, "description": "Padaria e confeitaria com predominância de revenda" }],
      "address": { "street": "RUA XV DE NOVEMBRO", "number": "100", "complement": null, "district": "CENTRO", "zipCode": "80010000", "city": "CURITIBA", "uf": "PR" },
      "simples": { "option": true, "since": "2026-09-14", "until": null },
      "mei": { "option": false, "since": null, "until": null },
      "…": "identificação, capital, situação especial, telefones, fax, e-mail"
    },
    "partners": {
      "available": true,
      "partners": [
        { "name": "ANA SOUZA", "kind": "PF", "qualification": "Sócio-Administrador", "sinceYear": 2026, "likelyDecisionMaker": true,
          "linkedinSearchUrl": "https://www.linkedin.com/search/results/people/?keywords=Ana%20Souza%20Padaria%20Central" },
        { "name": "CARLOS LIMA", "kind": "PF", "qualification": "Sócio", "sinceYear": 2026, "likelyDecisionMaker": false, "linkedinSearchUrl": null }
      ]
    },
    "branches": { "total": 3, "active": 3, "byUf": [{ "uf": "PR", "total": 2 }, { "uf": "SC", "total": 1 }] },
    "group": {
      "owners": [],
      "holdings": [{ "cnpj": "98765432000110", "name": "CENTRAL ALIMENTOS LTDA", "qualification": "Sócio" }]
    },
    "publicRecords": {
      "sanctions": { "available": true, "asOf": "2026-11-03", "items": [] },
      "debt": { "available": true, "asOf": "2026_trimestre_03", "value": null },
      "procurement": {
        "available": true,
        "asOf": "2026-11-03",
        "value": {
          "total": 4, "active": 2, "totalValueCents": 9600000, "activeValueCents": 5200000,
          "bySphere": { "federal": 0, "state": 1, "municipal": 3 },
          "ufs": [{ "uf": "PR", "count": 4 }],
          "organs": [{ "name": "MUNICIPIO DE CURITIBA", "count": 3 }],
          "lastSignedOn": "2026-10-15",
          "latest": [
            { "organ": "MUNICIPIO DE CURITIBA", "sphere": "municipal", "uf": "PR", "city": "Curitiba", "category": "Compras",
              "object": "Fornecimento de pães para a merenda escolar", "signedOn": "2026-10-15", "endsOn": "2027-10-14",
              "valueCents": 2600000, "active": true, "url": "https://pncp.gov.br/app/contratos/76417005000186/2026/112" }
          ]
        }
      }
    },
    "signals": [
      { "kind": "new", "tone": "positive", "label": "Aberta há 51 dias" },
      { "kind": "gov_supplier", "tone": "positive", "label": "Fornece ao governo (2 contratos vigentes)" },
      { "kind": "branches", "tone": "positive", "label": "3 estabelecimentos em 2 UFs" },
      { "kind": "group", "tone": "neutral", "label": "Sócia de outras empresas" }
    ]
  }
}

• Os campos de sempre continuam no topo, iguais aos da pesquisa; a ficha completa vem nos campos novos. Integração antiga não quebra.
• Quadro societário com o recorte da LGPD: nome, tipo (PF, PJ ou EXTERIOR), qualificação, ano de entrada e likelyDecisionMaker (administração ou titularidade, nunca empresa sócia). Nunca CPF, representante legal ou faixa etária. Só nesta rota, uma empresa por vez: não vem na pesquisa em lista nem no lead.
• LinkedIn, link pronto: linkedinSearchUrl no topo abre a busca da EMPRESA, e o do sócio (só no provável decisor pessoa física) abre a busca de pessoas por nome e sobrenome mais o nome da empresa. É só um endereço de busca, para abrir no navegador de quem vai prospectar: o Faro não consulta o LinkedIn, não confirma o perfil e não guarda nada de lá. O link do decisor existe só nesta rota, como os sócios; no lead e no CSV vai só o da empresa.
• partners.available: false quando a base de sócios não está carregada; sanctions.available e debt.available idem para os dados abertos do governo. asOf é a data da carga.
• debt.value, quando há dívida: totalCents, registrations (inscrições), judicial, bySystem e oldestOn. Cada sanção traz source (CEIS ou CNEP), category, órgão, datas e active.
• procurement: contratos da empresa como fornecedora no PNCP (Portal Nacional de Contratações Públicas), de prefeituras, estados e União, dos últimos 5 anos. asOf é o último dia de publicações já carregado (atualiza todo dia); value: null quando não há contrato. latest traz os 5 mais recentes, com o link de cada um no PNCP.
• signals[].kind: new (recém-aberta), grew_mei (deixou de ser MEI), left_simples, status (situação diferente de ativa), branches, group, sanction, debt, gov_supplier (contrato público vigente ou assinado no último ano). tone diz se é bom sinal, neutro ou alerta.

Site, e-mail e contratos com o governo

O que vem de fora da base, separado da ficha porque é mais lento: o site do domínio do e-mail (quando não é provedor gratuito como Gmail) e os contratos da empresa como fornecedora do governo federal, pelo Portal da Transparência. Cada fonte falha sozinha: uma fora do ar volta com `error` e a outra responde normalmente.

curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  "https://api.faroprospect.com/v1/empresas/12345678000199/enriquecimento"

{
  "data": {
    "domain": {
      "info": {
        "domain": "padariacentral.com.br",
        "mailProvider": "Google Workspace",
        "registration": { "registeredOn": "2019-03-12", "expiresOn": "2027-03-12", "registrant": "company" },
        "website": {
          "url": "https://padariacentral.com.br/",
          "title": "Padaria Central | Pães artesanais em Curitiba",
          "description": "Pães, bolos e cafés desde 2026.",
          "social": [{ "network": "Instagram", "url": "https://instagram.com/padariacentral" }],
          "whatsapp": ["5541999990000"],
          "phones": ["4133334444"],
          "emails": ["contato@padariacentral.com.br"],
          "careers": { "url": "https://padariacentral.gupy.io/", "platform": "Gupy" },
          "tech": [{ "name": "WordPress", "category": "site" }],
          "mentionsCnpj": true,
          "pages": [
            { "kind": "contact", "url": "https://padariacentral.com.br/contato" },
            { "kind": "about", "url": "https://padariacentral.com.br/quem-somos" },
            { "kind": "services", "url": "https://padariacentral.com.br/produtos" }
          ],
          "about": "Padaria artesanal com fornos a lenha, aberta em 2026 no centro de Curitiba.",
          "offerings": ["Pães de fermentação natural", "Bolos sob encomenda", "Café da manhã para empresas"]
        },
        "websiteNote": null
      },
      "error": null,
      "reason": null
    },
    "contracts": {
      "summary": {
        "configured": true,
        "total": 2,
        "truncated": false,
        "totalValueCents": 4800000,
        "active": 1,
        "organs": [{ "name": "Universidade Federal do Paraná", "count": 2 }],
        "latest": [
          { "number": "12/2026", "object": "Fornecimento de pães e salgados", "organ": "Universidade Federal do Paraná",
            "signedOn": "2026-10-01", "endsOn": "2027-09-30", "valueCents": 2400000, "active": true }
        ]
      },
      "error": null
    }
  }
}

• domain.reason: free_mail (e-mail de provedor gratuito, sem site para ler) ou no_email. websiteNote explica quando o site não pôde ser lido (não respondeu, bloqueado pelo robots.txt).
• registration vem do registro do domínio (RDAP: Registro.br no .br, e o registro oficial de cada extensão nas outras): registeredOn, expiresOn e registrant, que diz só se o domínio está no CNPJ da própria empresa (company, mesma raiz de CNPJ), no de outra empresa (another_company) ou no CPF de uma pessoa (person). Documento e nome do titular nunca vêm. null quando o registro não respondeu.
• Do site saem só os canais que a empresa publica como dela: redes, whatsapp e phones (links de telefone, DDD + número), emails de setor no domínio dela (contato@, comercial@; e-mail com nome de pessoa nunca) e careers, a página de vagas ou a plataforma de recrutamento (sinal de que está contratando).
• Além da página inicial, o Faro lê as páginas de contato, quem somos e serviços/produtos que o próprio site linka (uma de cada, respeitando o robots.txt) e soma os canais delas. pages lista as que foram lidas (kind: contact, about ou services); about é um resumo do quem somos (até ~700 caracteres, sem e-mail, telefone nem link) e offerings, os títulos da página de serviços/produtos. null e lista vazia quando o site não tem essas páginas.
• Contratos com prefeituras e estados (PNCP) vêm na ficha, em publicRecords.procurement; aqui fica o histórico federal do Portal da Transparência.
• O site é lido respeitando o robots.txt, só a página inicial. Resultados ficam em cache por 30 dias (site) e 7 dias (contratos).
• Limite próprio: 30 consultas por minuto, por chave.

CNAEs e naturezas jurídicas da base

Tabelas de apoio da base: todos os códigos CNAE e naturezas jurídicas com descrição. Mudam só quando a Receita publica uma base nova; guarde em cache.

curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  "https://api.faroprospect.com/v1/atividades"

{
  "data": {
    "cnaes": [
      { "code": 111301, "description": "Cultivo de arroz" },
      { "code": 1091102, "description": "Fabricação de produtos de padaria e confeitaria com predominância de produção própria" }
    ],
    "legalNatures": [
      { "code": 2062, "description": "Sociedade Empresária Limitada" },
      { "code": 2135, "description": "Empresário (Individual)" }
    ]
  }
}

Municípios de uma UF

Municípios de uma UF que têm estabelecimento na base, com o código usado em `cities` da pesquisa.

curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  "https://api.faroprospect.com/v1/municipios?uf=PR"

{
  "data": [
    { "code": 7535, "description": "CURITIBA" },
    { "code": 7691, "description": "LONDRINA" }
  ]
}

Listar leads

Leads da sua empresa, do mais novo para o mais antigo, 50 por página. Sem o escopo `leads.ver_todos`, vêm só os leads de que quem criou a chave é responsável. Cada lead traz `linkedinSearchUrl`, a busca da empresa no LinkedIn pronta para abrir (o link do decisor fica na ficha, `GET /v1/empresas/{cnpj}`).

curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  "https://api.faroprospect.com/v1/leads?stage=NEW&uf=PR&page=1"

{
  "data": [
    {
      "id": "cm3x9k2v10001abcd",
      "cnpj": "12345678000199",
      "stage": "NEW",
      "tradeName": "Padaria Central",
      "legalName": "PADARIA CENTRAL LTDA",
      "cnaeCode": 1091102,
      "cnaeDescription": "Fabricação de produtos de padaria e confeitaria…",
      "openedOn": "2026-09-14",
      "city": "Curitiba",
      "uf": "PR",
      "address": "RUA XV DE NOVEMBRO, 100 - CENTRO - 80010000",
      "mobiles": ["41999990000"],
      "landlines": ["4133330000"],
      "email": "contato@padariacentral.com.br",
      "size": "ME",
      "capitalCents": 5000000,
      "notes": null,
      "lostReason": null,
      "rfFolder": "2026-10-11",
      "refreshedAt": null,
      "createdAt": "2026-11-04T13:02:11.512Z",
      "updatedAt": "2026-11-04T13:02:11.512Z",
      "owner": { "id": "cm3membro0001", "name": "Ana Souza" },
      "linkedinSearchUrl": "https://www.linkedin.com/search/results/companies/?keywords=Padaria%20Central"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1
}

• Leads excluídos não aparecem (exclusão lógica).

Salvar empresas da base como leads

Salva empresas da base como leads. Mande só os CNPJs: os dados da empresa são relidos da base da Receita no servidor, nunca do corpo da requisição. Quem criou a chave fica como responsável. Cada CNPJ que não virou lead volta em `skipped` com o motivo.

curl -X POST -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "cnpjs": ["12345678000199", "98765432000188"] }' \
  "https://api.faroprospect.com/v1/leads"

{
  "data": {
    "created": [
      { "cnpj": "12345678000199", "leadId": "cm3x9k2v10001abcd" }
    ],
    "skipped": [
      { "cnpj": "98765432000188", "reason": "ALREADY_LEAD", "message": "Já está nos seus leads." }
    ],
    "limitMessage": null
  }
}

• Motivos de skipped: ALREADY_LEAD (já é lead), OPTED_OUT (pediu para não ser contatada), NOT_FOUND (não está na base), PLAN_LIMIT (fora do teto mensal de leads do plano; limitMessage explica).
• O teto mensal é o do plano da empresa e vale para o painel e a API juntos. Excluir um lead não devolve a vaga do mês.

Um lead, com as atividades

Um lead com as 100 atividades mais recentes (notas, mudanças de etapa, e-mails enviados, conversas de WhatsApp abertas, ligações, atualizações de dados).

curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  "https://api.faroprospect.com/v1/leads/cm3x9k2v10001abcd"

{
  "data": {
      "id": "cm3x9k2v10001abcd",
      "cnpj": "12345678000199",
      "stage": "NEW",
      "tradeName": "Padaria Central",
      "legalName": "PADARIA CENTRAL LTDA",
      "cnaeCode": 1091102,
      "cnaeDescription": "Fabricação de produtos de padaria e confeitaria…",
      "openedOn": "2026-09-14",
      "city": "Curitiba",
      "uf": "PR",
      "address": "RUA XV DE NOVEMBRO, 100 - CENTRO - 80010000",
      "mobiles": ["41999990000"],
      "landlines": ["4133330000"],
      "email": "contato@padariacentral.com.br",
      "size": "ME",
      "capitalCents": 5000000,
      "notes": null,
      "lostReason": null,
      "rfFolder": "2026-10-11",
      "refreshedAt": null,
      "createdAt": "2026-11-04T13:02:11.512Z",
      "updatedAt": "2026-11-04T13:02:11.512Z",
      "owner": { "id": "cm3membro0001", "name": "Ana Souza" },
      "linkedinSearchUrl": "https://www.linkedin.com/search/results/companies/?keywords=Padaria%20Central",
    "activities": [
      {
        "id": "cm3ativ0002",
        "kind": "STAGE_CHANGE",
        "text": "Novo → Contatado",
        "meta": { "from": "NEW", "to": "CONTACTED" },
        "createdAt": "2026-11-04T15:20:03.000Z"
      },
      {
        "id": "cm3ativ0001",
        "kind": "NOTE",
        "text": "Ligar na quinta de manhã.",
        "meta": null,
        "createdAt": "2026-11-04T13:10:44.000Z"
      }
    ]
  }
}

• kind: NOTE, STAGE_CHANGE, EMAIL_SENT, WHATSAPP_OPENED, CALL, DATA_REFRESH.

Alterar etapa, responsável, notas ou motivo de perda

Altera a etapa, o responsável, as notas ou o motivo da perda. Mande só os campos que mudam; `null` limpa. Mudar a etapa grava uma atividade no histórico. Trocar o responsável exige o escopo `leads.ver_todos`.

curl -X PATCH -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "CONTACTED", "notes": "Falei com a Ana, retorno dia 10." }' \
  "https://api.faroprospect.com/v1/leads/cm3x9k2v10001abcd"

{
  "data": {
    "id": "cm3x9k2v10001abcd",
    "cnpj": "12345678000199",
    "stage": "CONTACTED",
    "tradeName": "Padaria Central",
    "legalName": "PADARIA CENTRAL LTDA",
    "cnaeCode": 1091102,
    "cnaeDescription": "Fabricação de produtos de padaria e confeitaria…",
    "openedOn": "2026-09-14",
    "city": "Curitiba",
    "uf": "PR",
    "address": "RUA XV DE NOVEMBRO, 100 - CENTRO - 80010000",
    "mobiles": ["41999990000"],
    "landlines": ["4133330000"],
    "email": "contato@padariacentral.com.br",
    "size": "ME",
    "capitalCents": 5000000,
    "notes": "Falei com a Ana, retorno dia 10.",
    "lostReason": null,
    "rfFolder": "2026-10-11",
    "refreshedAt": null,
    "createdAt": "2026-11-04T13:02:11.512Z",
    "updatedAt": "2026-11-04T13:02:11.512Z",
    "owner": { "id": "cm3membro0001", "name": "Ana Souza" },
    "linkedinSearchUrl": "https://www.linkedin.com/search/results/companies/?keywords=Padaria%20Central"
  }
}

• Corpo vazio volta 400 validation_error (“Nada a alterar.”, em fields.body).

Excluir um lead

Exclusão lógica: o lead sai das listas, mas continua contando no limite mensal do plano.

curl -X DELETE -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  "https://api.faroprospect.com/v1/leads/cm3x9k2v10001abcd"

{
  "data": { "id": "cm3x9k2v10001abcd", "deleted": true }
}

Listar CNPJs com pedido de não contato

CNPJs que a sua empresa marcou como “não quero contato”, 100 por página, do mais recente para o mais antigo.

curl -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  "https://api.faroprospect.com/v1/nao-contatar?page=1"

{
  "data": [
    { "cnpj": "12345678000199", "reason": "Pediu por e-mail em 03/11", "createdAt": "2026-11-03T18:40:12.000Z" }
  ],
  "page": 1,
  "pageSize": 100,
  "total": 1
}

• A lista pública (pedidos feitos pela própria empresa prospectada, válidos para toda a plataforma) não é exposta: ela só age, sumindo da pesquisa e recusando e-mail.

Registrar pedido de não contato

Registra que a empresa pediu para não ser contatada. Ela some da pesquisa e da ficha, o e-mail para ela é recusado e o lead que já exista fica marcado. Vale para a sua empresa; sobrevive à exclusão do lead. Auditado.

curl -X POST -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "cnpj": "12345678000199", "reason": "Pediu por e-mail em 03/11" }' \
  "https://api.faroprospect.com/v1/nao-contatar"

{
  "data": { "cnpj": "12345678000199", "optedOut": true, "changed": true }
}

• changed: false significa que o CNPJ já estava na lista (a chamada é idempotente).

Desfazer o pedido de não contato

Desfaz o pedido registrado pela sua empresa. Não mexe no pedido PÚBLICO que a própria empresa prospectada fez na página de não contato. Auditado.

curl -X DELETE -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  "https://api.faroprospect.com/v1/nao-contatar/12345678000199"

{
  "data": { "cnpj": "12345678000199", "optedOut": false, "changed": true }
}