convertajá

Guia 2 de 8

Converter um arquivo: enviar, acompanhar e baixar o resultado

Toda ferramenta de arquivo funciona igual: você envia, a API cria uma tarefa, você espera terminar e baixa. Este guia usa o Comprimir PDF, mas vale para todas.

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

O que você vai construir

Um script que envia um PDF para POST /v1/tools/comprimir-pdf, acompanha a tarefa até o fim e salva o arquivo comprimido. Em cURL, Node.js, Python e PHP.

Antes de começar

  • Uma chave de API em CONVERTAJA_KEY (veja Primeiros passos).
  • Um PDF de teste chamado contrato.pdf na pasta onde você vai rodar os exemplos.

Passo 1: Descubra as opções da ferramenta

Cada ferramenta tem um id (ex.: comprimir-pdf) e opções próprias. Consulte com GET /v1/tools/{id} (grátis):

curl "https://convertaja.com.br/v1/tools/comprimir-pdf" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"
Resposta 200 (trecho)
{
  "id": "comprimir-pdf",
  "operation": "pdf-compress",
  "name": "Comprimir PDF",
  "accepted_extensions": [
    "pdf"
  ],
  "multiple": true,
  "min_files": 1,
  "max_files": null,
  "options_schema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "level": {
        "title": "Compressão",
        "type": "string",
        "enum": [
          "low",
          "medium",
          "high"
        ],
        "x-enum-labels": {
          "low": "Leve",
          "medium": "Recomendada",
          "high": "Máxima"
        },
        "default": "medium"
      }
    }
  },
  "heavy": false,
  "kind": "light",
  "credits_per_file": 1,
  "docs_url": "https://convertaja.com.br/api/docs/comprimir-pdf"
}

Opções que não existem ou valores fora da lista são recusados com 400 invalid_option antes de cobrar qualquer crédito.

Passo 2: Envie o arquivo e crie a tarefa

Mande o arquivo em multipart/form-data no campo files (repita o campo para vários arquivos). As opções vão no campo options como JSON, ou como campos soltos (-F "level=high"):

curl -i -X POST "https://convertaja.com.br/v1/tools/comprimir-pdf" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -F "files=@contrato.pdf" \
  -F 'options={"level":"high"}'

A resposta chega na hora, com status 202: a tarefa foi aceita e os créditos foram reservados. O cabeçalho Location aponta para a tarefa.

Resposta 202
{
  "id": "AxLIGjFJHd93",
  "tool": "comprimir-pdf",
  "operation": "pdf-compress",
  "status": "running",
  "progress": 0,
  "message": "Processando…",
  "created_at": "2026-10-16T20:23:36.199Z",
  "finished_at": null,
  "expires_at": "2026-10-16T21:23:36.199Z",
  "credits_charged": 1,
  "credits_refunded": 0,
  "test": false,
  "outputs": []
}

Passo 3: Acompanhe até terminar

Consulte GET /v1/jobs/{id} a cada 1 ou 2 segundos até status virar done ou error. A consulta é grátis, mas conta no limite por minuto.

# Troque AxLIGjFJHd93 pelo id da sua tarefa
curl "https://convertaja.com.br/v1/jobs/AxLIGjFJHd93" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"
Resposta 200 (concluída)
{
  "id": "Fi_TgsjgpM19",
  "tool": "comprimir-pdf",
  "operation": "pdf-compress",
  "status": "done",
  "progress": 100,
  "message": "Pronto!",
  "created_at": "2026-10-16T20:36:06.144Z",
  "finished_at": "2026-10-16T20:36:07.523Z",
  "expires_at": "2026-10-16T21:36:06.144Z",
  "credits_charged": 1,
  "credits_refunded": 0,
  "test": false,
  "outputs": [
    {
      "index": 0,
      "name": "contrato - comprimido.pdf",
      "size": 34031,
      "url": "https://convertaja.com.br/v1/jobs/Fi_TgsjgpM19/files/0"
    }
  ],
  "download_url": "https://convertaja.com.br/v1/jobs/Fi_TgsjgpM19/download",
  "info": "5.5 MB → 33 KB (99% menor)"
}

info traz um resumo da ferramenta (aqui, o tamanho antes e depois). expires_at é quando os arquivos são apagados: 1 hora depois da criação.

Dica Prefere não ficar consultando? Envie um webhook_url e receba um aviso quando a tarefa terminar. Veja o guia Webhooks.

Passo 4: Baixe o resultado

Cada arquivo gerado está em outputs[].url. download_url baixa tudo: o próprio arquivo quando é um só, ou um ZIP quando são vários. As duas URLs exigem a mesma chave:

# Um arquivo pela posição (outputs[].url)…
curl -f -o contrato-comprimido.pdf "https://convertaja.com.br/v1/jobs/AxLIGjFJHd93/files/0" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

# …ou tudo de uma vez (download_url): o próprio arquivo, ou um ZIP se houver vários
curl -f -OJ "https://convertaja.com.br/v1/jobs/AxLIGjFJHd93/download" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

O -f faz o cURL falhar em vez de salvar a mensagem de erro (JSON) dentro do “PDF”.

