Guia 1 de 8
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.
O que você vai construir
Uma chamada autenticada para GET /v1/me, que mostra sua conta, o plano, o saldo de créditos e os limites, e a lista de ferramentas disponíveis.
Antes de começar
- Uma conta no Convertajá com a idade confirmada (18+). Sem isso a API responde
403 account_not_eligible. - Um terminal com
curl, ou Node.js 18+, Python 3.8+ comrequests, ou PHP 7.4+ com a extensão curl.
Passo 1: Crie a chave em Minha conta → API
Entre na sua conta e abra Minha conta → API. Em Chaves de API, dê um nome que diga onde ela vai ser usada (ex.: “ERP produção”) e escolha o tipo:
- Produção (
cj_live_…): consome créditos do plano. - Teste (
cj_test_…): não consome créditos, faz até 20 chamadas por dia e devolve resultados reais. Boa para desenvolver.
Clique em Criar chave e copie na hora: por segurança ela aparece uma única vez (guardamos só um hash). Você recebe um e-mail a cada chave criada. Se perder a chave, revogue e crie outra.
Passo 2: Guarde a chave numa variável de ambiente
Todos os exemplos dos guias leem a chave de CONVERTAJA_KEY. Assim ela não vai parar no código nem no Git:
# macOS e Linux (vale para a sessão atual do terminal)
export CONVERTAJA_KEY="cj_live_cole_sua_chave_aqui"
# Windows (PowerShell)
$env:CONVERTAJA_KEY = "cj_live_cole_sua_chave_aqui"
Atenção A chave é secreta e serve só para chamadas do seu servidor. Nunca coloque em página web, app ou repositório: a API não aceita chamadas do navegador (não há CORS) e quem tiver a chave gasta seus créditos.
Passo 3: Faça a primeira chamada: GET /v1/me
Envie a chave no cabeçalho Authorization: Bearer … (também vale X-API-Key: …). /v1/me não consome créditos:
curl "https://convertaja.com.br/v1/me" \
-H "Authorization: Bearer $CONVERTAJA_KEY"// primeira-chamada.mjs (Node.js 18 ou mais novo): node primeira-chamada.mjs
const res = await fetch('https://convertaja.com.br/v1/me', {
headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
const me = await res.json();
if (!res.ok) throw new Error(`${me.error.code}: ${me.error.message}`);
console.log(`Plano ${me.plan.label}: ${me.credits.remaining} créditos disponíveis`);
console.log(`Limite: ${res.headers.get('x-ratelimit-limit')} requisições por minuto`);# primeira_chamada.py (pip install requests): python primeira_chamada.py
import os
import requests
res = requests.get(
"https://convertaja.com.br/v1/me",
headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
timeout=30,
)
me = res.json()
if not res.ok:
raise SystemExit(f"{me['error']['code']}: {me['error']['message']}")
print(f"Plano {me['plan']['label']}: {me['credits']['remaining']} créditos disponíveis")
print(f"Limite: {res.headers['X-RateLimit-Limit']} requisições por minuto")<?php
// primeira-chamada.php (PHP 7.4 ou mais novo, com a extensão curl): php primeira-chamada.php
$ch = curl_init('https://convertaja.com.br/v1/me');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')],
]);
$me = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status !== 200) {
exit($me['error']['code'] . ': ' . $me['error']['message'] . PHP_EOL);
}
echo "Plano {$me['plan']['label']}: {$me['credits']['remaining']} créditos disponíveis\n";
{
"account": {
"id": 2,
"email": "voce@suaempresa.com.br",
"name": "Sua Empresa LTDA"
},
"key": {
"id": 2,
"name": "ERP",
"mode": "live",
"prefix": "cj_live_a1B2c3D4"
},
"plan": {
"id": "start",
"label": "Start",
"period": "monthly",
"status": "active",
"renews_at": "2026-11-15T20:23:59.240Z",
"bundle": null
},
"credits": {
"allowance": 2000,
"used": 88,
"allowance_remaining": 1912,
"packs": [],
"packs_remaining": 0,
"remaining": 1912,
"cycle": {
"start": "2026-10-16T20:23:59.240Z",
"end": "2026-11-15T20:23:59.240Z"
}
},
"limits": {
"requests_per_minute": 60,
"max_file_bytes": 524288000,
"max_files_per_job": 50,
"max_active_keys": 5,
"heavy_jobs_concurrency": 3
}
}O que importa aqui:
credits.remaining: quanto você ainda pode gastar (franquia do ciclo + pacotes avulsos).credits.cycle.endé quando a franquia renova.limits.requests_per_minute: chamadas por minuto, por chave.limits.max_file_byteselimits.max_files_per_job: tamanho máximo de cada arquivo e quantos arquivos cabem numa tarefa.limits.heavy_jobs_concurrency: quantas tarefas pesadas (OCR, Office, vídeo…) podem rodar ao mesmo tempo.
Passo 4: Leia os cabeçalhos de toda resposta
Toda resposta autenticada traz o saldo e o limite por minuto, sem precisar chamar /v1/me de novo:
# -i mostra os cabeçalhos da resposta
curl -i "https://convertaja.com.br/v1/me" \
-H "Authorization: Bearer $CONVERTAJA_KEY"
HTTP/1.1 200 OK
X-Request-Id: req_Ta9td9ulmuhn
Cache-Control: no-store
X-Credits-Remaining: 1912
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 53
X-RateLimit-Reset: 1792183001
Content-Type: application/json; charset=utf-8
X-Request-Id: informe ao suporte se algo der errado.X-Credits-Remaining: saldo depois desta chamada.X-RateLimit-RemainingeX-RateLimit-Reset(horário Unix, em segundos): quantas chamadas ainda cabem na janela de 60 s e quando ela libera.- Com chave de teste, vem também
X-Convertaja-Mode: test.
Passo 5: Veja as ferramentas disponíveis
GET /v1/tools lista todas as ferramentas de arquivo, com as extensões aceitas, as opções (em JSON Schema) e o custo por arquivo. Também é grátis:
curl "https://convertaja.com.br/v1/tools" \
-H "Authorization: Bearer $CONVERTAJA_KEY"const res = await fetch('https://convertaja.com.br/v1/tools', {
headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
const { count, data } = await res.json();
console.log(`${count} ferramentas`);
for (const t of data) console.log(`${t.id} — ${t.credits_per_file} crédito(s) por arquivo`);import os
import requests
res = requests.get(
"https://convertaja.com.br/v1/tools",
headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
timeout=30,
)
lista = res.json()
print(lista["count"], "ferramentas")
for t in lista["data"]:
print(f"{t['id']} — {t['credits_per_file']} crédito(s) por arquivo")<?php
$ch = curl_init('https://convertaja.com.br/v1/tools');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')],
]);
$lista = json_decode(curl_exec($ch), true);
echo "{$lista['count']} ferramentas\n";
foreach ($lista['data'] as $t) {
echo "{$t['id']} — {$t['credits_per_file']} crédito(s) por arquivo\n";
}
unir-pdf — 1 crédito(s) por arquivo
comprimir-pdf — 1 crédito(s) por arquivo
comprimir-pdf-tamanho — 5 crédito(s) por arquivo
dividir-pdf — 1 crédito(s) por arquivo
…
A referência de cada uma, com todas as opções, está em /api/docs.
Créditos e limites de cada plano
Cada operação custa créditos. A franquia mensal do plano é usada primeiro; depois, os pacotes avulsos (que valem 12 meses). Tarefas que terminam com erro devolvem os créditos automaticamente.
| Operação | Créditos |
|---|---|
| Ferramenta leve (unir, dividir, comprimir, DANFE, recortar etiqueta, imagens…), por arquivo | 1 |
| Ferramenta pesada (OCR, Word/Excel/PowerPoint, PDF/A, HTML para PDF…), por arquivo de até 10 páginas | 5 + 1 a cada 10 páginas a mais |
| Vídeo (converter, comprimir, GIF), por arquivo | 10 |
| Consulta de CNPJ ou CEP | grátis |
| Validação de documentos (lote: a cada 50 itens), boleto, Pix, QR Code, código de barras | 1 |
| Assinatura eletrônica, por envelope enviado | 20 |
| Tarefa que termina com erro | 0 (estorno) |
| Plano | Preço/mês | Créditos/mês | Req./min | Arquivo | Arquivos/tarefa | Pesadas simultâneas |
|---|---|---|---|---|---|---|
| Sandbox | grátis | 500 | 10 | 50 MB | 10 | 3 |
| Mini | R$ 29,00 | 1.000 | 30 | 200 MB | 20 | 2 |
| Start | R$ 49,00 | 2.000 | 60 | 500 MB | 50 | 3 |
| Growth | R$ 149,00 | 8.000 | 120 | 2 GB | 200 | 10 |
| Scale | R$ 449,00 | 30.000 | 300 | 2 GB | 200 | 10 |
Preços e pacotes atualizados em /api#precos. Para saber o seu saldo exato, use /v1/me ou o cabeçalho X-Credits-Remaining.
Erros comuns ao começar
Todo erro tem o mesmo formato, com um code estável para você tratar no código e uma mensagem em português:
{
"error": {
"code": "missing_api_key",
"message": "Envie sua chave no cabeçalho Authorization: Bearer cj_live_… (ou X-API-Key).",
"request_id": "req_UkbrW3QRi59d"
}
}| HTTP | code | O que fazer |
|---|---|---|
| 401 | missing_api_key | Envie Authorization: Bearer $CONVERTAJA_KEY. Confira se a variável de ambiente está definida no mesmo terminal. |
| 401 | invalid_api_key | Chave digitada errada ou incompleta. Copie de novo (ou crie outra). |
| 401 | revoked_api_key | A chave foi revogada em /conta/api. Crie outra. |
| 403 | account_not_eligible | Confirme a idade na sua conta. |
| 429 | rate_limited | Passou do limite por minuto. Espere os segundos de Retry-After. |
| 429 | test_limit | A chave de teste já fez 20 chamadas hoje. Use uma cj_live_ ou espere o dia seguinte. |
{
"error": {
"code": "rate_limited",
"message": "Limite de 10 requisições por minuto do plano Sandbox. Aguarde alguns segundos.",
"request_id": "req_UkbrW3QRi59d"
}
}Próximos passos
Todos os endpoints e opções: referência da API. Dúvidas? Fale com a gente e informe o X-Request-Id da chamada.