convertajá

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.

5 min · Iniciante · atualizado em 16/10/2026

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+ com requests, 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"
Resposta 200
{
  "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_bytes e limits.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-Remaining e X-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"
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çãoCréditos
Ferramenta leve (unir, dividir, comprimir, DANFE, recortar etiqueta, imagens…), por arquivo1
Ferramenta pesada (OCR, Word/Excel/PowerPoint, PDF/A, HTML para PDF…), por arquivo de até 10 páginas5 + 1 a cada 10 páginas a mais
Vídeo (converter, comprimir, GIF), por arquivo10
Consulta de CNPJ ou CEPgrátis
Validação de documentos (lote: a cada 50 itens), boleto, Pix, QR Code, código de barras1
Assinatura eletrônica, por envelope enviado20
Tarefa que termina com erro0 (estorno)
PlanoPreço/mêsCréditos/mêsReq./minArquivoArquivos/tarefaPesadas simultâneas
Sandboxgrátis5001050 MB103
MiniR$ 29,001.00030200 MB202
StartR$ 49,002.00060500 MB503
GrowthR$ 149,008.0001202 GB20010
ScaleR$ 449,0030.0003002 GB20010

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:

401: chave não enviada
{
  "error": {
    "code": "missing_api_key",
    "message": "Envie sua chave no cabeçalho Authorization: Bearer cj_live_… (ou X-API-Key).",
    "request_id": "req_UkbrW3QRi59d"
  }
}
HTTPcodeO que fazer
401missing_api_keyEnvie Authorization: Bearer $CONVERTAJA_KEY. Confira se a variável de ambiente está definida no mesmo terminal.
401invalid_api_keyChave digitada errada ou incompleta. Copie de novo (ou crie outra).
401revoked_api_keyA chave foi revogada em /conta/api. Crie outra.
403account_not_eligibleConfirme a idade na sua conta.
429rate_limitedPassou do limite por minuto. Espere os segundos de Retry-After.
429test_limitA chave de teste já fez 20 chamadas hoje. Use uma cj_live_ ou espere o dia seguinte.
429: limite por minuto (com Retry-After: 23)
{
  "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.