Guia 7 de 8
Consultas e dados: CNPJ, CEP, validação, boleto e Pix
Endpoints de dados brasileiros para cadastro de clientes, checkout e financeiro. Respondem na hora, em JSON, sem tarefa nem arquivo.
O que você vai construir
Uma função de cadastro de cliente que confere o CNPJ, busca os dados na Receita e preenche razão social e endereço. E exemplos prontos de CEP, validação em lote, boleto e Pix.
Antes de começar
- Uma chave de API em
CONVERTAJA_KEY(veja Primeiros passos).
Quanto custa
| Endpoint | Custo por chamada |
|---|---|
GET /v1/cnpj/{cnpj} | grátis |
GET /v1/cep/{cep} | grátis |
POST /v1/validate | 1 crédito (lote: 1 crédito a cada 50 itens, até 1.000) |
POST /v1/boleto/parse, /v1/pix/brcode, /v1/qrcode, /v1/barcode | 1 crédito |
Só é cobrado o que dá certo: consulta não encontrada, fonte fora do ar ou dado inválido não consomem créditos. Todas contam no limite de requisições por minuto.
Passo 1: Consulte um CNPJ
Dados públicos da Receita Federal (via BrasilAPI), com cache de 24 horas: razão social, situação, endereço, CNAEs e Simples. Aceita o novo CNPJ alfanumérico. O quadro de sócios não é devolvido (LGPD).
# Só os números (ou o CNPJ alfanumérico), sem a barra
curl "https://convertaja.com.br/v1/cnpj/00000000000191" \
-H "Authorization: Bearer $CONVERTAJA_KEY"const cnpj = '00.000.000/0001-91'.replace(/[^0-9A-Za-z]/g, ''); // tira pontos, barra e traço
const res = await fetch(`https://convertaja.com.br/v1/cnpj/${cnpj}`, {
headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
const empresa = await res.json();
if (res.status === 404) console.log('CNPJ não encontrado na Receita (não cobra crédito)');
else if (!res.ok) console.log(`${empresa.error.code}: ${empresa.error.message}`);
else console.log(empresa.razaoSocial, '·', empresa.situacao, '·', empresa.endereco.municipio, '/', empresa.endereco.uf);import os
import re
import requests
cnpj = re.sub(r"[^0-9A-Za-z]", "", "00.000.000/0001-91") # tira pontos, barra e traço
res = requests.get(
f"https://convertaja.com.br/v1/cnpj/{cnpj}",
headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
timeout=30,
)
empresa = res.json()
if res.status_code == 404:
print("CNPJ não encontrado na Receita (não cobra crédito)")
elif not res.ok:
print(f"{empresa['error']['code']}: {empresa['error']['message']}")
else:
print(empresa["razaoSocial"], "·", empresa["situacao"], "·", empresa["endereco"]["municipio"], "/", empresa["endereco"]["uf"])<?php
$cnpj = preg_replace('/[^0-9A-Za-z]/', '', '00.000.000/0001-91'); // tira pontos, barra e traço
$ch = curl_init("https://convertaja.com.br/v1/cnpj/$cnpj");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')],
]);
$empresa = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status === 404) echo "CNPJ não encontrado na Receita (não cobra crédito)\n";
elseif ($status !== 200) echo "{$empresa['error']['code']}: {$empresa['error']['message']}\n";
else echo "{$empresa['razaoSocial']} · {$empresa['situacao']} · {$empresa['endereco']['municipio']}/{$empresa['endereco']['uf']}\n";{
"cnpj": "00000000000191",
"razaoSocial": "BANCO DO BRASIL SA",
"nomeFantasia": "DIRECAO GERAL",
"situacao": "ATIVA",
"dataSituacao": "2005-11-03",
"abertura": "1966-08-01",
"porte": "DEMAIS",
"naturezaJuridica": "Sociedade de Economia Mista",
"cnaePrincipal": {
"codigo": "6422100",
"descricao": "Bancos múltiplos, com carteira comercial"
},
"cnaesSecundarios": [
{
"codigo": "6499999",
"descricao": "Outras atividades de serviços financeiros não especificadas anteriormente"
}
],
"endereco": {
"logradouro": "QUADRA SAUN QUADRA 5 BLOCO B TORRE I, II, III",
"numero": "SN",
"complemento": "ANDAR T I SL S101 A S1602 T II SL C101 A C1602 TIII SL N101 A N1602",
"bairro": "ASA NORTE",
"municipio": "Brasilia",
"uf": "DF",
"cep": "70040912"
},
"telefone": "(61) 3493-9002",
"email": "",
"capitalSocial": 120000000000,
"simples": {
"optante": false,
"mei": false
},
"cached": false
}Dica O CNPJ pode ir com ou sem pontuação, inclusive com a barra: /v1/cnpj/00.000.000/0001-91 e /v1/cnpj/00000000000191 dão o mesmo resultado.
Respostas possíveis: 400 invalid_cnpj (dígito verificador errado), 404 not_found (não existe na Receita) e 502 upstream_unavailable (fonte fora do ar; tente de novo em alguns minutos).
Passo 2: Consulte um CEP
curl "https://convertaja.com.br/v1/cep/01310100" \
-H "Authorization: Bearer $CONVERTAJA_KEY"{
"cep": "01310100",
"logradouro": "Avenida Paulista",
"bairro": "Bela Vista",
"cidade": "São Paulo",
"uf": "SP",
"cached": false
}Fonte: BrasilAPI, com ViaCEP de reserva. O CEP precisa ter 8 números (com ou sem traço); caso contrário, 400 invalid_cep.
Passo 3: Valide documentos, um ou vários
Confere os dígitos verificadores de CPF, CNPJ (inclusive alfanumérico), CNH, PIS/PASEP, título de eleitor, RENAVAM e CNS. Sem type, deduzimos pelo tamanho (e candidates mostra as possibilidades). Ótimo para limpar uma base inteira de cadastro:
# Um documento (o tipo é opcional: sem ele, deduzimos pelo tamanho)
curl -X POST "https://convertaja.com.br/v1/validate" \
-H "Authorization: Bearer $CONVERTAJA_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"cnpj","value":"12.ABC.345/01DE-35"}'
# Vários de uma vez (até 1.000; 1 crédito a cada 50)
curl -X POST "https://convertaja.com.br/v1/validate" \
-H "Authorization: Bearer $CONVERTAJA_KEY" \
-H "Content-Type: application/json" \
-d '{"values":["529.982.247-25","111.111.111-11","11.222.333/0001-81"]}'const documentos = ['529.982.247-25', '111.111.111-11', '11.222.333/0001-81'];
const res = await fetch('https://convertaja.com.br/v1/validate', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ values: documentos }),
});
const { count, valid_count: validos, results } = await res.json();
console.log(`${validos} de ${count} válidos`);
for (const r of results) console.log(r.value, r.type_label, r.valid ? 'ok' : 'INVÁLIDO');import os
import requests
documentos = ["529.982.247-25", "111.111.111-11", "11.222.333/0001-81"]
res = requests.post(
"https://convertaja.com.br/v1/validate",
headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
json={"values": documentos},
timeout=30,
)
lote = res.json()
print(f"{lote['valid_count']} de {lote['count']} válidos")
for r in lote["results"]:
print(r["value"], r["type_label"], "ok" if r["valid"] else "INVÁLIDO")<?php
$documentos = ['529.982.247-25', '111.111.111-11', '11.222.333/0001-81'];
$ch = curl_init('https://convertaja.com.br/v1/validate');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['values' => $documentos]),
]);
$lote = json_decode(curl_exec($ch), true);
echo "{$lote['valid_count']} de {$lote['count']} válidos\n";
foreach ($lote['results'] as $r) {
echo $r['value'] . ' ' . $r['type_label'] . ' ' . ($r['valid'] ? 'ok' : 'INVÁLIDO') . "\n";
}{
"count": 3,
"valid_count": 2,
"results": [
{
"value": "529.982.247-25",
"type": "cpf",
"type_label": "CPF",
"valid": true,
"normalized": "52998224725",
"formatted": "529.982.247-25",
"candidates": [
"cpf",
"cnh",
"pis",
"renavam"
]
},
{
"value": "111.111.111-11",
"type": "cpf",
"type_label": "CPF",
"valid": false,
"normalized": "11111111111",
"formatted": null,
"candidates": [
"cpf",
"cnh",
"pis",
"renavam"
]
},
{
"value": "11.222.333/0001-81",
"type": "cnpj",
"type_label": "CNPJ",
"valid": true,
"normalized": "11222333000181",
"formatted": "11.222.333/0001-81",
"alphanumeric": false
}
]
}A validação confere só a matemática do número; para saber se a empresa existe e está ativa, consulte o CNPJ (passo 1).
Passo 4: Junte tudo num cadastro de cliente
Valida primeiro (rápido, evita consultar número digitado errado), depois busca os dados e recusa empresa que não esteja ativa:
// cadastro.mjs: confere o CNPJ de um novo cliente e preenche o cadastro com os dados da Receita
const BASE = 'https://convertaja.com.br/v1';
const headers = { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}`, 'Content-Type': 'application/json' };
async function cadastrar(cnpjDigitado) {
// 1. Dígitos verificadores (barato e rápido): evita consultar CNPJ digitado errado
const v = await (await fetch(`${BASE}/validate`, { method: 'POST', headers, body: JSON.stringify({ type: 'cnpj', value: cnpjDigitado }) })).json();
if (!v.valid) return { ok: false, motivo: 'CNPJ com dígito verificador errado' };
// 2. Dados públicos da empresa
const res = await fetch(`${BASE}/cnpj/${v.normalized}`, { headers });
const empresa = await res.json();
if (res.status === 404) return { ok: false, motivo: 'CNPJ não encontrado na Receita' };
if (!res.ok) return { ok: false, motivo: empresa.error.message, tentarDeNovo: res.status === 502 || res.status === 429 };
if (empresa.situacao !== 'ATIVA') return { ok: false, motivo: `Situação na Receita: ${empresa.situacao}` };
return {
ok: true,
cliente: {
cnpj: v.formatted, razaoSocial: empresa.razaoSocial, nomeFantasia: empresa.nomeFantasia,
cep: empresa.endereco.cep, cidade: empresa.endereco.municipio, uf: empresa.endereco.uf,
simples: empresa.simples.optante,
},
};
}
console.log(await cadastrar('00.000.000/0001-91'));# cadastro.py: confere o CNPJ de um novo cliente e preenche o cadastro com os dados da Receita
import os
import requests
BASE = "https://convertaja.com.br/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"}
def cadastrar(cnpj_digitado):
# 1. Dígitos verificadores (barato e rápido): evita consultar CNPJ digitado errado
v = requests.post(f"{BASE}/validate", headers=HEADERS, json={"type": "cnpj", "value": cnpj_digitado}, timeout=30).json()
if not v["valid"]:
return {"ok": False, "motivo": "CNPJ com dígito verificador errado"}
# 2. Dados públicos da empresa
res = requests.get(f"{BASE}/cnpj/{v['normalized']}", headers=HEADERS, timeout=30)
empresa = res.json()
if res.status_code == 404:
return {"ok": False, "motivo": "CNPJ não encontrado na Receita"}
if not res.ok:
return {"ok": False, "motivo": empresa["error"]["message"], "tentar_de_novo": res.status_code in (429, 502)}
if empresa["situacao"] != "ATIVA":
return {"ok": False, "motivo": f"Situação na Receita: {empresa['situacao']}"}
return {"ok": True, "cliente": {
"cnpj": v["formatted"], "razao_social": empresa["razaoSocial"], "nome_fantasia": empresa["nomeFantasia"],
"cep": empresa["endereco"]["cep"], "cidade": empresa["endereco"]["municipio"], "uf": empresa["endereco"]["uf"],
"simples": empresa["simples"]["optante"],
}}
print(cadastrar("00.000.000/0001-91"))<?php
// cadastro.php: confere o CNPJ de um novo cliente e preenche o cadastro com os dados da Receita
const BASE = 'https://convertaja.com.br/v1';
function chamar(string $path, ?array $json = null): array {
$ch = curl_init(BASE . $path);
$headers = ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')];
if ($json !== null) {
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($json));
}
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $headers]);
$data = json_decode(curl_exec($ch), true);
return [curl_getinfo($ch, CURLINFO_HTTP_CODE), $data];
}
function cadastrar(string $cnpjDigitado): array {
// 1. Dígitos verificadores (barato e rápido): evita consultar CNPJ digitado errado
[, $v] = chamar('/validate', ['type' => 'cnpj', 'value' => $cnpjDigitado]);
if (empty($v['valid'])) return ['ok' => false, 'motivo' => 'CNPJ com dígito verificador errado'];
// 2. Dados públicos da empresa
[$status, $empresa] = chamar("/cnpj/{$v['normalized']}");
if ($status === 404) return ['ok' => false, 'motivo' => 'CNPJ não encontrado na Receita'];
if ($status !== 200) return ['ok' => false, 'motivo' => $empresa['error']['message'], 'tentar_de_novo' => in_array($status, [429, 502])];
if ($empresa['situacao'] !== 'ATIVA') return ['ok' => false, 'motivo' => "Situação na Receita: {$empresa['situacao']}"];
return ['ok' => true, 'cliente' => [
'cnpj' => $v['formatted'], 'razao_social' => $empresa['razaoSocial'], 'nome_fantasia' => $empresa['nomeFantasia'],
'cep' => $empresa['endereco']['cep'], 'cidade' => $empresa['endereco']['municipio'], 'uf' => $empresa['endereco']['uf'],
'simples' => $empresa['simples']['optante'],
]];
}
print_r(cadastrar('00.000.000/0001-91'));{
ok: true,
cliente: {
cnpj: '00.000.000/0001-91',
razaoSocial: 'BANCO DO BRASIL SA',
nomeFantasia: 'DIRECAO GERAL',
cep: '70040912',
cidade: 'Brasilia',
uf: 'DF',
simples: false
}
}Passo 5: Leia um boleto
Linha digitável (47 posições no bancário, 48 na arrecadação/concessionárias) ou código de barras (44), com ou sem pontuação. Conferimos os dígitos e devolvemos banco, valor e vencimento, já com o novo fator de vencimento (reiniciado em 22/02/2025):
curl -X POST "https://convertaja.com.br/v1/boleto/parse" \
-H "Authorization: Bearer $CONVERTAJA_KEY" \
-H "Content-Type: application/json" \
-d '{"code":"23793.38128 86000.782713 36950.000632 1 10000000012345"}'{
"tipo": "bancario",
"valido": true,
"codigo_barras": "23791100000000123453381286000782713695000063",
"linha_digitavel": "23793381288600078271336950000632110000000012345",
"linha_digitavel_formatada": "23793.38128 86000.782713 36950.000632 1 10000000012345",
"banco": {
"codigo": "237",
"nome": "Bradesco"
},
"moeda": "BRL",
"valor": 123.45,
"fator_vencimento": 1000,
"vencimento": "2025-02-22",
"campo_livre": "3381286000782713695000063"
}Dígito que não confere: 422 invalid_boleto.
Passo 6: Gere um Pix copia e cola com QR Code
BR Code estático no padrão do Banco Central, com o QR Code em SVG e PNG na mesma resposta. Campos: key (CPF, CNPJ, e-mail, telefone +55 ou chave aleatória), name (até 25 caracteres), city (até 15), e opcionais amount (em reais), txid (até 25 letras e números) e description:
curl -X POST "https://convertaja.com.br/v1/pix/brcode" \
-H "Authorization: Bearer $CONVERTAJA_KEY" \
-H "Content-Type: application/json" \
-d '{"key":"contato@minhaloja.com.br","name":"Minha Loja LTDA","city":"SAO PAULO","amount":149.90,"txid":"PEDIDO1234"}'import { writeFile } from 'node:fs/promises';
const res = await fetch('https://convertaja.com.br/v1/pix/brcode', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ key: 'contato@minhaloja.com.br', name: 'Minha Loja LTDA', city: 'SAO PAULO', amount: 149.9, txid: 'PEDIDO1234' }),
});
const pix = await res.json();
if (!res.ok) throw new Error(`${pix.error.code}: ${pix.error.message}`);
console.log('Copia e cola:', pix.payload);
await writeFile('pix-pedido-1234.png', Buffer.from(pix.qr_png_base64, 'base64')); // ou use pix.qr_svg direto no HTMLimport base64
import os
import requests
res = requests.post(
"https://convertaja.com.br/v1/pix/brcode",
headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
json={"key": "contato@minhaloja.com.br", "name": "Minha Loja LTDA", "city": "SAO PAULO", "amount": 149.90, "txid": "PEDIDO1234"},
timeout=30,
)
pix = res.json()
if not res.ok:
raise SystemExit(f"{pix['error']['code']}: {pix['error']['message']}")
print("Copia e cola:", pix["payload"])
with open("pix-pedido-1234.png", "wb") as f: # ou use pix["qr_svg"] direto no HTML
f.write(base64.b64decode(pix["qr_png_base64"]))<?php
$ch = curl_init('https://convertaja.com.br/v1/pix/brcode');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'key' => 'contato@minhaloja.com.br', 'name' => 'Minha Loja LTDA', 'city' => 'SAO PAULO',
'amount' => 149.90, 'txid' => 'PEDIDO1234',
]),
]);
$pix = json_decode(curl_exec($ch), true);
echo "Copia e cola: {$pix['payload']}\n";
file_put_contents('pix-pedido-1234.png', base64_decode($pix['qr_png_base64'])); // ou use $pix['qr_svg'] no HTML{
"payload": "00020126460014br.gov.bcb.pix0124contato@minhaloja.com.br5204000053039865406149.905802BR5915Minha Loja LTDA6009SAO PAULO62140510PEDIDO123463041DBC",
"key": "contato@minhaloja.com.br",
"key_type": "email",
"amount": 149.9,
"txid": "PEDIDO1234",
"qr_svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"456\" height=\"456\" …</svg>",
"qr_png_base64": "iVBORw0KGgoAAAANSUhEUgAAAcgAAAHI…"
}Dica É um Pix estático: serve para cobrar, mas a confirmação do pagamento vem do seu banco ou PSP. Use o txid para conciliar.
QR Code e código de barras
POST /v1/qrcode recebe text (até 2.900 caracteres) e opções de cor, margem e correção de erros. POST /v1/barcode recebe type e value; EAN/UPC sem o último dígito recebem o dígito calculado. Os dois devolvem svg e/ou png_base64 conforme format (svg, png ou both). Exemplo completo no guia Etiquetas para e-commerce.
Próximos passos
8
Boas práticas: reenvios, limites, segurança e custosO que separa um teste que funciona de uma integração que roda meses sem surpresa: repetir só o que pode ser repetido, respeitar os limites, proteger a chave e saber quanto cada chamada custa.
10 min · Intermediário · Produção · Limites · Segurança
1
Primeiros passos com a API do ConvertajáEm 5 minutos você cria a chave, faz a primeira chamada e sabe ler o saldo de créditos e os limites do seu plano.
5 min · Iniciante · Chave · Autenticação · Créditos
5
Etiquetas para e-commerce: expedição automatizadaEtiquetas de marketplace vêm em folha A4, duas ou quatro por página. Com a API, a expedição recebe um PDF só, já no tamanho da impressora térmica, junto com os DANFEs simplificados.
12 min · Intermediário · Etiquetas · 10×15 · Expedição
Todos os endpoints e opções: referência da API. Dúvidas? Fale com a gente e informe o X-Request-Id da chamada.