REST API v1

API Documentation

Integrate facilita.tools directly into your systems via our REST API.

0 endpoints 0 categories

Postman / Insomnia Collection

Base URL

https://facilita.tools

Authentication

X-Api-Key: your_key

Format

application/json

API Reference

Technical endpoint documentation

All authentication, limits, parameters, examples and interactive tests are centralized below.

Authentication

All API requests require the header X-Api-Key in all requests.

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"}'

const response = await fetch(
  'https://facilita.tools/api/v1/cpf/validate',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ cpf: '12345678909' })
  }
);
const data = await response.json();

import requests

response = requests.post(
    'https://facilita.tools/api/v1/cpf/validate',
    headers={
        'X-Api-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={'cpf': '12345678909'}
)
data = response.json()

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");

var response = await client.PostAsJsonAsync(
    "https://facilita.tools/api/v1/cpf/validate",
    new { cpf = "12345678909" }
);
var data = await response.Content.ReadFromJsonAsync<JsonElement>();

<?php
$ch = curl_init('https://facilita.tools/api/v1/cpf/validate');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode(['cpf' => '12345678909'])
]);
$data = json_decode(curl_exec($ch), true);

Each plan has specific limits for API requests. Headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset are included in every response.

Plan	req/month	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

Rate Limit Headers

X-RateLimit-Limit: 5000        # Monthly quota
X-RateLimit-Remaining: 4987    # Remaining requests
X-RateLimit-Reset: 1735689600  # Reset timestamp (epoch)
Retry-After: 60                # Seconds to wait (when 429)

Returns company data from the Brazilian Federal Revenue (Receita Federal) open data. Accepts numeric (14 digits) or alphanumeric CNPJ.

Parameters

Name	Type	required	Description
cnpj	string	required	14-digit numeric or alphanumeric CNPJ

Response example

{
  "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" }]
}

Try it

X-Api-Key (required)

cnpj (required)

Response

Returns address data for a Brazilian postal code (CEP). Accepts 8-digit numeric CEP.

Parameters

Name	Type	required	Description
cep	string	required	8-digit Brazilian postal code

Response example

{
  "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"
}

Try it

X-Api-Key (required)

cep (required)

Response

Converts amounts between currencies using the Brazilian Central Bank (BCB) official exchange rates (PTAX), updated daily.

GET /api/v1/currency/convert?from=USD&to=BRL&amount=1

Name	Type		Description
from	string	required	Source currency (e.g. USD, EUR)
to	string	required	Target currency (e.g. BRL)
amount	number	optional	Amount to convert (default: 1)

GET /api/v1/currency/currencies

Returns the list of all 29 supported currencies with names.

{ "currencies": [{ "code": "USD", "name": "Dólar Americano" }, ...] }

Try it

from

amount

X-Api-Key (required)

Response

POST /api/v1/cpf/validate

Validates a CPF using the Módulo 11 algorithm. Returns validity and formatted CPF.

Request

POST /api/v1/cpf/validate
Content-Type: application/json

{ "cpf": "12345678909" }

Response 200

{
  "valid": true,
  "formatted": "123.456.789-09"
}

GET /api/v1/cpf/generate?quantity=5&formatted=true

Generates valid random CPFs for development use. Max 1,000 per request.

Response 200

{ "cpfs": ["123.456.789-09", "987.654.321-00", "111.222.333-96", "444.555.666-61", "777.888.999-33"] }

Try it — POST /validate

X-Api-Key

cpf

Response

POST /api/v1/cnpj/validate

Validates a numeric CNPJ (14 digits) using the official algorithm.

Request

{ "cnpj": "11222333000181" }

Response 200

{ "valid": true, "formatted": "11.222.333/0001-81" }

GET /api/v1/cnpj/generate?quantity=5&formatted=true

Generates valid random CNPJs for development use. Max 1,000 per request.

{ "cnpjs": ["11.222.333/0001-81", "44.555.666/0001-72", ...] }

POST /api/v1/cnpj-alphanumeric/validate

Validates an alphanumeric CNPJ per IN RFB 2.119/2022 (effective July 2026).

Request

{ "cnpj": "12ABC34501DE35" }

Response 200

{ "valid": true, "formatted": "12.ABC.345/01DE-35" }

