Documentação da API

Introdução

A API do Convertajá é REST, recebe e devolve JSON (UTF-8) e fica em https://convertaja.com.br/v1. Ela usa o mesmo motor do site: as 53 ferramentas de arquivo (PDF, imagem, áudio, vídeo, notas fiscais, etiquetas) e endpoints de dados brasileiros.

Entre na sua conta e crie uma chave em Minha conta → API.
Envie o arquivo para POST /v1/tools/{id}.
Receba a tarefa (202), consulte GET /v1/jobs/{id} ou use ?wait=true e baixe o resultado.

curl -X POST "https://convertaja.com.br/v1/tools/unir-pdf?wait=true" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -F "files=@arquivo1.pdf" \
  -F "files=@arquivo2.pdf" \
  -F 'options={}'

import { openAsBlob } from 'node:fs';

const form = new FormData();
form.append('files', await openAsBlob('arquivo1.pdf'), 'arquivo1.pdf');
form.append('files', await openAsBlob('arquivo2.pdf'), 'arquivo2.pdf');
form.append('options', JSON.stringify({}));

const res = await fetch('https://convertaja.com.br/v1/tools/unir-pdf?wait=true', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
  body: form,
});
const job = await res.json();
console.log(job.status, job.outputs);

import json, os, requests

res = requests.post(
    "https://convertaja.com.br/v1/tools/unir-pdf",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
    files=[("files", open("arquivo1.pdf", "rb")), ("files", open("arquivo2.pdf", "rb"))],
    data={"options": json.dumps({})},
)
job = res.json()
print(job["status"], job.get("outputs"))

<?php
$ch = curl_init('https://convertaja.com.br/v1/tools/unir-pdf?wait=true');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')],
  CURLOPT_POSTFIELDS => [
    'files[0]' => new CURLFile('arquivo1.pdf'),
    'files[1]' => new CURLFile('arquivo2.pdf'),
    'options' => json_encode([]),
  ],
]);
$job = json_decode(curl_exec($ch), true);
echo $job['status'];

Autenticação

Envie a chave em todas as chamadas, no cabeçalho Authorization: Bearer cj_live_… (ou X-API-Key: cj_live_…). A chave é mostrada uma única vez quando é criada; guardamos só um hash (SHA-256) e o prefixo. Revogue uma chave vazada na hora em /conta/api.

Toda resposta traz X-Request-Id. Informe esse código ao suporte se precisar de ajuda.

Créditos e preços

O que você faz	Créditos
Ferramenta leve (unir, dividir, girar, comprimir, numerar, proteger, imagens, DANFE…) — por arquivo	1
Ferramenta pesada (OCR, PDF para Word/Excel, Word para PDF, PDF/A, mala direta…) — por arquivo	5
Vídeo (converter, comprimir, vídeo para GIF) — por arquivo	10
CNPJ, CEP, boleto, Pix, QR Code, código de barras — por chamada	1
Validação de documentos — por chamada (lote: a cada 50 itens)	1
Assinatura eletrônica — por envelope enviado (até 10 signatários; rascunho, consulta, lembrete e downloads são grátis)	20
Tarefa que termina com erro	0 (estorno automático)

Os créditos de uma tarefa são debitados quando ela é aceita (resposta 202) e estornados automaticamente se ela terminar com erro. Chamadas de dados são cobradas só quando respondem com sucesso. Ordem de consumo: franquia mensal do plano (incluindo os créditos do Pro/Empresas) e depois os pacotes avulsos, do que vence primeiro. Sem saldo, a API responde 402 insufficient_credits. O saldo vem em X-Credits-Remaining.

Plano	Preço/mês	Créditos/mês	Req./min	Arquivo	Arquivos/tarefa	Chaves	Pesadas simultâneas
Sandbox	grátis	100	10	50 MB	10	2	3
Start	R$ 49,00	2.000	60	500 MB	50	5	3
Growth	R$ 149,00	8.000	120	2 GB	200	10	10
Scale	R$ 449,00	30.000	300	2 GB	200	25	10

Anual = 10× o mensal. Pacotes avulsos: 1.000 por R$ 35,00 · 5.000 por R$ 150,00 · 20.000 por R$ 500,00 (valem 12 meses). Pro inclui 300 créditos/mês e Empresas 1.000. A franquia renova no ciclo do plano da API (a cada 30 dias) ou, no grátis e nos créditos inclusos, no início de cada mês.

Limites

Cada chave tem uma janela deslizante de 60 segundos com o limite do plano. Os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (Unix, em segundos) vêm em toda resposta; acima do limite, 429 rate_limited com Retry-After. Ferramentas pesadas e de vídeo têm limite de tarefas simultâneas por conta (429 concurrency_limit).

Tamanho por arquivo e arquivos por tarefa seguem o plano. Corpo JSON com base64: até 60 MB (use multipart ou URL para arquivos maiores). ?wait espera até 60 s. Os arquivos ficam disponíveis por 1 hora e depois são apagados.

Erros

Erros sempre têm o formato abaixo, com status HTTP adequado e code estável:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Créditos insuficientes: esta chamada custa 5 e você tem 2. …",
    "request_id": "req_x1Y2z3"
  }
}

