Jobs

Um Job é um envio de um ou mais arquivos. A API extrai cada arquivo em segundo plano.

O objeto Job

Cada arquivo:

Statement

Todo campo é null quando o extrato não o mostra.

Transaction (modo smart)

Todo campo é null quando o extrato não o mostra.

Rows (modo simple)

rows é a tabela do extrato como impressa: um array de linhas, cada uma um array de células em texto. O modo simple não interpreta valores nem datas.

Criar um Job

POST /v1/jobs

Envia arquivos e inicia a extração. O corpo é multipart/form-data.

Mantenha a requisição inteira abaixo de 20 MB. A plataforma rejeita requisições maiores antes de chegarem à API, então a resposta não tem corpo de erro em JSON.

curl https://energized-butterfly-12.convex.site/v1/jobs \
  -H "Authorization: Bearer $CONVERT_API_KEY" \
  -F "files=@janeiro.pdf" \
  -F "files=@fevereiro.pdf" \
  -F "mode=smart"

const body = new FormData();
body.append(
  "files",
  new Blob([pdfBytes], { type: "application/pdf" }),
  "janeiro.pdf",
);
body.append("mode", "smart");

const res = await fetch("https://energized-butterfly-12.convex.site/v1/jobs", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.CONVERT_API_KEY}` },
  body,
});
const job = await res.json();

Retorna 202 Accepted com o Job no status pending.

A API verifica todos os arquivos antes de aceitar o Job. Se algum arquivo falhar em uma verificação, nada é armazenado e nenhuma página é gasta:

• 400 para tipo, tamanho ou número de páginas inválido.
• 409 DUPLICATE_FILE quando um arquivo já foi convertido nesta conta. Liste os Jobs para encontrá-lo em vez de enviar de novo.
• 402 QUOTA_EXCEEDED quando as páginas do Job passam das páginas restantes no mês.

Obter um Job

GET /v1/jobs/{id}

Retorna o Job com seus resultados. Consulte este endpoint a cada 5 segundos até status ser processed ou failed.

curl https://energized-butterfly-12.convex.site/v1/jobs/jn7craq7xc3qjq1knfzy5612f98gqnmh \
  -H "Authorization: Bearer $CONVERT_API_KEY"

async function waitForJob(id) {
  for (;;) {
    const res = await fetch(`https://energized-butterfly-12.convex.site/v1/jobs/${id}`, {
      headers: { Authorization: `Bearer ${process.env.CONVERT_API_KEY}` },
    });
    const job = await res.json();
    if (job.status === "processed" || job.status === "failed") return job;
    await new Promise((r) => setTimeout(r, 5000));
  }
}

Um Job processed ainda pode conter arquivos failed. Verifique o status de cada arquivo.

Retorna 404 JOB_NOT_FOUND para um id desconhecido ou um Job de outra conta.

Obter um arquivo de extrato

GET /v1/jobs/{id}/statement-files/{fileId}

Retorna uma entrada de files do Job, no mesmo formato. Use quando você guarda os ids dos arquivos ou para consultar um arquivo de um Job grande. Um arquivo ainda não extracted não tem statement, transactions nem rows.

curl https://energized-butterfly-12.convex.site/v1/jobs/jn7craq7xc3qjq1knfzy5612f98gqnmh/statement-files/jd718c20qj99x07hqmb6q48kn98gqamb \
  -H "Authorization: Bearer $CONVERT_API_KEY"

Retorna 404 JOB_NOT_FOUND quando o Job não existe na sua conta, e 404 STATEMENT_FILE_NOT_FOUND quando o arquivo não está nesse Job.

Listar Jobs

GET /v1/jobs

Lista seus Jobs, do mais recente ao mais antigo, sem os resultados.

curl "https://energized-butterfly-12.convex.site/v1/jobs?limit=10" \
  -H "Authorization: Bearer $CONVERT_API_KEY"

{
  "jobs": [
    {
      "id": "jn7craq7xc3qjq1knfzy5612f98gqnmh",
      "status": "processed",
      "createdAt": "2026-10-21T12:51:02.816Z",
      "fileCount": 1
    }
  ],
  "nextCursor": "eyJ..."
}

nextCursor é null na última página.

Excluir um Job

DELETE /v1/jobs/{id}

Exclui os arquivos enviados e os dados extraídos. Não dá para desfazer. As páginas do Job continuam contando no plano deste mês.

curl -X DELETE https://energized-butterfly-12.convex.site/v1/jobs/jn7craq7xc3qjq1knfzy5612f98gqnmh \
  -H "Authorization: Bearer $CONVERT_API_KEY"

Retorna 204 No Content. Um Job ainda pending ou processing retorna 409 JOB_IN_PROGRESS; espere ele terminar antes.