GET /api/v1/cnpj-alphanumeric/generate?quantity=3

Generates valid random alphanumeric CNPJs for development use. Max 50 per request.

{ "cnpjs": ["12.ABC.345/01DE-35", "9K.M2P.Q78/0RST-61", "3X.YZ1.W56/04AB-89"] }

POST /api/v1/pix/key/validate

Validates a PIX key (CPF, CNPJ, email, phone, or EVP/UUID). Returns type and validity.

Request

{ "key": "12345678909" }

Response 200

{
  "valid": true,
  "keyType": "cpf",
  "formattedKey": "123.456.789-09",
  "error": null
}

POST /api/v1/pix/key/identify

Identifies the type of a PIX key without full validation.

Request

{ "key": "[email protected]" }

Response 200

{ "key": "[email protected]", "type": "email" }

GET /api/v1/pix/evp/generate?quantity=3

Generates random EVP keys (UUID v4). Max 100 per request.

{ "keys": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", ...] }

Try it — POST /key/validate

X-Api-Key

key (CPF, CNPJ, email, phone, UUID)

Response

POST /api/v1/nfe/key/validate

Validates a 44-digit NFe access key using 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" } }

POST /api/v1/nfe/key/parse

Decodes all components of an NFe access key without validation.

Request

{ "key": "3524061122233300018155001..." }

Response 200

{ "valid": true, "details": { "uf": "SP", ... } }

POST /api/v1/nfe/key/generate

Generates valid random NFe access keys for development use.

// Request: { "quantity": 2, "ufCode": "35", "model": "55" }
// Response: { "keys": ["35240611222333000181550010000001001234567897", ...] }

GET /api/v1/nfe/uf-codes

Returns all valid Brazilian state (UF) codes with names.

{ "ufCodes": [{ "code": "35", "name": "São Paulo" }, ...] }

Try it — POST /key/validate

X-Api-Key

key (44 digits)

Response

POST /api/v1/utils/password/generate

Generates secure random passwords with configurable options.

Request

{
  "length": 16,
  "quantity": 3,
  "uppercase": true,
  "lowercase": true,
  "numbers": true,
  "symbols": true
}

Response 200

{
  "passwords": [
    { "value": "kF9#mP2$xL7&nQ4!", "strength": "strong" },
    ...
  ]
}

POST /api/v1/utils/text/count

Counts characters, words, sentences, and paragraphs in a text.

Request

{ "text": "The quick brown fox." }

Response 200

{ "characters": 20, "charactersNoSpaces": 17, "words": 4, "sentences": 1, "paragraphs": 1 }

POST /api/v1/utils/text/convert

Converts text case: uppercase, lowercase, 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" }

POST /api/v1/utils/number-base/convert

Converts numbers between bases: binary, octal, decimal, hexadecimal.

Request

{ "value": "255", "fromBase": 10, "toBase": 16 }

Response 200

{ "original": "255", "converted": "FF", "fromBase": 10, "toBase": 16 }

GET /api/v1/utils/roman?number=42

Converts between Arabic and Roman numerals. Pass 'number' or 'roman' query param.

// GET /api/v1/utils/roman?number=42 → { "arabic": 42, "roman": "XLII" }
// GET /api/v1/utils/roman?roman=XLII → { "arabic": 42, "roman": "XLII" }

POST /api/v1/calc/bmi

Calculates Body Mass Index (BMI) with WHO classification.

Request

{ "weight": 75, "height": 1.75 }

Response 200

{ "bmi": 24.49, "classification": "Normal weight", "idealMin": 56.66, "idealMax": 76.56 }

GET /api/v1/calc/percentage?percent=15&of=200

Calculates X% of Y. Example: 15% of 200 = 30.

{ "result": 30.00 }

GET /api/v1/calc/percentage/what-percent?value=30&of=200

What percentage is X of Y? Example: 30 is what % of 200 = 15%.

{ "result": 15.00 }

GET /api/v1/calc/percentage/change?from=100&to=150

Percentage change from X to Y. Example: 100 to 150 = +50%.

{ "result": 50.00 }

POST /api/v1/calc/hours

Calculates total worked hours from start/end times with optional lunch break.

Request

{ "startTime": "08:00", "endTime": "17:00", "lunchMinutes": 60 }

Response 200

{ "totalHours": 8.0, "formatted": "08:00" }

POST /api/v1/calc/net-salary

Calculates net salary from gross, applying INSS and IRRF 2026 tables (Lei 15.270/2025).

Request

{ "grossSalary": 5000, "dependents": 1 }

Response 200

{
  "grossSalary": 5000.00,
  "inssDiscount": 525.47,
  "irrfDiscount": 83.72,
  "netSalary": 4390.81
}

POST /api/v1/calc/das-mei

Calculates the monthly DAS MEI tax based on activity type (commerce, services, or both).

Request

{ "activityType": "commerce" }

Response 200

{
  "inss": 75.90,
  "icms": 1.00,
  "iss": 0.00,
  "total": 76.90
}

HTTP	Meaning	Common cause
200	OK	Request successful.
400	Bad Request	Invalid parameters (e.g. CPF/CNPJ with wrong length).
401	Unauthorized	Missing or invalid X-Api-Key header.
404	Not Found	CNPJ or CEP not found in the database.
429	Too Many Requests	Rate limit exceeded. See your plan limits.
500	Server Error	Unexpected server error. Try again later.

Integration Documentation

Implementation guides and operational recommendations

This area groups practical tutorials, architecture patterns, security and support material to help your team run in production.

Quick Start — Up and running in 5 minutes

From zero to first successful API call

Create your account

Create your account — no credit card required. Free plan includes 5,000 requests/month.

Create free account →

Generate your API Key

In your dashboard, go to API Keys and click "New Key". Each key is tied to your plan limits. Keep it safe — treat it like a password.

Go to dashboard →

Make your first request

Add the X-Api-Key header to any endpoint and you're ready to go. Here's the simplest possible call:

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"}'

Handle the response

All responses share the same envelope. Check success, read your data, monitor your quota headers:

// 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)

REST API — works with any language

Our API is plain HTTPS+JSON — no special SDK required. Works with Python, Node.js, PHP, Java, C#, Go, Ruby, or any HTTP client.

Python

Node.js

PHP

Java

Integration Guides

Step-by-step tutorials for real-world integration scenarios

Written for teams running production workloads — not toy examples.

The problem: manual CNPJ look-ups slow your team down

Teams waste hours copy-pasting CNPJs into government portals, manually checking if a company is active, and transcribing addresses. With facilita.tools API, you can automate this entire flow in a few lines of code.

Recommended architecture

Form action

User fills CNPJ

Background job

Call facilita.tools API

Enrich record

Save company data

Implementation — Node.js + queue (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 });