HTTP	code	Quando
400	`invalid_request`	Parâmetros ausentes ou inválidos.
400	`invalid_json`	O corpo não é um JSON válido.
400	`invalid_option`	Opção desconhecida ou com valor inválido para a ferramenta.
400	`missing_option`	Falta uma opção obrigatória.
400	`missing_files`	Nenhum arquivo enviado.
400	`too_few_files / too_many_files`	Quantidade de arquivos fora do permitido pela ferramenta ou pelo plano.
400	`missing_file`	Falta o arquivo extra (papel timbrado, logo).
400	`invalid_webhook_url`	webhook_url não é HTTPS ou aponta para rede interna.
400	`invalid_cnpj / invalid_cep`	Documento com formato ou dígito verificador inválido.
400	`declaration_required`	Desbloquear PDF exige authorized: true.
401	`missing_api_key`	Chave não enviada.
401	`invalid_api_key`	Chave inexistente.
401	`revoked_api_key`	Chave revogada.
402	`insufficient_credits`	Créditos insuficientes para a chamada.
402	`esign_quota`	Cota mensal de documentos para assinatura do plano esgotada (Grátis 3, Pro 30, Empresas 200).
403	`account_not_eligible`	A conta ainda não confirmou a maioridade.
404	`not_found / tool_not_found / job_not_found / file_not_found`	Recurso inexistente, expirado ou de outra conta.
404	`envelope_not_found`	Envelope inexistente, excluído ou de outra conta.
409	`job_not_ready`	A tarefa ainda não terminou.
409	`invalid_state`	Ação incompatível com a situação do envelope (ex.: enviar de novo, cancelar um assinado).
409	`envelope_not_completed`	Os PDFs final e de relatório só existem depois que todos assinam.
410	`envelope_gone`	O arquivo do rascunho não está mais disponível.
413	`file_too_large / payload_too_large`	Arquivo acima do limite do plano ou corpo JSON grande demais.
415	`unsupported_file_type / unsupported_media_type`	Extensão não aceita pela ferramenta, ou corpo que não é JSON.
422	`invalid_boleto`	Dígito verificador do boleto não confere.
422	`invalid_value`	Valor impossível de codificar no tipo de código de barras.
422	`invalid_pdf`	Arquivo que não é PDF, corrompido, protegido por senha ou com mais de 100 páginas.
422	`forbidden_url`	URL de arquivo aponta para rede interna/privada (bloqueado).
429	`rate_limited`	Limite de requisições por minuto do plano.
429	`concurrency_limit`	Tarefas pesadas simultâneas acima do limite do plano.
429	`reminder_too_soon`	Lembrete repetido em menos de 30 minutos.
429	`test_limit`	Chave de teste passou de 20 chamadas no dia.
500	`internal_error`	Erro inesperado (tente de novo).
502	`upstream_unavailable`	A fonte pública (Receita/CEP) não respondeu; nada é cobrado.

Ferramentas de arquivo

Lista completa com opções (JSON Schema) em GET /v1/tools. Envie os arquivos de três formas:

multipart/form-data: campo files (um ou vários), arquivos extras (letterhead, logo) e as opções em options (JSON) ou como campos soltos;
JSON com URL: {"files":[{"url":"https://…/a.pdf"}],"options":{…}} — baixamos com limite de tamanho e tempo, só de endereços públicos;
JSON com base64: {"files":[{"base64":"JVBERi0…","name":"a.pdf"}]}.

id	Ferramenta	Extensões	Créditos/arquivo
PDF
`unir-pdf`	Unir PDF	pdf, jpg, jpeg, png, webp, gif…	1
`comprimir-pdf`	Comprimir PDF	pdf	1
`comprimir-pdf-tamanho`	Comprimir PDF para tamanho exato	pdf	5
`dividir-pdf`	Dividir PDF	pdf	1
`extrair-paginas`	Extrair páginas	pdf	1
`remover-paginas`	Remover páginas	pdf	1
`girar-pdf`	Girar PDF	pdf	1
`numerar-paginas`	Numerar páginas	pdf	1
`marca-dagua`	Marca d'água	pdf	1
`recortar-pdf`	Recortar PDF	pdf	1
`proteger-pdf`	Proteger PDF	pdf	1
`desbloquear-pdf`	Desbloquear PDF	pdf	1
`ocultar-dados`	Ocultar dados	pdf	1
`anonimizar-documento`	Anonimizar documento (LGPD)	pdf	1
`comparar-pdf`	Comparar PDF	pdf	5
`ocr-pdf`	OCR em PDF	pdf	5
`reparar-pdf`	Reparar PDF	pdf	1
`achatar-pdf`	Achatar PDF	pdf	1
`extrair-imagens`	Extrair imagens do PDF	pdf	1
Converter PDF
`word-para-pdf`	Word para PDF	doc, docx, odt, rtf, txt, pages…	5
`pdf-para-word`	PDF para Word	pdf	5
`excel-para-pdf`	Excel para PDF	xls, xlsx, ods, csv, numbers	5
`pdf-para-excel`	PDF para Excel	pdf	5
`powerpoint-para-pdf`	PowerPoint para PDF	ppt, pptx, odp, pps, ppsx, key	5
`pdf-para-powerpoint`	PDF para PowerPoint	pdf	5
`html-para-pdf`	Site para PDF	html, htm	5
`qualquer-para-pdf`	Qualquer arquivo para PDF	doc, docx, odt, rtf, txt, pages…	5
`pdf-para-texto`	PDF para texto	pdf	1
`pdf-para-pdfa`	PDF para PDF/A	pdf	5
`eps-para-pdf`	EPS para PDF	eps, ps	5
`converter-documento`	Converter documento	doc, docx, odt, rtf, txt, pages…	5
`jpg-para-pdf`	Imagens para PDF	jpg, jpeg, png, webp, gif, tif…	1
Escritório e negócios
`papel-timbrado`	Aplicar papel timbrado	pdf	1
`xml-nfe-para-pdf`	XML da NF-e para PDF (DANFE)	xml, zip	1
`nfe-para-excel`	Notas fiscais (XML) para Excel	xml, zip	1
`mala-direta-word`	Mala direta com modelo do Word	docx, xlsx, xls, csv, ods	5
`ofx-para-excel`	Extrato OFX para Excel	ofx, qfx, ofc	1
Etiquetas e envios
`recortar-etiqueta`	Recortar etiqueta de envio (10×15)	pdf	1
Imagem
`converter-imagem`	Converter imagem	jpg, jpeg, png, webp, gif, tif…	1
`png-para-jpg`	PNG para JPG	jpg, jpeg, png, webp, gif, tif…	1
`jpg-para-png`	JPG para PNG	jpg, jpeg, png, webp, gif, tif…	1
`imagem-para-webp`	Imagem para WEBP	jpg, jpeg, png, webp, gif, tif…	1
`redimensionar-imagem`	Redimensionar imagem	jpg, jpeg, png, webp, gif, tif…	1
`marca-dagua-imagem`	Marca d'água em fotos	jpg, jpeg, png, webp, gif, tif…	1
`imagem-redes-sociais`	Imagem para redes sociais e marketplace	jpg, jpeg, png, webp, gif, tif…	1
`comprimir-imagem`	Comprimir imagem	jpg, jpeg, png, webp, gif, tif…	1
Áudio
`mp4-para-mp3`	MP4 para MP3	mp3, wav, ogg, oga, m4a, flac…	1
`converter-audio`	Converter áudio	mp3, wav, ogg, oga, m4a, flac…	1
`cortar-audio`	Cortar áudio	mp3, wav, ogg, oga, m4a, flac…	1
Vídeo
`converter-video`	Converter vídeo	mp4, mkv, mov, avi, wmv, flv…	10
`comprimir-video`	Comprimir vídeo	mp4, mkv, mov, avi, wmv, flv…	10
`video-para-gif`	Vídeo para GIF	mp4, mkv, mov, avi, wmv, flv…	10
`cortar-video`	Cortar vídeo	mp4, mkv, mov, avi, wmv, flv…	1

