Documentación de la API
Integra facilita.tools directamente en tus sistemas mediante nuestra API REST.
Colección Postman / Insomnia
URL base
https://facilita.tools
Autenticación
X-Api-Key: your_key
Formato
application/json
Referencia API
Documentación técnica de endpoints
Toda la autenticación, límites, parámetros, ejemplos y pruebas interactivas están centralizados abajo.
Autenticación
Todas las solicitudes de la API requieren el header
X-Api-Key
en todas las solicitudes.
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 plan tiene límites específicos para solicitudes API. Los headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset se incluyen en cada respuesta.
| Plano | req/mes | 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 Límite
X-RateLimit-Limit: 5000 # Cuota mensual
X-RateLimit-Remaining: 4987 # Solicitudes restantes
X-RateLimit-Reset: 1735689600 # Timestamp de reset (epoch)
Retry-After: 60 # Segundos de espera (en 429)Retorna datos de empresas de la Receita Federal brasileña (datos abiertos). Acepta CNPJ numérico (14 dígitos) o alfanumérico.
Parámetros
| Nome | Tipo | obligatorio | Descrição |
|---|---|---|---|
| cnpj | string | obligatorio | 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" }]
}Probar
Respuesta
Retorna datos de dirección a partir de un código postal brasileño (CEP, 8 dígitos).
Parámetros
| Nome | Tipo | obligatorio | Descrição |
|---|---|---|---|
| cep | string | obligatorio | 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"
}Probar
Respuesta
Convierte valores entre monedas usando las tasas de cambio oficiales del Banco Central de Brasil (BCB/PTAX), actualizadas diariamente.
/api/v1/currency/convert?from=USD&to=BRL&amount=1
| Nome | Tipo | Descrição | |
|---|---|---|---|
| from | string | obligatorio | Moeda de origem (ex: USD, EUR) |
| to | string | obligatorio | Moeda de destino (ex: BRL) |
| amount | number | opcional | Valor a converter (padrão: 1) |
/api/v1/currency/currencies
Retorna la lista de las 29 monedas soportadas con nombres.
{ "currencies": [{ "code": "USD", "name": "Dólar Americano" }, ...] }Probar
Respuesta
/api/v1/cpf/validate
Valida un CPF con el algoritmo Módulo 11. Retorna validez y CPF formateado.
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
Genera CPFs válidos aleatorios para desarrollo. Máx 1.000 por solicitud.
Response 200
{ "cpfs": ["123.456.789-09", "987.654.321-00", "111.222.333-96", "444.555.666-61", "777.888.999-33"] }Probar — POST /validate
Respuesta
/api/v1/cnpj/validate
Valida un CNPJ numérico (14 dígitos) con el algoritmo oficial.
Request
{ "cnpj": "11222333000181" }Response 200
{ "valid": true, "formatted": "11.222.333/0001-81" }/api/v1/cnpj/generate?quantity=5&formatted=true
Genera CNPJs válidos aleatorios para desarrollo. Máx 1.000 por solicitud.
{ "cnpjs": ["11.222.333/0001-81", "44.555.666/0001-72", ...] }/api/v1/cnpj-alphanumeric/validate
Valida un CNPJ alfanumérico según IN RFB 2.119/2022 (vigente julio 2026).
Request
{ "cnpj": "12ABC34501DE35" }Response 200
{ "valid": true, "formatted": "12.ABC.345/01DE-35" }/api/v1/cnpj-alphanumeric/generate?quantity=3
Genera CNPJs alfanuméricos válidos aleatorios para desarrollo. Máx 50 por solicitud.
{ "cnpjs": ["12.ABC.345/01DE-35", "9K.M2P.Q78/0RST-61", "3X.YZ1.W56/04AB-89"] }/api/v1/pix/key/validate
Valida una clave PIX (CPF, CNPJ, email, teléfono o EVP/UUID). Retorna tipo y validez.
Request
{ "key": "12345678909" }Response 200
{
"valid": true,
"keyType": "cpf",
"formattedKey": "123.456.789-09",
"error": null
}/api/v1/pix/key/identify
Identifica el tipo de una clave PIX sin validación completa.
Request
{ "key": "[email protected]" }Response 200
{ "key": "[email protected]", "type": "email" }/api/v1/pix/evp/generate?quantity=3
Genera claves EVP aleatorias (UUID v4). Máx 100 por solicitud.
{ "keys": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", ...] }Probar — POST /key/validate
Respuesta
/api/v1/nfe/key/validate
Valida una clave de acceso 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 los componentes de una clave de acceso NFe sin validación.
Request
{ "key": "3524061122233300018155001..." }Response 200
{ "valid": true, "details": { "uf": "SP", ... } }/api/v1/nfe/key/generate
Genera claves de acceso NFe válidas aleatorias para desarrollo.
// Request: { "quantity": 2, "ufCode": "35", "model": "55" }
// Response: { "keys": ["35240611222333000181550010000001001234567897", ...] }/api/v1/nfe/uf-codes
Retorna todos los códigos de estado (UF) brasileños válidos con nombres.
{ "ufCodes": [{ "code": "35", "name": "São Paulo" }, ...] }Probar — POST /key/validate
Respuesta
/api/v1/utils/password/generate
Genera contraseñas seguras aleatorias con opciones configurables.
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
Cuenta caracteres, palabras, oraciones y párrafos en un texto.
Request
{ "text": "The quick brown fox." }Response 200
{ "characters": 20, "charactersNoSpaces": 17, "words": 4, "sentences": 1, "paragraphs": 1 }/api/v1/utils/text/convert
Convierte mayúsculas/minúsculas: 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
Convierte números entre bases: binario, 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
Convierte entre numerales arábigos y romanos. Pasar 'number' o '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 el Índice de Masa Corporal (IMC) con clasificación 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. Ejemplo: 15% de 200 = 30.
{ "result": 30.00 }/api/v1/calc/percentage/what-percent?value=30&of=200
¿Qué porcentaje es X de Y? Ejemplo: 30 es qué % de 200 = 15%.
{ "result": 15.00 }/api/v1/calc/percentage/change?from=100&to=150
Variación porcentual de X a Y. Ejemplo: 100 a 150 = +50%.
{ "result": 50.00 }/api/v1/calc/hours
Calcula el total de horas trabajadas con horarios de entrada/salida y pausa opcional.
Request
{ "startTime": "08:00", "endTime": "17:00", "lunchMinutes": 60 }Response 200
{ "totalHours": 8.0, "formatted": "08:00" }/api/v1/calc/net-salary
Calcula salario neto a partir del bruto, aplicando tablas 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 el DAS MEI mensual basado en el tipo de actividad (comercio, servicios o ambos).
Request
{ "activityType": "commerce" }Response 200
{
"inss": 75.90,
"icms": 1.00,
"iss": 0.00,
"total": 76.90
}| HTTP | Significado | Causa comum |
|---|---|---|
| 200 | OK | Solicitud exitosa. |
| 400 | Mala petición | Parámetros inválidos (ej: CPF/CNPJ con longitud incorrecta). |
| 401 | Unauthorized | Header X-Api-Key ausente o inválido. |
| 404 | No se ha encontrado | CNPJ o CEP no encontrado en la base de datos. |
| 429 | Demasiadas peticiones | Límite de solicitudes excedido. Vea los límites de su plan. |
| 500 | Error del servidor | Error interno del servidor. Intente de nuevo. |
Documentación de Integración
Guías de implementación y recomendaciones operativas
Esta área agrupa tutoriales prácticos, patrones de arquitectura, seguridad y material de soporte para operar en producción.
Inicio Rápido — En funcionamiento en 5 minutos
De cero a tu primera llamada exitosa
Crea tu cuenta
Crea tu cuenta sin tarjeta de crédito. El plan Free incluye 5.000 solicitudes/mes.
Crear cuenta →Genera tu API Key
En tu panel, ve a API Keys y haz clic en "Nueva Key". Cada key está vinculada a los límites de tu plan. Guárdala a salvo.
Ir al panel →Haz tu primera solicitud
Agrega el header X-Api-Key a cualquier endpoint y ya estás listo.
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"}'Maneja la respuesta
Todas las respuestas tienen el mismo formato. Verifica success, lee los datos, monitorea los headers de cuota:
// 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
Guías de Integración
Tutoriales paso a paso para escenarios reales de integración
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;
}Buenas Prácticas
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