Pro tip: Cache the CNPJ response in Redis for 24h. Company data rarely changes daily, and this drastically reduces your API usage.

When validating large batches (CSV imports, database cleanup, onboarding flows), respecting rate limits is critical. Here's a production-grade Python implementation with exponential backoff:

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))

Concurrency limits by plan

5/min

Free

15/min

Dev

40/min

Pro

100/min

Business

200/min

Enterprise

Never do this

Commit your API Key in Git — leaked forever via GitHub search
Call the API from frontend JavaScript (exposed in DevTools)
Share one key between production and development environments
Log the X-Api-Key header in plain text in your log files

Do this instead

Store in environment variables — never in source code
Always call via backend/server — never from browser
Use separate keys per environment (prod/staging/dev)
Rotate keys every 90 days or immediately after a suspected leak

Rotation pattern — 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 troca

Every response from facilita.tools includes quota headers. Parse them on every call and build a local counter. Here's how to send a Slack alert when you reach 80% usage:

// 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;
}

Best Practices

Recommendations to build a stable, secure, and efficient integration

Cache responses aggressively

CNPJ and CEP data rarely changes. Cache at minimum 1h for CNPJ (situação cadastral), 24h for address data. This saves quota and reduces latency.

Validate before calling the API

Run client-side format validation (CPF: 11 digits, CNPJ: 14 digits, CEP: 8 digits) before hitting the API. This uses zero quota and rejects obviously invalid inputs instantly.

Use connection pooling and keep-alive

Reuse HTTP connections. In Node.js, create a single axios instance or undici Pool. In Python, use a shared httpx.Client. This cuts latency by 30-50% on repeated calls.

Deduplicate requests in batch scenarios