GET `/v1/tools`

Listar ferramentas. Todas as ferramentas de arquivo com extensões aceitas, opções em JSON Schema e custo em créditos.

Custo: grátis (não consome créditos)

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}` },
});
console.log(await res.json());

import os, requests

res = requests.get("https://convertaja.com.br/v1/tools", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/tools');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

GET `/v1/tools/{toolId}`

Detalhes de uma ferramenta. Uma ferramenta, com o JSON Schema das opções.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`toolId`	caminho	Id da ferramenta (ex.: unir-pdf).

curl "https://convertaja.com.br/v1/tools/{toolId}" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

const res = await fetch('https://convertaja.com.br/v1/tools/{toolId}', {
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.get("https://convertaja.com.br/v1/tools/{toolId}", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/tools/{toolId}');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

POST `/v1/tools/{toolId}`

Criar tarefa. Envia os arquivos e cria a tarefa. Responde 202 com a tarefa; use ?wait=true para esperar até 60 s pelo resultado.

Custo: 1, 5 ou 10 por arquivo crédito(s)

Parâmetro	Onde	Descrição
`toolId`	caminho	Id da ferramenta.
`wait`	query	true (até 60 s) ou número de segundos (1–60).
`webhook_url`	query	URL HTTPS que recebe o aviso de conclusão.

Tarefas e downloads

Status: running → done ou error. Exemplo de tarefa concluída:

{
  "id": "V1StGXR8_Z5j",
  "tool": "comprimir-pdf",
  "operation": "pdf-compress",
  "status": "done",
  "progress": 100,
  "message": "Pronto!",
  "created_at": "2026-10-15T13:00:00.000Z",
  "finished_at": "2026-10-15T13:00:02.000Z",
  "expires_at": "2026-10-15T14:00:00.000Z",
  "credits_charged": 1,
  "credits_refunded": 0,
  "test": false,
  "outputs": [
    {
      "index": 0,
      "name": "contrato - comprimido.pdf",
      "size": 182344,
      "url": "https://convertaja.com.br/v1/jobs/V1StGXR8_Z5j/files/0"
    }
  ],
  "download_url": "https://convertaja.com.br/v1/jobs/V1StGXR8_Z5j/download",
  "info": "2,1 MB → 180 KB (-91%)"
}

GET `/v1/jobs/{id}`

Consultar tarefa. Situação, progresso e arquivos gerados. Só a conta que criou a tarefa consegue consultar.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id`	caminho	Id da tarefa.

curl "https://convertaja.com.br/v1/jobs/{id}" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