Passo 5: Junte tudo num script

Os três passos juntos, com tratamento de erro. Troque comprimir-pdf e as opções por qualquer outra ferramenta:

# Requer curl e jq. 1) Envia e espera até 60 s pelo resultado
curl -s -X POST "https://convertaja.com.br/v1/tools/comprimir-pdf?wait=true" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -F "files=@contrato.pdf" \
  -F 'options={"level":"high"}' > tarefa.json

# 2) Confere o status e baixa o resultado
if [ "$(jq -r .status tarefa.json)" = "done" ]; then
  curl -fs -o contrato-comprimido.pdf "$(jq -r .download_url tarefa.json)" \
    -H "Authorization: Bearer $CONVERTAJA_KEY"
  jq -r .info tarefa.json
else
  jq . tarefa.json
fi
Tarefa Fi_TgsjgpM19 criada (1 crédito)
Salvo: contrato - comprimido.pdf (34031 bytes)
5.5 MB → 33 KB (99% menor)

Atalho: esperar na mesma chamada com ?wait=true

Para arquivos pequenos e ferramentas rápidas, acrescente ?wait=true (espera até 60 s) ou ?wait=20 (até 20 s). Se terminar a tempo, a resposta é 200 já com outputs; se não, é o mesmo 202 de antes e você continua consultando. O exemplo em cURL do passo 5 usa esse atalho.

Atenção Não use wait com timeout curto no seu cliente HTTP: se a sua conexão cair, a tarefa continua rodando e já foi cobrada. Para tarefas pesadas (OCR, Office, vídeo), prefira 202 + consulta ou webhook.

Enviar por URL ou base64 (JSON)

Se o arquivo já está num endereço público, mande só a URL; baixamos com limite de tamanho do plano e de tempo (60 s). Endereços de rede interna são bloqueados (422 forbidden_url).

curl -X POST "https://convertaja.com.br/v1/tools/comprimir-pdf?wait=30" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files":[{"url":"https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"}],"options":{"level":"high"}}'

Ou mande o conteúdo em base64 (corpo JSON de até 60 MB; acima disso, use multipart ou URL):

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

const res = await fetch('https://convertaja.com.br/v1/tools/comprimir-pdf?wait=true', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    files: [{ base64: (await readFile('contrato.pdf')).toString('base64'), name: 'contrato.pdf' }],
    options: { level: 'high' },
  }),
});
console.log(await res.json());

Erros e o que fazer

Erros de validação voltam na hora, antes de cobrar:

HTTPcodeQuando
400missing_filesNenhum arquivo no campo files.
400invalid_optionOpção que não existe ou valor fora da lista.
400too_many_filesMais arquivos do que a ferramenta ou o plano permitem.
402insufficient_creditsSaldo menor que o custo da chamada.
404tool_not_found / job_not_foundId errado, ou a tarefa já passou de 1 hora.
413file_too_largeArquivo maior que o limite do plano.
415unsupported_file_typeExtensão que a ferramenta não aceita.
422forbidden_urlURL de arquivo aponta para rede interna.
429concurrency_limitTarefas pesadas demais ao mesmo tempo. Espere uma terminar.
400: valor de opção inválido
{
  "error": {
    "code": "invalid_option",
    "message": "Valor inválido para \"level\". Use um destes: low, medium, high.",
    "request_id": "req_UkbrW3QRi59d"
  }
}
415: tipo de arquivo
{
  "error": {
    "code": "unsupported_file_type",
    "message": "Tipo de arquivo não aceito por esta ferramenta: \"nota.xml\". Aceitos: pdf.",
    "request_id": "req_UkbrW3QRi59d"
  }
}
402: sem créditos
{
  "error": {
    "code": "insufficient_credits",
    "message": "Créditos insuficientes: esta chamada custa 2 e você tem 1. Compre um pacote ou mude de plano em https://convertaja.com.br/conta/api.",
    "credits_required": 2,
    "credits_remaining": 1,
    "request_id": "req_UkbrW3QRi59d"
  }
}

Se o problema estiver no conteúdo do arquivo, a tarefa é aceita (202) e termina com status: "error". Nesse caso os créditos voltam sozinhos (credits_refunded):

Tarefa com erro (créditos devolvidos)
{
  "id": "lrzqWwqfYv4a",
  "tool": "xml-nfe-para-pdf",
  "operation": "nfe-danfe",
  "status": "error",
  "progress": 0,
  "message": "Nenhuma NF-e encontrada. Envie os arquivos XML das notas (ou um ZIP com eles). (1 arquivo ignorado por não ser NF-e)",
  "created_at": "2026-10-16T20:24:25.824Z",
  "finished_at": "2026-10-16T20:24:25.998Z",
  "expires_at": "2026-10-16T21:24:25.824Z",
  "credits_charged": 1,
  "credits_refunded": 1,
  "test": false,
  "outputs": [],
  "error": {
    "code": "job_failed",
    "message": "Nenhuma NF-e encontrada. Envie os arquivos XML das notas (ou um ZIP com eles). (1 arquivo ignorado por não ser NF-e)"
  }
}

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.