When processing a CSV with 10,000 CNPJs, first deduplicate the list. Real-world datasets typically have 15-30% duplicates. Processing unique values can save up to 30% of your quota instantly.

Implement circuit breakers for production

Wrap API calls with a circuit breaker (e.g. opossum for Node.js, pybreaker for Python). This prevents cascade failures: if our API is temporarily unavailable, your system degrades gracefully instead of crashing.

Monitor your integration in production

Log the X-RateLimit-Remaining header in your APM (Datadog, New Relic, Grafana). Set alerts at 80% usage. Track p95 latency — our API targets p99 under 300ms.

Frequently Asked Questions

Answers to the most common questions from our API users

Yes. Our CNPJ database is refreshed monthly from the Receita Federal open data portal (dados.gov.br). Registration status, address, and QSA data reflect the latest official snapshot. For critical compliance workflows, we recommend combining our API with your own frequency policy.

The API returns HTTP 429 Too Many Requests with a Retry-After header indicating seconds to wait. Monthly quotas reset on the 1st of each month (BRT). During the reset window, requests may briefly return 429 — implement exponential backoff to handle this transparently.

Plan upgrades are managed via the billing dashboard. There is no automatic upgrade — we intentionally require a human decision before increasing your commitment. If you need burst capacity on short notice, contact support via dashboard chat.

CPF and CNPJ validation uses the official Módulo 11 algorithm published by the Receita Federal — the same used by banks and government systems. A 'valid' result means the check digits are correct. It does not mean the document exists in a government database (lookup vs. validation are different concepts).

The API is hosted on Oracle Cloud in Brazil with Cloudflare CDN globally. Requests from Europe, the US, or Asia will typically complete in 100–250ms. There are no geographic restrictions — any IP can call our endpoints.

Yes. The Free plan is designed for small production workloads (startups, side projects, internal tools). There is no time limit. Upgrade whenever your volume exceeds 5,000 req/month.

Yes. All API endpoints are exclusively over HTTPS (TLS 1.2+). HTTP requests are automatically redirected to HTTPS at the Cloudflare layer. Never send your API key over unencrypted connections.

For API Pro and above, we target 99.9% monthly uptime, monitored externally. Incidents are communicated via our status page. For Enterprise plans, uptime commitments are defined in the service agreement.

Yes. A single key can be called from multiple IP addresses simultaneously. Rate limits are applied per key, not per IP. If needed, you can create multiple keys (within your plan limit) and distribute load across them.

Log into your dashboard immediately and revoke the compromised key. Generate a new key. Audit your logs for unexpected usage. The revocation takes effect within seconds — the old key will immediately start returning 401 Unauthorized.

Still have questions?

Our team answers technical questions within 24h on business days. Available in Portuguese and English.

Contact support

Changelog

API version history and upcoming features

v1.0.0 Current version — March 2026 STABLE

What's included

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)

Infrastructure

Rate limiting per API Key with real-time headers
HTTPS-only (TLS 1.2+) via Cloudflare
Response time target: p99 < 300ms
99.9% monthly uptime target (Pro+)
5 languages in code examples
Interactive Try It panels on every endpoint

v1.1.0 Coming next ROADMAP

Batch endpoints — validate up to 100 CPFs/CNPJs in a single request
CNPJ Monitor webhooks — get notified when a company status changes
PDF generation API (via Xeon workers)
Official SDKs for Python, Node.js, and PHP

}

API Documentation

Technical endpoint documentation

Authentication

Rate Limits & Quotas

Error codes

Implementation guides and operational recommendations

Quick Start — Up and running in 5 minutes

Create your account

Generate your API Key

Make your first request

Handle the response

Integration Guides

Automating CNPJ validation in ERP/CRM systems

The problem: manual CNPJ look-ups slow your team down

Recommended architecture

Implementation — Node.js + queue (BullMQ)

Bulk CPF/CNPJ validation with retry logic and rate limit awareness

API Key security: rotation, secrets, and what never to do

Rotation pattern — zero downtime

Monitoring quota usage and building threshold alerts

Best Practices

Cache responses aggressively

Validate before calling the API

Use connection pooling and keep-alive

Deduplicate requests in batch scenarios

Implement circuit breakers for production

Monitor your integration in production

Frequently Asked Questions

Changelog