const res = await fetch('https://convertaja.com.br/v1/jobs/{id}', {
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.get("https://convertaja.com.br/v1/jobs/{id}", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/jobs/{id}');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

GET `/v1/jobs/{id}/files/{index}`

Baixar um arquivo. Baixa o arquivo gerado na posição index.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id`	caminho	Id da tarefa.
`index`	caminho	Posição do arquivo (0, 1, …).

GET `/v1/jobs/{id}/download`

Baixar tudo. Baixa o arquivo gerado ou, se houver vários, um ZIP com todos.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id`	caminho	Id da tarefa.

Só a conta dona da chave que criou a tarefa consegue consultá-la ou baixar os arquivos (outras contas recebem 404).

Webhooks

Envie webhook_url (HTTPS, endereço público) ao criar a tarefa. Quando ela terminar, fazemos um POST com JSON:

{
  "id": "evt_9f8e7d…",
  "type": "job.completed",
  "created_at": "2026-10-15T13:00:02.000Z",
  "data": {
    "id": "V1StGXR8_Z5j",
    "tool": "comprimir-pdf",
    "operation": "pdf-compress",
    "status": "done",
    "progress": 100,
    "message": "Pronto!",
    "created_at": "2026-10-15T13:00:00.000Z",
    "finished_at": "2026-10-15T13:00:02.000Z",
    "expires_at": "2026-10-15T14:00:00.000Z",
    "credits_charged": 1,
    "credits_refunded": 0,
    "test": false,
    "outputs": [
      {
        "index": 0,
        "name": "contrato - comprimido.pdf",
        "size": 182344,
        "url": "https://convertaja.com.br/v1/jobs/V1StGXR8_Z5j/files/0"
      }
    ],
    "download_url": "https://convertaja.com.br/v1/jobs/V1StGXR8_Z5j/download",
    "info": "2,1 MB → 180 KB (-91%)"
  }
}

Eventos: job.completed e job.failed (tarefas) e esign.envelope.completed, esign.envelope.refused, esign.envelope.expired e esign.envelope.canceled (assinatura eletrônica). Responda com status 2xx em até 10 s. Se falhar, tentamos de novo até 3 vezes no total (esperas de 5 s e 30 s). Cabeçalhos: X-Convertaja-Event, X-Convertaja-Delivery (id do evento, para descartar repetidos), X-Convertaja-Attempt e a assinatura:

X-Convertaja-Signature: t=1760533202,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

v1 é o HMAC-SHA256 (hex) de "{t}.{corpo cru}" com o segredo de webhook da conta (em /conta/api, onde também dá para trocá-lo). Confira a assinatura e rejeite eventos com mais de 5 minutos:

# Use um dos exemplos em Node.js, Python ou PHP.

import crypto from 'node:crypto';

// Use o corpo cru (raw), antes de qualquer JSON.parse
function assinaturaValida(rawBody, header, segredo) {
  const partes = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(partes.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // 5 minutos
  const esperado = crypto.createHmac('sha256', segredo).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(esperado), b = Buffer.from(partes.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: app.post('/webhooks/convertaja', express.raw({ type: 'application/json' }), (req, res) => {
//   if (!assinaturaValida(req.body.toString(), req.get('X-Convertaja-Signature'), process.env.CONVERTAJA_WEBHOOK_SECRET)) return res.sendStatus(400);
//   const evento = JSON.parse(req.body); // evento.type: job.completed | job.failed
//   res.sendStatus(200);
// });

import hashlib, hmac, time

def assinatura_valida(raw_body: bytes, header: str, segredo: str) -> bool:
    partes = dict(p.split("=", 1) for p in header.split(","))
    t = int(partes.get("t", "0"))
    if not t or abs(time.time() - t) > 300:
        return False
    esperado = hmac.new(segredo.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, partes.get("v1", ""))

# Flask:
# @app.post("/webhooks/convertaja")
# def webhook():
#     if not assinatura_valida(request.get_data(), request.headers["X-Convertaja-Signature"], os.environ["CONVERTAJA_WEBHOOK_SECRET"]):
#         abort(400)
#     evento = request.get_json()  # evento["type"]: job.completed | job.failed
#     return "", 200

<?php
function assinatura_valida(string $rawBody, string $header, string $segredo): bool {
  parse_str(str_replace(',', '&', $header), $p);
  $t = (int)($p['t'] ?? 0);
  if (!$t || abs(time() - $t) > 300) return false;
  $esperado = hash_hmac('sha256', $t . '.' . $rawBody, $segredo);
  return hash_equals($esperado, $p['v1'] ?? '');
}

$raw = file_get_contents('php://input');
if (!assinatura_valida($raw, $_SERVER['HTTP_X_CONVERTAJA_SIGNATURE'] ?? '', getenv('CONVERTAJA_WEBHOOK_SECRET'))) {
  http_response_code(400); exit;
}
$evento = json_decode($raw, true); // $evento['type']: job.completed | job.failed
http_response_code(200);

Assinatura eletrônica

Envie PDFs para outras pessoas assinarem, no mesmo fluxo de /assinatura-eletronica: cada signatário recebe um link pessoal por e-mail, confirma um código de 6 dígitos enviado ao e-mail (e o CPF, se você pedir), desenha ou digita a assinatura e aceita os termos. Quando todos assinam, geramos o PDF final com as assinaturas aplicadas e o relatório de assinaturas (IP/porta, dispositivo, horários, hash SHA-256 do original e do final, QR Code de verificação em /verificar/{id}).

Base legal: assinatura eletrônica nos termos da MP 2.200-2/2001, art. 10, § 2º, e da Lei 14.063/2020. Não é assinatura qualificada com certificado ICP-Brasil.

Custo: 20 créditos por envelope enviado (na criação com send: true, o padrão, ou em POST …/send). Rascunhos, consultas, lembretes, cancelamento e downloads são grátis. Se o envio falhar, os créditos voltam na hora; cancelar um envelope já enviado não devolve os créditos. Chaves de teste não consomem créditos, mas os e-mails são enviados de verdade.
Cota do plano: além dos créditos, vale a cota mensal de documentos enviados do plano do site (Grátis 3, Pro 30, Empresas 200, compartilhada pela equipe). Acima dela: 402 esign_quota, sem cobrança.
Limites: PDF até 20 MB e 100 páginas (sem senha), até 10 signatários e 400 campos, prazo de 1 hora a 90 dias (padrão 30).
Situações do envelope: draft → pending → completed, ou refused (alguém recusou), expired (prazo terminou) e canceled. Signatários: waiting (aguardando a vez, em ordem sequencial) → pending (convidado) → signed ou refused, com notified_at, viewed_at, verified_at e signed_at.
Campos: coordenadas relativas à página (0 a 1, origem no canto superior esquerdo): {"signer":0,"type":"signature","page":0,"x":0.1,"y":0.75,"w":0.3,"h":0.07}. Tipos: signature, initials, date, name, cpf. Sem campos, as assinaturas vão só no relatório.
Guarda: o PDF final e o relatório ficam 90 dias depois da conclusão; rascunhos 30 dias; cancelados, recusados e expirados, 30 dias. Arquivos cifrados (AES-256-GCM).
Webhook: envie webhook_url ao criar o envelope. Verificamos a situação a cada 30 segundos e avisamos uma vez quando ele chega a um estado final: esign.envelope.completed, esign.envelope.refused, esign.envelope.expired ou esign.envelope.canceled, com o envelope em data e a mesma assinatura X-Convertaja-Signature das tarefas.

{
  "id": "evt_3c2b1a…",
  "type": "esign.envelope.completed",
  "created_at": "2026-10-15T15:42:10.000Z",
  "data": {
    "id": "K7QD-9WZ2-M4HT-R8PA",
    "object": "envelope",
    "name": "Contrato de prestação de serviços",
    "status": "completed",
    "signed_count": 2,
    "signer_count": 2,
    "completed_at": "2026-10-15T15:42:01.000Z",
    "final_sha256": "9f2c…",
    "verify_url": "https://convertaja.com.br/verificar/K7QD-9WZ2-M4HT-R8PA",
    "signers": [
      {
        "id": 41,
        "name": "Ana Souza",
        "email": "ana@cliente.com.br",
        "role": "sign",
        "status": "signed",
        "signed_at": "2026-10-15T14:10:12.000Z"
      }
    ],
    "files": {
      "final": "https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/files/final",
      "audit": "https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/files/audit"
    },
    "credits_charged": 20
  }
}

POST `/v1/esign/envelopes`

Criar envelope. Sobe o PDF, define signatários e campos e (por padrão) envia os convites por e-mail. Envie multipart/form-data com "file" (PDF até 20 MB e 100 páginas) e "data" (JSON com os campos abaixo), ou JSON com "file": { "base64": "…", "name": "…" } ou { "url": "https://…" } mais os mesmos campos. Responde 201 com o envelope. Além dos créditos, vale a cota mensal de documentos do plano do site (Grátis 3, Pro 30, Empresas 200); acima dela, 402 esign_quota.

Custo: 20 quando enviado (rascunho: 0) crédito(s)

Campo (JSON)	Tipo	Descrição
`name`	string	Nome do documento (padrão: nome do arquivo).
`signers` obrigatório	array	Até 10 pessoas.
`fields`	array	Onde cada pessoa assina (coordenadas relativas, origem no canto superior esquerdo).
`message`	string	Mensagem no convite (até 1.000 caracteres).
`expires_at`	string	Prazo: ISO 8601 ou AAAA-MM-DD (padrão 30 dias, máximo 90).
`sequential`	boolean	Um de cada vez, na ordem de signers.
`send`	boolean	Envia na hora (cobra 20 créditos). false = rascunho grátis.
`return_links`	boolean	Devolve signers[].sign_url (para enviar o link você mesmo).
`webhook_url`	string	URL HTTPS que recebe esign.envelope.completed \| refused \| expired \| canceled.

curl -X POST "https://convertaja.com.br/v1/esign/envelopes" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -F "file=@contrato.pdf" \
  -F 'data={"name":"Contrato de prestação de serviços","message":"Olá! Segue o contrato para assinatura.","signers":[{"name":"Ana Souza","email":"ana@cliente.com.br","role":"sign"},{"name":"Bruno Lima","email":"bruno@empresa.com.br","role":"witness"}],"fields":[{"signer":0,"type":"signature","page":0,"x":0.1,"y":0.75,"w":0.3,"h":0.07},{"signer":1,"type":"signature","page":0,"x":0.55,"y":0.75,"w":0.3,"h":0.07}],"webhook_url":"https://seusite.com.br/webhooks/convertaja"}'

import { openAsBlob } from 'node:fs';

const form = new FormData();
form.append('file', await openAsBlob('contrato.pdf'), 'contrato.pdf');
form.append('data', JSON.stringify({
  "name": "Contrato de prestação de serviços",
  "message": "Olá! Segue o contrato para assinatura.",
  "signers": [
    {
      "name": "Ana Souza",
      "email": "ana@cliente.com.br",
      "role": "sign"
    },
    {
      "name": "Bruno Lima",
      "email": "bruno@empresa.com.br",
      "role": "witness"
    }
  ],
  "fields": [
    {
      "signer": 0,
      "type": "signature",
      "page": 0,
      "x": 0.1,
      "y": 0.75,
      "w": 0.3,
      "h": 0.07
    },
    {
      "signer": 1,
      "type": "signature",
      "page": 0,
      "x": 0.55,
      "y": 0.75,
      "w": 0.3,
      "h": 0.07
    }
  ],
  "webhook_url": "https://seusite.com.br/webhooks/convertaja"
}));

const res = await fetch('https://convertaja.com.br/v1/esign/envelopes', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
  body: form,
});
const envelope = await res.json();
console.log(envelope.id, envelope.status); // ex.: K7QD-9WZ2-M4HT-R8PA pending

import json, os, requests

dados = {
    "name": "Contrato de prestação de serviços",
    "message": "Olá! Segue o contrato para assinatura.",
    "signers": [
        {
            "name": "Ana Souza",
            "email": "ana@cliente.com.br",
            "role": "sign"
        },
        {
            "name": "Bruno Lima",
            "email": "bruno@empresa.com.br",
            "role": "witness"
        }
    ],
    "fields": [
        {
            "signer": 0,
            "type": "signature",
            "page": 0,
            "x": 0.1,
            "y": 0.75,
            "w": 0.3,
            "h": 0.07
        },
        {
            "signer": 1,
            "type": "signature",
            "page": 0,
            "x": 0.55,
            "y": 0.75,
            "w": 0.3,
            "h": 0.07
        }
    ],
    "webhook_url": "https://seusite.com.br/webhooks/convertaja"
}
res = requests.post(
    "https://convertaja.com.br/v1/esign/envelopes",
    headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
    files={"file": open("contrato.pdf", "rb")},
    data={"data": json.dumps(dados)},
)
envelope = res.json()
print(envelope["id"], envelope["status"])

<?php
$dados = json_decode('{"name":"Contrato de prestação de serviços","message":"Olá! Segue o contrato para assinatura.","signers":[{"name":"Ana Souza","email":"ana@cliente.com.br","role":"sign"},{"name":"Bruno Lima","email":"bruno@empresa.com.br","role":"witness"}],"fields":[{"signer":0,"type":"signature","page":0,"x":0.1,"y":0.75,"w":0.3,"h":0.07},{"signer":1,"type":"signature","page":0,"x":0.55,"y":0.75,"w":0.3,"h":0.07}],"webhook_url":"https://seusite.com.br/webhooks/convertaja"}', true);
$ch = curl_init('https://convertaja.com.br/v1/esign/envelopes');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')],
  CURLOPT_POSTFIELDS => ['file' => new CURLFile('contrato.pdf'), 'data' => json_encode($dados)],
]);
$envelope = json_decode(curl_exec($ch), true);
echo $envelope['id'];

GET `/v1/esign/envelopes`

Listar envelopes. Envelopes da conta (criados pela API ou pelo site), do mais recente para o mais antigo. Pagine com next_cursor (ou offset).

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`limit`	query	1 a 100 (padrão 20).
`cursor`	query	next_cursor da página anterior.
`offset`	query	Alternativa ao cursor: pula N envelopes.
`status`	query	draft, pending, completed, refused, expired ou canceled.

curl "https://convertaja.com.br/v1/esign/envelopes?status=pending&limit=20" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

const res = await fetch('https://convertaja.com.br/v1/esign/envelopes?status=pending&limit=20', {
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.get("https://convertaja.com.br/v1/esign/envelopes?status=pending&limit=20", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/esign/envelopes?status=pending&limit=20');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

GET `/v1/esign/envelopes/{id}`

Consultar envelope. Situação do envelope e de cada signatário (convidado, abriu, confirmou o código, assinou ou recusou, com horários). Com ?events=true, inclui a trilha de auditoria.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id`	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).
`events`	query	true para incluir os eventos (IP, porta, dispositivo, horário).

curl "https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA?events=true" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

const res = await fetch('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA?events=true', {
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.get("https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA?events=true", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA?events=true');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

POST `/v1/esign/envelopes/{id}/send`

Enviar rascunho. Envia um envelope criado com send: false. Cobra 20 créditos (estornados se o envio falhar) e conta na cota mensal do plano.

Custo: 20 crédito(s)

Parâmetro	Onde	Descrição
`id`	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).

curl -X POST "https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/send" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

const res = await fetch('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/send', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.post("https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/send", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/send');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

POST `/v1/esign/envelopes/{id}/remind`

Lembrar quem falta. Reenvia o convite para quem está com a vez e ainda não assinou. No máximo um lembrete a cada 30 minutos por pessoa (429 reminder_too_soon).

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id`	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).

curl -X POST "https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/remind" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

const res = await fetch('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/remind', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.post("https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/remind", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/remind');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

POST `/v1/esign/envelopes/{id}/cancel`

Cancelar envelope. Cancela um rascunho ou um envelope aguardando assinaturas e avisa quem estava com a vez. Os créditos do envio não são devolvidos.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id`	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).

curl -X POST "https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/cancel" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

const res = await fetch('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/cancel', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.post("https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/cancel", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/cancel');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

POST `/v1/esign/envelopes/{id}/delete`

Excluir envelope. Apaga o envelope, os arquivos e a trilha de auditoria, em qualquer situação. Também aceito como DELETE /v1/esign/envelopes/{id}.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id`	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).

curl -X POST "https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/delete" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

const res = await fetch('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/delete', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.post("https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/delete", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/delete');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

GET `/v1/esign/envelopes/{id}/files/final`

Baixar PDF assinado. PDF final com as assinaturas aplicadas e o relatório de assinaturas anexado (application/pdf). Só depois que todos assinam (409 envelope_not_completed antes disso). Fica guardado 90 dias.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id`	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).

curl "https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/files/final" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -o contrato-assinado.pdf

import { writeFile } from 'node:fs/promises';

const res = await fetch('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/files/final', {
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
await writeFile('contrato-assinado.pdf', Buffer.from(await res.arrayBuffer()));

import os, requests

res = requests.get("https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/files/final", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
open("contrato-assinado.pdf", "wb").write(res.content)

<?php
$ch = curl_init('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/files/final');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
file_put_contents('contrato-assinado.pdf', curl_exec($ch));

GET `/v1/esign/envelopes/{id}/files/audit`

Baixar relatório de assinaturas. Só o relatório de assinaturas (evidências: IP/porta, dispositivo, horários, hash SHA-256 e QR Code de verificação), em PDF.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id`	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).

curl "https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/files/audit" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -o relatorio-assinaturas.pdf

import { writeFile } from 'node:fs/promises';

const res = await fetch('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/files/audit', {
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
await writeFile('relatorio-assinaturas.pdf', Buffer.from(await res.arrayBuffer()));

import os, requests

res = requests.get("https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/files/audit", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
open("relatorio-assinaturas.pdf", "wb").write(res.content)

<?php
$ch = curl_init('https://convertaja.com.br/v1/esign/envelopes/K7QD-9WZ2-M4HT-R8PA/files/audit');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
file_put_contents('relatorio-assinaturas.pdf', curl_exec($ch));

Só a conta dona da chave vê e mexe nos seus envelopes (outras contas recebem 404 envelope_not_found). A listagem inclui os envelopes criados pelo site.

Dados (CNPJ, CEP, boleto, Pix, códigos)

GET `/v1/cnpj/{cnpj}`

Consultar CNPJ. Razão social, situação, endereço, CNAEs e Simples Nacional, da base pública da Receita Federal. Aceita o CNPJ alfanumérico. Sem quadro de sócios (LGPD).

Custo: 1 crédito(s)

Parâmetro	Onde	Descrição
`cnpj`	caminho	CNPJ com ou sem pontuação (numérico ou alfanumérico).

curl "https://convertaja.com.br/v1/cnpj/11222333000181" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

const res = await fetch('https://convertaja.com.br/v1/cnpj/11222333000181', {
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.get("https://convertaja.com.br/v1/cnpj/11222333000181", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/cnpj/11222333000181');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

GET `/v1/cep/{cep}`

Consultar CEP. Logradouro, bairro, cidade e UF. Fonte: BrasilAPI, com ViaCEP de reserva.

Custo: 1 crédito(s)

Parâmetro	Onde	Descrição
`cep`	caminho	CEP com 8 números.

curl "https://convertaja.com.br/v1/cep/01310100" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

const res = await fetch('https://convertaja.com.br/v1/cep/01310100', {
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.get("https://convertaja.com.br/v1/cep/01310100", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/cep/01310100');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

POST `/v1/validate`

Validar documentos. Confere os dígitos verificadores de CPF, CNPJ (inclusive alfanumérico), CNH, PIS/PASEP, título de eleitor, RENAVAM e CNS. Sem tipo, deduz pelo tamanho.

Custo: 1 (lote: 1 a cada 50) crédito(s)

Campo (JSON)	Tipo	Descrição
`type`	string cpf, cnpj, cnh, pis, titulo, renavam, cns	Tipo do documento (opcional).
`value`	string	Um documento.
`values`	array	Lista de documentos (até 1.000).

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

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({"type":"cnpj","value":"12.ABC.345/01DE-35"}),
});
console.log(await res.json());

import os, requests

res = requests.post(
    "https://convertaja.com.br/v1/validate",
    headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
    json={"type": "cnpj", "value": "12.ABC.345/01DE-35"},
)
print(res.json())

<?php
$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(['type' => 'cnpj', 'value' => '12.ABC.345/01DE-35']),
]);
print_r(json_decode(curl_exec($ch), true));

POST `/v1/boleto/parse`

Ler boleto. Linha digitável (47 bancário, 48 arrecadação) ou código de barras (44) → confere os DVs, converte e mostra banco, valor e vencimento (com o novo fator de vencimento de 22/02/2025).

Custo: 1 crédito(s)

Campo (JSON)	Tipo	Descrição
`code` obrigatório	string	Linha digitável ou código de barras, com ou sem pontuação.

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

const res = await fetch('https://convertaja.com.br/v1/boleto/parse', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"code":"23793.38128 86000.782713 36950.000632 1 10000000012345"}),
});
console.log(await res.json());

import os, requests

res = requests.post(
    "https://convertaja.com.br/v1/boleto/parse",
    headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
    json={"code": "23793.38128 86000.782713 36950.000632 1 10000000012345"},
)
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/boleto/parse');
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(['code' => '23793.38128 86000.782713 36950.000632 1 10000000012345']),
]);
print_r(json_decode(curl_exec($ch), true));

POST `/v1/pix/brcode`

Pix copia e cola (BR Code). Gera o BR Code estático (padrão do Banco Central) e o QR Code em SVG e PNG.

Custo: 1 crédito(s)

Campo (JSON)	Tipo	Descrição
`key` obrigatório	string	Chave Pix: CPF, CNPJ, e-mail, telefone +55 ou aleatória.
`name` obrigatório	string	Nome de quem recebe (até 25).
`city` obrigatório	string	Cidade (até 15).
`amount`	number	Valor em reais (opcional).
`txid`	string	Identificador (até 25 letras/números). Padrão ***.
`description`	string	Mensagem (opcional).

curl -X POST "https://convertaja.com.br/v1/pix/brcode" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"123e4567-e12b-12d1-a456-426655440000","name":"Fulano de Tal","city":"BRASILIA"}'

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":"123e4567-e12b-12d1-a456-426655440000","name":"Fulano de Tal","city":"BRASILIA"}),
});
console.log(await res.json());

import os, requests

res = requests.post(
    "https://convertaja.com.br/v1/pix/brcode",
    headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
    json={"key": "123e4567-e12b-12d1-a456-426655440000", "name": "Fulano de Tal", "city": "BRASILIA"},
)
print(res.json())

<?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' => '123e4567-e12b-12d1-a456-426655440000', 'name' => 'Fulano de Tal', 'city' => 'BRASILIA']),
]);
print_r(json_decode(curl_exec($ch), true));

POST `/v1/qrcode`

Gerar QR Code. QR Code de qualquer texto ou link, em SVG e/ou PNG.

Custo: 1 crédito(s)

Campo (JSON)	Tipo	Descrição
`text` obrigatório	string	Conteúdo (até 2.900 caracteres).
`format`	string svg, png, both	svg (padrão), png ou both.
`ecc`	string L, M, Q, H	Correção de erros.
`module_size`	integer	Pixels por módulo (1–40).
`margin`	integer	Margem em módulos (0–20).
`color`	string	#RRGGBB
`background`	string	#RRGGBB ou transparent

curl -X POST "https://convertaja.com.br/v1/qrcode" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"https://convertaja.com.br","format":"svg"}'

const res = await fetch('https://convertaja.com.br/v1/qrcode', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"text":"https://convertaja.com.br","format":"svg"}),
});
console.log(await res.json());

