Uma empresa nova, uma razão social nova, um aumento de capital ou uma sede em outro endereço costumam marcar o momento em que a empresa passa a comprar. A API acompanha as contas do seu CRM, entrega a alteração do CNPJ da Receita Federal e lista as empresas que entraram no cadastro. Sempre no nível da empresa, sem sócios e sem contatos.
Para o Brasil, cada entrada no cadastro e cada alteração de razão social, natureza jurídica, sede, capital social ou situação cadastral recebe um event_type:
| Alteração | event_type | Por que importa para vendas |
|---|---|---|
| Empresa nova no cadastro | new_incorporation | Empresa nova precisa de banco, contador, seguro, software e espaço |
| Razão social nova | name_change | Uma troca de marca reabre contratos, notas fiscais e sistemas |
| Aumento ou redução do capital social | capital_change | Capital novo é dinheiro prestes a ser gasto; uma redução é aviso para quem vende a prazo |
| Natureza jurídica nova | legal_form_change | Uma transformação societária muda contratos e necessidades |
| Sede em outro endereço | address_change | Endereço novo: obra, serviços, fornecedores locais |
| Situação inapta ou suspensa | status_change | Empresa irregular na Receita: confira antes de vender a prazo |
| Empresa baixada | dissolution | Pare a venda e limpe o CRM |
| Recuperação judicial, falência, liquidação, intervenção | insolvency, liquidation | Proteja a cobrança e revise limites |
| Empresa que volta a ficar ativa | reactivation | Uma empresa regularizada pode retomar as compras |
previous_value e new_value trazem o antes e o depois: o capital em reais no capital_change (compare os dois para separar aumento de redução), o código da natureza jurídica no legal_form_change (2062 é a sociedade empresária limitada) e o endereço no address_change. Confira os dois valores antes de abrir uma tarefa: uma correção de grafia, como "AVENIDA 15 DE NOVEMBRO" que vira "AVENIDA XV DE NOVEMBRO", também gera o evento.
A Receita publica um arquivo completo do CNPJ por mês, e a leitura é mensal: uma alteração aparece com a carga mensal, e o evento recebe a data da carga que a viu pela primeira vez (event_date), não a data do ato na Receita. O histórico começa na primeira carga, em outubro de 2026.
Encontre o registro de cada conta uma vez, ative o acompanhamento com POST /monitor e guarde o id do CRM como label: ele volta em cada alerta. O acompanhamento não consome créditos e vale só para o que acontece depois de ativado; o passado de uma empresa se lê com GET /company-events/search?country=BR&company_number=33.000.167/0001-01 (2 créditos).
import requests
BASE = 'https://api.prometiam.com/functions/v1/risk-api'
H = {'Authorization': 'Bearer rk_live_...'}
# Suas contas-alvo, como o CRM as guarda: CNPJ e id no CRM
contas = [('33.000.167/0001-01', 'crm-1001'), ('47.960.950/0001-21', 'crm-1002')]
for cnpj, crm_id in contas:
r = requests.get(f'{BASE}/companies/search', headers=H,
params={'country': 'BR', 'company_number': cnpj})
r.raise_for_status()
achadas = r.json()['data']
if not achadas:
continue
m = requests.post(f'{BASE}/monitor', headers=H, json={
'company_id': achadas[0]['id'],
'country': 'BR',
'label': crm_id, # volta em cada alerta
'events': ['corporate_event', 'status_change', 'dissolution'],
'webhook_url': 'https://example.com/hooks/prometiam',
})
m.raise_for_status()
segredo = m.json()['data']['webhook_secret'] # aparece uma única vez: guarde
Cada alerta chega assinado. O cabeçalho X-Prometiam-Signature traz sha256= e o HMAC-SHA256 do corpo, calculado com o webhook_secret que o POST /monitor devolve uma única vez. Confira a assinatura antes de criar a tarefa para o vendedor; uma resposta 2xx confirma o recebimento e, sem ela, a entrega é repetida.
import hashlib, hmac, json, os
SEGREDO = os.environ['PROMETIAM_WEBHOOK_SECRET'].encode() # webhook_secret do POST /monitor
def receber_alerta(corpo: bytes, assinatura: str) -> int:
"""corpo = corpo bruto da requisição; assinatura = cabeçalho X-Prometiam-Signature."""
esperada = 'sha256=' + hmac.new(SEGREDO, corpo, hashlib.sha256).hexdigest()
if not hmac.compare_digest(assinatura, esperada):
return 401
alerta = json.loads(corpo)
# alerta['label'] = id no CRM, alerta['alert_type'], alerta['company']['name'], alerta['event_date']
# em corporate_event: alerta['detail'] = {'event_type': 'capital_change', 'previous_value': '80000', 'new_value': '210000'}
... # cria a tarefa para o dono da conta alerta['label']
return 204
O webhook está em todos os planos. Os alertas também podem ser lidos em GET /monitor (os seus acompanhamentos e os 50 alertas mais recentes), então uma rotina noturna pode ocupar o lugar do webhook. O teste acompanha 3 empresas, o Starter 25, o Professional 250 e o Scale 2.500.
Sem nome e sem CNPJ, a mesma chamada é o feed de eventos do país: tudo o que apareceu no cadastro, do mais novo ao mais antigo, filtrado por event_type. O date_from é, por padrão, 7 dias atrás e pode voltar no máximo 31 dias (uma data mais antiga é recusada com 400). Cada chamada custa 2 créditos por até 100 eventos, e a página seguinte se pede com next_cursor.
# Todos os aumentos e reduções de capital social vistos nos últimos 30 dias (100 eventos por chamada) # no macOS: date -v-30d +%F no lugar de date -d '30 days ago' +%F curl "https://api.prometiam.com/functions/v1/risk-api/company-events/search?country=BR&event_type=capital_change&date_from=$(date -d '30 days ago' +%F)&limit=100" \ -H 'Authorization: Bearer rk_live_...'
Como a fonte é lida uma vez por mês, o intervalo padrão de 7 dias pode devolver uma lista vazia entre duas cargas; por isso o exemplo parte de 30 dias atrás. Uma rotina frequente guarda o event_date mais recente que viu, recomeça dele e descarta repetidos pelo id do evento. O feed alcança no máximo 31 dias: rode a rotina pelo menos uma vez por mês.
O founded_after lista as empresas abertas desde uma data, sem nome, da mais nova à mais antiga: até 100 por chamada, a 1 crédito, com next_cursor para a página seguinte. Cada registro traz founding_date, o CNAE em activity_code, o capital em capital_amount, city, region (o estado) e, em registry_details, o porte (size_class: ME, EPP ou DEMAIS, uma classe de faturamento, não de funcionários) e o bairro (district).
# Empresas abertas desde 1º de outubro, as mais novas primeiro (100 por chamada) curl 'https://api.prometiam.com/functions/v1/risk-api/companies/search?country=BR&founded_after=2026-10-01&limit=100' \ -H 'Authorization: Bearer rk_live_...'
O servidor só filtra por data de abertura (founded_after e founded_before): um cnae= é recusado com 400, e atividade, porte e estado ficam por conta do seu código.
def novas(desde, cnae='62', porte='ME'):
"""Empresas abertas desde uma data, com CNAE iniciado por cnae e o porte dado (usa requests, BASE e H acima)."""
cursor = None
while True:
p = {'country': 'BR', 'founded_after': desde, 'limit': 100}
if cursor:
p['cursor'] = cursor
r = requests.get(f'{BASE}/companies/search', headers=H, params=p)
r.raise_for_status()
corpo = r.json()
for e in corpo['data']:
detalhes = e.get('registry_details') or {}
if (e['activity_code'] or '').startswith(cnae) and detalhes.get('size_class') == porte:
yield e['company_number'], e['company_name'], e['city'], e['region']
cursor = corpo['pagination']['next_cursor']
if not cursor:
break
O meta.data_as_of mostra a data a que os dados se referem, e as empresas abertas depois dela aparecem na carga seguinte. Cada página de 100 empresas custa 1 crédito: limite desde ao período de que você precisa. Para conferir um CNPJ à mão, use a consulta de CNPJ.
vat= é recusada).status e nos eventos.BR-CNAE-2.3), não a NACE, e a atualização é mensal.O acompanhamento não consome créditos: o plano define quantas empresas você acompanha (3 no teste, 25 no Starter, 250 no Professional e 2.500 no Scale; os webhooks estão em todos os planos). Uma busca de empresa custa 1 crédito, e uma busca de eventos ou uma chamada ao feed do país, 2; erros não custam nada. No teste, as buscas de eventos (inclusive o feed do país) têm um limite de 25 chamadas por mês; a partir do Starter esse limite não existe. O Starter custa € 9,99 por mês com 1.000 créditos, o Professional € 29,99 com 10.000 e o Scale € 99,99 com 50.000. O teste gratuito dura 14 dias e inclui 500 créditos: é preciso informar um cartão, nada é cobrado durante o teste e, depois, vale o plano Starter (€ 9,99 por mês), salvo cancelamento. Veja os preços.
Contains data from the Cadastro Nacional da Pessoa Jurídica (CNPJ), Receita Federal do Brasil, published as open data (CC BY). Adapted by Prometiam.
Começar o teste gratuito de 14 dias · Documentação da API
O teste dura 14 dias e inclui 500 créditos. É necessário informar um cartão; nada é cobrado durante o teste e, depois, vale o plano Starter (€ 9,99 por mês), salvo cancelamento.