Documentação da API
Integre o facilita.tools diretamente nos seus sistemas via nossa API REST.
Coleção Postman / Insomnia
URL base
https://facilita.tools
Autenticação
X-Api-Key: your_key
Formato
application/json
Referencia de API
Documentação tecnica de endpoints
Toda autenticacao, limites, parametros, exemplos e testes interativos estao centralizados abaixo.
Autenticação
Todas as requisições da API exigem o header
X-Api-Key
em todas as requisições.
curl -X POST https://facilita.tools/api/v1/cpf/validate \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cpf": "12345678909"}'Cada plano possui limites específicos de requisições à API. Os headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset são incluídos em todas as respostas.
| Plano | req/mês | req/min | API Keys |
|---|---|---|---|
| Free | 5.000 | 5 | 1 |
| API Dev | 60.000 | 15 | 3 |
| API Pro | 230.000 | 40 | 5 |
| API Business | 1.200.000 | 100 | 10 |
| API Enterprise | 3.500.000 | 200 | 20 |
Headers de Limite
X-RateLimit-Limit: 5000 # Cota mensal
X-RateLimit-Remaining: 4987 # Requisições restantes
X-RateLimit-Reset: 1735689600 # Timestamp de reset (epoch)
Retry-After: 60 # Segundos de espera (quando 429)Retorna dados de empresas da Receita Federal brasileira (dados abertos). Aceita CNPJ numérico (14 dígitos) ou alfanumérico.
Parâmetros
| Nome | Tipo | obrigatório | Descrição |
|---|---|---|---|
| cnpj | string | obrigatório | CNPJ numérico (14 dígitos) ou alfanumérico |
Exemplo de resposta
{
"success": true,
"cnpj": "11222333000181",
"razaoSocial": "EMPRESA EXEMPLO LTDA",
"nomeFantasia": "Nome Fantasia",
"situacaoCadastral": "ATIVA",
"naturezaJuridica": "206-2 - Sociedade Empresária Limitada",
"capitalSocial": 10000.00,
"logradouro": "Rua Exemplo",
"numero": "100",
"municipio": "São Paulo",
"uf": "SP",
"cep": "01310-100",
"telefone": "(11) 3333-4444",
"partners": [{ "name": "FULANO DE TAL", "document": "***.123.456-**", "role": "Sócio" }]
}Testar
Resposta
Retorna dados de endereço a partir de um CEP brasileiro (8 dígitos).
Parâmetros
| Nome | Tipo | obrigatório | Descrição |
|---|---|---|---|
| cep | string | obrigatório | CEP com 8 dígitos |
Exemplo de resposta
{
"success": true,
"cep": "01310-100",
"logradouro": "Avenida Paulista",
"complemento": "de 1 a 610 - lado par",
"bairro": "Bela Vista",
"localidade": "São Paulo",
"uf": "SP",
"ibge": "3550308",
"ddd": "11"
}Testar
Resposta
Converte valores entre moedas usando as taxas de câmbio oficiais do Banco Central do Brasil (BCB/PTAX), atualizadas diariamente.
/api/v1/currency/convert?from=USD&to=BRL&amount=1
| Nome | Tipo | Descrição | |
|---|---|---|---|
| from | string | obrigatório | Moeda de origem (ex: USD, EUR) |
| to | string | obrigatório | Moeda de destino (ex: BRL) |
| amount | number | opcional | Valor a converter (padrão: 1) |
/api/v1/currency/currencies
Retorna a lista de todas as 29 moedas suportadas com nomes.
{ "currencies": [{ "code": "USD", "name": "Dólar Americano" }, ...] }Testar
Resposta
/api/v1/cpf/validate
Valida um CPF usando o algoritmo Módulo 11. Retorna validade e CPF formatado.
Request
POST /api/v1/cpf/validate
Content-Type: application/json
{ "cpf": "12345678909" }Response 200
{
"valid": true,
"formatted": "123.456.789-09"
}/api/v1/cpf/generate?quantity=5&formatted=true
Gera CPFs válidos aleatórios para desenvolvimento. Máx 1.000 por requisição.
Response 200
{ "cpfs": ["123.456.789-09", "987.654.321-00", "111.222.333-96", "444.555.666-61", "777.888.999-33"] }Testar — POST /validate
Resposta
/api/v1/cnpj/validate
Valida um CNPJ numérico (14 dígitos) usando o algoritmo oficial.
Request
{ "cnpj": "11222333000181" }Response 200
{ "valid": true, "formatted": "11.222.333/0001-81" }/api/v1/cnpj/generate?quantity=5&formatted=true
Gera CNPJs válidos aleatórios para desenvolvimento. Máx 1.000 por requisição.
{ "cnpjs": ["11.222.333/0001-81", "44.555.666/0001-72", ...] }/api/v1/cnpj-alphanumeric/validate
Valida um CNPJ alfanumérico conforme IN RFB 2.119/2022 (vigência julho 2026).
Request
{ "cnpj": "12ABC34501DE35" }Response 200
{ "valid": true, "formatted": "12.ABC.345/01DE-35" }/api/v1/cnpj-alphanumeric/generate?quantity=3
Gera CNPJs alfanuméricos válidos aleatórios para desenvolvimento. Máx 50 por requisição.
{ "cnpjs": ["12.ABC.345/01DE-35", "9K.M2P.Q78/0RST-61", "3X.YZ1.W56/04AB-89"] }/api/v1/pix/key/validate
Valida uma chave PIX (CPF, CNPJ, email, telefone ou EVP/UUID). Retorna tipo e validade.
Request
{ "key": "12345678909" }Response 200
{
"valid": true,
"keyType": "cpf",
"formattedKey": "123.456.789-09",
"error": null
}/api/v1/pix/key/identify
Identifica o tipo de uma chave PIX sem validação completa.
Request
{ "key": "[email protected]" }Response 200
{ "key": "[email protected]", "type": "email" }/api/v1/pix/evp/generate?quantity=3
Gera chaves EVP aleatórias (UUID v4). Máx 100 por requisição.
{ "keys": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", ...] }Testar — POST /key/validate
Resposta
/api/v1/nfe/key/validate
Valida uma chave de acesso NFe de 44 dígitos usando Módulo 11.
Request
{ "key": "35240611222333000181550010000001001234567897" }Response 200
{ "valid": true, "details": { "uf": "SP", "emissionDate": "2024-06", "cnpj": "11222333000181", "model": "55", "series": "001", "number": "000000100", "emissionType": "Normal", "numericCode": "12345678", "checkDigit": "7" } }/api/v1/nfe/key/parse
Decodifica todos os componentes de uma chave de acesso NFe sem validação.
Request
{ "key": "3524061122233300018155001..." }Response 200
{ "valid": true, "details": { "uf": "SP", ... } }/api/v1/nfe/key/generate
Gera chaves de acesso NFe válidas aleatórias para desenvolvimento.
// Request: { "quantity": 2, "ufCode": "35", "model": "55" }
// Response: { "keys": ["35240611222333000181550010000001001234567897", ...] }/api/v1/nfe/uf-codes
Retorna todos os códigos de UF brasileiros válidos com nomes.
{ "ufCodes": [{ "code": "35", "name": "São Paulo" }, ...] }Testar — POST /key/validate
Resposta
/api/v1/utils/password/generate
Gera senhas seguras aleatórias com opções configuráveis.
Request
{
"length": 16,
"quantity": 3,
"uppercase": true,
"lowercase": true,
"numbers": true,
"symbols": true
}Response 200
{
"passwords": [
{ "value": "kF9#mP2$xL7&nQ4!", "strength": "strong" },
...
]
}/api/v1/utils/text/count
Conta caracteres, palavras, sentenças e parágrafos em um texto.
Request
{ "text": "The quick brown fox." }Response 200
{ "characters": 20, "charactersNoSpaces": 17, "words": 4, "sentences": 1, "paragraphs": 1 }/api/v1/utils/text/convert
Converte caixa de texto: upper, lower, title, sentence, slug, reverse, alternating.
Request
{ "text": "the quick brown fox", "mode": "upper" }Response 200
{ "original": "the quick brown fox", "converted": "THE QUICK BROWN FOX", "mode": "upper" }/api/v1/utils/number-base/convert
Converte números entre bases: binário, octal, decimal, hexadecimal.
Request
{ "value": "255", "fromBase": 10, "toBase": 16 }Response 200
{ "original": "255", "converted": "FF", "fromBase": 10, "toBase": 16 }/api/v1/utils/roman?number=42
Converte entre numerais arábicos e romanos. Passar 'number' ou 'roman' como query param.
// GET /api/v1/utils/roman?number=42 → { "arabic": 42, "roman": "XLII" }
// GET /api/v1/utils/roman?roman=XLII → { "arabic": 42, "roman": "XLII" }/api/v1/calc/bmi
Calcula o Índice de Massa Corporal (IMC) com classificação OMS.
Request
{ "weight": 75, "height": 1.75 }Response 200
{ "bmi": 24.49, "classification": "Normal weight", "idealMin": 56.66, "idealMax": 76.56 }/api/v1/calc/percentage?percent=15&of=200
Calcula X% de Y. Exemplo: 15% de 200 = 30.
{ "result": 30.00 }/api/v1/calc/percentage/what-percent?value=30&of=200
Quanto % é X de Y? Exemplo: 30 é quanto % de 200 = 15%.
{ "result": 15.00 }/api/v1/calc/percentage/change?from=100&to=150
Variação percentual de X para Y. Exemplo: 100 para 150 = +50%.
{ "result": 50.00 }/api/v1/calc/hours
Calcula total de horas trabalhadas com horários de entrada/saída e intervalo opcional.
Request
{ "startTime": "08:00", "endTime": "17:00", "lunchMinutes": 60 }Response 200
{ "totalHours": 8.0, "formatted": "08:00" }/api/v1/calc/net-salary
Calcula salário líquido a partir do bruto, aplicando tabelas INSS e IRRF 2026 (Lei 15.270/2025).
Request
{ "grossSalary": 5000, "dependents": 1 }Response 200
{
"grossSalary": 5000.00,
"inssDiscount": 525.47,
"irrfDiscount": 83.72,
"netSalary": 4390.81
}/api/v1/calc/das-mei
Calcula o DAS MEI mensal com base no tipo de atividade (comércio, serviços ou ambos).
Request
{ "activityType": "commerce" }Response 200
{
"inss": 75.90,
"icms": 1.00,
"iss": 0.00,
"total": 76.90
}| HTTP | Significado | Causa comum |
|---|---|---|
| 200 | OK | Requisição bem-sucedida. |
| 400 | Solicitação ruim | Parâmetros inválidos (ex: CPF/CNPJ com tamanho incorreto). |
| 401 | Unauthorized | Header X-Api-Key ausente ou inválido. |
| 404 | Não encontrado | CNPJ ou CEP não encontrado na base de dados. |
| 429 | Muitas solicitações | Limite de requisições atingido. Veja os limites do seu plano. |
| 500 | Erro do servidor | Erro interno. Tente novamente em alguns instantes. |
Documentacao de Integracao
Guias de implementacao e recomendacoes operacionais
Esta area agrupa tutoriais praticos, padroes de arquitetura, seguranca e material de suporte para o time operar em producao.
Quick Start — Funcionando em 5 minutos
Do zero à sua primeira chamada bem-sucedida
Crie sua conta
Crie sua conta sem cartão de crédito. O plano Free inclui 5.000 requisições/mês para você começar.
Criar conta →Gere sua API Key
No dashboard, vá em Chaves de API e clique em "Nova Chave". Cada chave tem os limites do seu plano. Guarde-a com segurança — trate como uma senha.
Acessar dashboard →Faça sua primeira requisição
Adicione o header X-Api-Key em qualquer endpoint e você já está pronto. Veja a chamada mais simples possível:
curl https://facilita.tools/api/v1/cpf/validate \
-X POST \
-H "X-Api-Key: SUA_CHAVE_AQUI" \
-H "Content-Type: application/json" \
-d '{"cpf": "12345678909"}'Trate a resposta
Todas as respostas seguem o mesmo envelope. Verifique o campo success, leia os dados e monitore os headers de cota:
// Resposta:
{ "valid": true, "formatted": "123.456.789-09" }
// Headers de controle:
X-RateLimit-Remaining: 4987 // requisições restantes
X-RateLimit-Reset: 1735689600 // próximo reset (epoch)Nossa API é HTTPS + JSON puro — nenhum SDK especial necessário. Funciona com Python, Node.js, PHP, Java, C#, Go, Ruby ou qualquer cliente HTTP.
Python
Node.js
PHP
Java
C#
Go
Guias de Integração
Tutoriais passo a passo para cenários reais de integração
Escritos para times em produção — sem exemplos fictícios.
O problema: consultas manuais de CNPJ travam o time comercial
Times comerciais perdem horas copiando CNPJs em portais governamentais, verificando manualmente se a empresa está ativa e transcrevendo endereços. Com a API facilita.tools, você automatiza esse fluxo inteiro com poucas linhas de código.
Arquitetura recomendada
Ação do formulário
Usuário digita o CNPJ
Job em background
Chama a API facilita.tools
Enriquecer cadastro
Salva dados da empresa
Implementação — Node.js + fila (BullMQ)
// cnpjEnrichmentJob.js
import { Queue, Worker } from 'bullmq';
const cnpjQueue = new Queue('cnpj-enrichment', { connection });
// Adiciona à fila quando usuário cadastra
async function onNewCustomer(cnpj, customerId) {
await cnpjQueue.add('enrich', { cnpj, customerId });
}
// Worker que processa em background
new Worker('cnpj-enrichment', async (job) => {
const { cnpj, customerId } = job.data;
const res = await fetch(`https://facilita.tools/api/v1/cnpj/lookup/${cnpj}`, {
headers: { 'X-Api-Key': process.env.FACILITA_API_KEY }
});
if (!res.ok) throw new Error(`API error: ${res.status}`);
const data = await res.json();
// Atualiza o cadastro com os dados enriquecidos
await db.customers.update(customerId, {
companyName: data.razaoSocial,
tradeName: data.nomeFantasia,
status: data.situacaoCadastral,
address: `${data.logradouro}, ${data.numero} - ${data.municipio}/${data.uf}`,
phone: data.telefone,
cnae: data.naturezaJuridica
});
}, { connection });Dica pro: Faça cache da resposta do CNPJ no Redis por 24h. Dados de empresa raramente mudam todo dia, e isso reduz drasticamente o uso da sua API.
Ao validar grandes lotes (importações de CSV, limpeza de banco, fluxos de onboarding), respeitar os rate limits é crítico. Veja uma implementação Python de produção com backoff exponencial:
Python
import asyncio, httpx, time, math
API_KEY = "SUA_CHAVE"
BASE_URL = "https://facilita.tools/api/v1"
async def validate_cpf(client: httpx.AsyncClient, cpf: str, retries=3) -> dict:
"""Valida um CPF com retry exponencial ao receber 429."""
for attempt in range(retries):
resp = await client.post(
f"{BASE_URL}/cpf/validate",
json={"cpf": cpf},
headers={"X-Api-Key": API_KEY}
)
if resp.status_code == 200:
return {"cpf": cpf, **resp.json()}
if resp.status_code == 429:
wait = math.pow(2, attempt) + 0.5 # 0.5s, 1.5s, 2.5s
retry_after = int(resp.headers.get("Retry-After", wait))
await asyncio.sleep(retry_after)
continue
return {"cpf": cpf, "valid": False, "error": resp.status_code}
return {"cpf": cpf, "valid": False, "error": "max_retries"}
async def validate_bulk(cpfs: list[str], concurrency=5) -> list[dict]:
"""Valida uma lista de CPFs com concorrência controlada."""
semaphore = asyncio.Semaphore(concurrency) # max 5 req/s (plano Free)
results = []
async def guarded(cpf):
async with semaphore:
return await validate_cpf(client, cpf)
async with httpx.AsyncClient(timeout=10) as client:
tasks = [guarded(cpf) for cpf in cpfs]
results = await asyncio.gather(*tasks)
return results
# Uso:
# cpfs = ["12345678909", "98765432100", ...]
# results = asyncio.run(validate_bulk(cpfs))Limites de concorrência por plano
5/min
Free
15/min
Dev
40/min
Pro
100/min
Business
200/min
Enterprise
Nunca faça isso
- Commitar a API Key no Git — vaza permanentemente via busca no GitHub
- Chamar a API direto do JavaScript no frontend (visível no DevTools)
- Compartilhar uma chave entre produção e desenvolvimento
- Logar o header X-Api-Key em texto plano nos seus logs
Faça assim
- Armazene em variáveis de ambiente — nunca no código-fonte
- Sempre chame via backend/servidor — jamais pelo browser
- Use keys separadas por ambiente (prod/staging/dev)
- Rotacione as keys a cada 90 dias ou imediatamente após suspeita de vazamento
Padrão de rotação — zero downtime
# 1. Gere uma nova API Key no dashboard (sem revogar a atual)
# 2. Faça o deploy com a NOVA key como variável de ambiente
# 3. Verifique que a nova key está funcionando em produção
# 4. Só então revogue a key antiga no dashboard
# → Zero downtime, nenhuma requisição falha durante a trocaToda resposta da facilita.tools inclui headers de cota. Parse-os em cada chamada e construa um contador local. Veja como enviar um alerta no Slack ao atingir 80% do uso:
// middleware/quotaMonitor.js
const ALERT_THRESHOLD = 0.80; // alerta em 80% de uso
let alertSentThisMonth = false;
export async function withQuotaTracking(fetchFn) {
const response = await fetchFn();
const limit = parseInt(response.headers.get('X-RateLimit-Limit') ?? 0);
const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') ?? 0);
const resetAt = parseInt(response.headers.get('X-RateLimit-Reset') ?? 0);
if (limit > 0) {
const used = limit - remaining;
const usedPct = used / limit;
// Persiste métricas (ex: Redis, banco, datadog)
await metrics.gauge('facilita_api.used_pct', usedPct);
await metrics.gauge('facilita_api.remaining', remaining);
// Alerta Slack uma vez por mês ao atingir 80%
if (usedPct >= ALERT_THRESHOLD && !alertSentThisMonth) {
alertSentThisMonth = true;
await sendSlackAlert({
text: `⚠️ facilita.tools API: ${(usedPct*100).toFixed(0)}% da cota usada.`,
fields: [
{ title: 'Usado', value: `${used.toLocaleString()} req` },
{ title: 'Restante', value: `${remaining.toLocaleString()} req` },
{ title: 'Reset em', value: new Date(resetAt * 1000).toLocaleString('pt-BR') }
]
});
}
}
return response;
}Boas Práticas
Recomendações para uma integração estável, segura e eficiente
Cache respostas agressivamente
Dados de CNPJ e CEP raramente mudam. Cache por no mínimo 1h para CNPJ (situação cadastral) e 24h para dados de endereço. Economiza cota e reduz latência.
Valide antes de chamar a API
Execute validação de formato no cliente (CPF: 11 dígitos, CNPJ: 14 dígitos, CEP: 8 dígitos) antes de chamar a API. Não consome cota e rejeita entradas obviamente inválidas instantaneamente.
Use connection pooling e keep-alive
Reutilize conexões HTTP. Em Node.js, crie uma instância única de axios ou undici Pool. Em Python, use um httpx.Client compartilhado. Reduz latência em 30–50% em chamadas repetidas.
Deduplique requisições em cenários de lote
Ao processar um CSV com 10.000 CNPJs, primeiro deduplique a lista. Bases reais costumam ter 15–30% de duplicatas. Processar apenas valores únicos pode economizar até 30% da sua cota instantaneamente.
Implemente circuit breakers em produção
Envolva chamadas de API com um circuit breaker (ex: opossum para Node.js, pybreaker para Python). Isso evita falhas em cascata: se a API ficou temporariamente indisponível, o seu sistema degrada graciosamente em vez de travar.
Monitore sua integração em produção
Logue o header X-RateLimit-Remaining no seu APM (Datadog, New Relic, Grafana). Configure alertas em 80% de uso. Acompanhe a latência p95 — nossa API tem target p99 abaixo de 300ms.
Dúvidas Frequentes
Respostas para as dúvidas mais comuns dos nossos usuários de API
Sim. Nossa base de CNPJ é atualizada mensalmente a partir do portal de dados abertos da Receita Federal (dados.gov.br). Situação cadastral, endereço e QSA refletem o último snapshot oficial. Para workflows de compliance crítico, recomendamos combinar nossa API com uma política de frequência própria.
A API retorna HTTP 429 Too Many Requests com o header Retry-After indicando quantos segundos aguardar. As cotas mensais resetam no 1º de cada mês (horário de Brasília). Durante a janela de reset, requisições podem brevemente retornar 429 — implemente backoff exponencial para tratar isso de forma transparente.
Upgrades de plano são gerenciados via dashboard de faturamento. Não há upgrade automático — intencionalmente exigimos uma decisão humana antes de aumentar o compromisso. Se precisar de capacidade extra com curto prazo, entre em contato pelo chat de suporte no dashboard.
Validação de CPF e CNPJ usa o algoritmo Módulo 11 oficial publicado pela Receita Federal — o mesmo usado por bancos e sistemas governamentais. Um resultado 'válido' significa que os dígitos verificadores estão corretos. Isso não significa que o documento existe em uma base governamental (consulta vs. validação são conceitos distintos).
A API é hospedada na Oracle Cloud no Brasil com CDN global da Cloudflare. Requisições da Europa, EUA ou Ásia geralmente completam em 100–250ms. Não há restrições geográficas — qualquer IP pode chamar nossos endpoints.
Sim. O plano Free é projetado para cargas de produção menores (startups, projetos paralelos, ferramentas internas). Não há limite de tempo. Faça upgrade quando seu volume superar 5.000 req/mês.
Sim. Todos os endpoints são exclusivamente via HTTPS (TLS 1.2+). Requisições HTTP são automaticamente redirecionadas pela camada Cloudflare. Nunca envie sua API Key por conexões não criptografadas.
Para API Pro e acima, temos como target 99,9% de uptime mensal, monitorado externamente. Incidentes são comunicados via nossa página de status. Para planos Enterprise, compromissos de uptime são definidos no contrato de serviço.
Sim. Uma única chave pode ser chamada de múltiplos IPs simultaneamente. Os limites de rate são aplicados por chave, não por IP. Se necessário, você pode criar múltiplas chaves (dentro do limite do seu plano) e distribuir a carga entre elas.
Acesse seu dashboard imediatamente e revogue a chave comprometida. Gere uma nova chave. Audite seus logs por uso inesperado. A revogação tem efeito em segundos — a chave antiga passará imediatamente a retornar 401 Unauthorized.
Ainda tem dúvidas?
Nosso time responde dúvidas técnicas em até 24h nos dias úteis. Atendimento em PT-BR e inglês.
Changelog
Histórico de versões e funcionalidades previstas
O que está incluído
- CNPJ Lookup (dados abertos RF)
- CEP Lookup (ViaCEP + cache)
- Conversão de Moedas (API BCB PTAX)
- Validar/Gerar CPF (Módulo 11)
- Validar/Gerar CNPJ numérico
- Validar/Gerar CNPJ alfanumérico (IN RFB 2.119/2022)
- Validar Chave PIX (todas modalidades)
- Validar/Gerar Chave NFe (44 dígitos)
- Utilitários (gerador de texto, base numérica, romanos)
- Calculadoras (porcentagem, horas, rescisão, IMC, salário, DAS MEI)
Infraestrutura
- Rate limiting por API Key com headers em tempo real
- HTTPS exclusivo (TLS 1.2+) via Cloudflare
- Target de latência: p99 < 300ms
- Meta de uptime: 99,9% mensal (Pro+)
- 5 linguagens nos exemplos de código
- Painéis Try It interativos em cada endpoint
- Endpoints de lote — valide até 100 CPFs/CNPJs em uma única requisição
- Webhooks de monitoramento CNPJ — receba notificação quando o status de uma empresa mudar
- API de geração de PDF (via workers Xeon)
- SDKs oficiais para Python, Node.js e PHP