import os, requests

res = requests.post(
    "https://convertaja.com.br/v1/qrcode",
    headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
    json={"text": "https://convertaja.com.br", "format": "svg"},
)
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/qrcode');
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(['text' => 'https://convertaja.com.br', 'format' => 'svg']),
]);
print_r(json_decode(curl_exec($ch), true));

POST `/v1/barcode`

Gerar código de barras. Code 128, EAN-13, EAN-8, UPC-A, Code 39, ITF (boleto), ITF-14, DataMatrix e QR, em SVG e/ou PNG. EAN/UPC sem o último dígito recebem o DV calculado.

Custo: 1 crédito(s)

Campo (JSON)	Tipo	Descrição
`type` obrigatório	string code128, ean13, ean8, upca, code39, itf, itf14, datamatrix, qr	Tipo.
`value` obrigatório	string	Conteúdo.
`format`	string svg, png, both	svg (padrão), png ou both.
`module_size`	number	Largura do módulo em px.
`height`	number	Altura das barras em px (10–600).
`show_text`	boolean	Texto legível embaixo.

curl -X POST "https://convertaja.com.br/v1/barcode" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"ean13","value":"789123456789","format":"png"}'

const res = await fetch('https://convertaja.com.br/v1/barcode', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"type":"ean13","value":"789123456789","format":"png"}),
});
console.log(await res.json());

import os, requests

res = requests.post(
    "https://convertaja.com.br/v1/barcode",
    headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
    json={"type": "ean13", "value": "789123456789", "format": "png"},
)
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/barcode');
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(['type' => 'ean13', 'value' => '789123456789', 'format' => 'png']),
]);
print_r(json_decode(curl_exec($ch), true));

Conta e uso

GET `/v1/me`

Conta, plano e créditos. Mostra a conta dona da chave, o plano, os créditos (franquia, pacotes, saldo) e os limites.

Custo: grátis (não consome créditos)

curl "https://convertaja.com.br/v1/me" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

const res = await fetch('https://convertaja.com.br/v1/me', {
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.get("https://convertaja.com.br/v1/me", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/me');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

GET `/v1/usage`

Uso por dia. Créditos e chamadas por dia e por endpoint. Padrão: últimos 30 dias. Máximo de 366 dias.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`from`	query	Data inicial AAAA-MM-DD.
`to`	query	Data final AAAA-MM-DD (padrão: hoje).

curl "https://convertaja.com.br/v1/usage" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

const res = await fetch('https://convertaja.com.br/v1/usage', {
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.get("https://convertaja.com.br/v1/usage", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.json())

<?php
$ch = curl_init('https://convertaja.com.br/v1/usage');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')]]);
print_r(json_decode(curl_exec($ch), true));

Chaves de teste

Chaves cj_test_… funcionam em todos os endpoints, em qualquer plano, sem consumir créditos, com limite de 20 chamadas por dia por conta (429 test_limit). Os resultados são reais; as respostas trazem X-Convertaja-Mode: test e as tarefas têm "test": true. Use para desenvolver a integração e troque por uma chave cj_live_ em produção.

Segurança e CORS

As chaves são secretas e feitas para uso servidor a servidor. A API não envia cabeçalhos CORS, então navegadores bloqueiam chamadas diretas de páginas web — e isso é proposital.
Arquivos por URL e webhooks só vão para endereços públicos: redes internas (10.x, 192.168.x, 127.x, 169.254.x, IPv6 local) são bloqueadas no momento da conexão, inclusive depois de redirecionamentos.
Arquivos são apagados 1 hora depois da criação da tarefa. Registramos IP, porta, data e hora das chamadas por 6 meses (Marco Civil da Internet, art. 15).

Mudanças

1.1.0 (15/10/2026) — assinatura eletrônica: /v1/esign/envelopes (criar, listar, consultar, enviar, lembrar, cancelar, excluir, baixar PDF final e relatório) e webhooks esign.envelope.*.
1.0.0 (15/10/2026) — lançamento: 53 ferramentas de arquivo, CNPJ (inclusive alfanumérico), CEP, validação, boleto, Pix, QR Code, código de barras, webhooks assinados e OpenAPI 3.1.

Mudanças incompatíveis só em uma nova versão (/v2), com aviso prévio de 6 meses.

Documentação da API

Introdução

Autenticação

Créditos e preços

Limites

Erros

Ferramentas de arquivo

GET /v1/tools

GET /v1/tools/{toolId}

POST /v1/tools/{toolId}

Tarefas e downloads

GET /v1/jobs/{id}

GET /v1/jobs/{id}/files/{index}

GET /v1/jobs/{id}/download

Webhooks

Assinatura eletrônica

POST /v1/esign/envelopes

GET /v1/esign/envelopes

GET /v1/esign/envelopes/{id}

POST /v1/esign/envelopes/{id}/send

POST /v1/esign/envelopes/{id}/remind

POST /v1/esign/envelopes/{id}/cancel

POST /v1/esign/envelopes/{id}/delete

GET /v1/esign/envelopes/{id}/files/final

GET /v1/esign/envelopes/{id}/files/audit

Dados (CNPJ, CEP, boleto, Pix, códigos)

GET /v1/cnpj/{cnpj}

GET /v1/cep/{cep}

POST /v1/validate

POST /v1/boleto/parse

POST /v1/pix/brcode

POST /v1/qrcode

POST /v1/barcode

Conta e uso

GET /v1/me

GET /v1/usage

Chaves de teste

Segurança e CORS

Mudanças

GET `/v1/tools`

GET `/v1/tools/{toolId}`

POST `/v1/tools/{toolId}`

GET `/v1/jobs/{id}`

GET `/v1/jobs/{id}/files/{index}`

GET `/v1/jobs/{id}/download`

POST `/v1/esign/envelopes`

GET `/v1/esign/envelopes`

GET `/v1/esign/envelopes/{id}`

POST `/v1/esign/envelopes/{id}/send`

POST `/v1/esign/envelopes/{id}/remind`

POST `/v1/esign/envelopes/{id}/cancel`

POST `/v1/esign/envelopes/{id}/delete`

GET `/v1/esign/envelopes/{id}/files/final`

GET `/v1/esign/envelopes/{id}/files/audit`

GET `/v1/cnpj/{cnpj}`

GET `/v1/cep/{cep}`

POST `/v1/validate`

POST `/v1/boleto/parse`

POST `/v1/pix/brcode`

POST `/v1/qrcode`

POST `/v1/barcode`

GET `/v1/me`

GET `/v1/usage`