Idempotência, lista de tarefas e reenvios seguros

# Gere UMA chave por operação e repita o MESMO pedido com a MESMA chave se a conexão cair
CHAVE=$(uuidgen)   # ex.: 6f1c2b8e-3f0a-4c55-9d1e-2a7b9c0d4e11; guarde junto do pedido no seu banco

curl -X POST "https://convertaja.com.br/v1/tools/comprimir-pdf" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -H "Idempotency-Key: $CHAVE" \
  -F "files=@contrato.pdf" \
  --retry 3 --retry-all-errors -i
# A repetição devolve a mesma tarefa (mesmo "id") com o cabeçalho Idempotent-Replayed: true, sem cobrar de novo

import { randomUUID } from 'node:crypto';
import { openAsBlob } from 'node:fs';

// Cria a tarefa com novas tentativas seguras: a mesma Idempotency-Key em todas as tentativas
async function criarTarefa(arquivo, chave = randomUUID()) {
  for (let tentativa = 1; tentativa <= 4; tentativa++) {
    try {
      const form = new FormData();
      form.append('files', await openAsBlob(arquivo), arquivo);
      const res = await fetch('https://convertaja.com.br/v1/tools/comprimir-pdf', {
        method: 'POST',
        headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}`, 'Idempotency-Key': chave },
        body: form,
        signal: AbortSignal.timeout(30000),
      });
      const corpo = await res.json();
      if (res.status === 409 && corpo.error.code === 'idempotency_in_progress') throw new Error('em andamento');
      if (!res.ok) throw Object.assign(new Error(corpo.error.message), { fatal: true, code: corpo.error.code });
      if (res.headers.get('idempotent-replayed')) console.log('Repetição: a tarefa já existia, nada foi cobrado de novo.');
      return corpo; // { id, status: "running", credits_charged, … }
    } catch (e) {
      if (e.fatal || tentativa === 4) throw e;
      await new Promise((r) => setTimeout(r, 1000 * 2 ** tentativa)); // queda de rede ou tempo esgotado: tenta de novo
    }
  }
}

const tarefa = await criarTarefa('contrato.pdf');
console.log(tarefa.id, tarefa.status);

import os
import time
import uuid

import requests

def criar_tarefa(arquivo, chave=None):
    chave = chave or str(uuid.uuid4())  # a mesma chave em todas as tentativas
    for tentativa in range(1, 5):
        try:
            with open(arquivo, "rb") as f:
                res = requests.post(
                    "https://convertaja.com.br/v1/tools/comprimir-pdf",
                    headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}", "Idempotency-Key": chave},
                    files={"files": f},
                    timeout=30,
                )
            corpo = res.json()
            if res.status_code == 409 and corpo["error"]["code"] == "idempotency_in_progress":
                raise requests.ConnectionError("em andamento")
            if not res.ok:
                raise SystemExit(f"{corpo['error']['code']}: {corpo['error']['message']}")
            if res.headers.get("Idempotent-Replayed"):
                print("Repetição: a tarefa já existia, nada foi cobrado de novo.")
            return corpo
        except (requests.ConnectionError, requests.Timeout):
            if tentativa == 4:
                raise
            time.sleep(2 ** tentativa)

tarefa = criar_tarefa("contrato.pdf")
print(tarefa["id"], tarefa["status"])

# Tarefas concluídas de uma ferramenta, criadas a partir de 17/10/2026 (horário de Brasília), 50 por página
curl -G "https://convertaja.com.br/v1/jobs" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  --data-urlencode "status=done" \
  --data-urlencode "tool=comprimir-pdf" \
  --data-urlencode "created_after=2026-10-17" \
  --data-urlencode "limit=50"

# Próxima página: o next_cursor da resposta em starting_after
curl -G "https://convertaja.com.br/v1/jobs" -H "Authorization: Bearer $CONVERTAJA_KEY" \
  --data-urlencode "limit=50" --data-urlencode "starting_after=Fi_TgsjgpM19"

// Percorre todas as páginas de GET /v1/jobs (mais recentes primeiro)
async function* tarefas(filtros = {}) {
  let cursor = null;
  do {
    const qs = new URLSearchParams({ limit: '100', ...filtros, ...(cursor ? { starting_after: cursor } : {}) });
    const res = await fetch(`https://convertaja.com.br/v1/jobs?${qs}`, { headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` } });
    const pagina = await res.json();
    if (!res.ok) throw new Error(`${pagina.error.code}: ${pagina.error.message}`);
    yield* pagina.data;
    cursor = pagina.has_more ? pagina.next_cursor : null;
  } while (cursor);
}

const desde = new Date(Date.now() - 24 * 3600 * 1000).toISOString();
let creditos = 0;
for await (const t of tarefas({ status: 'done,error', created_after: desde })) {
  creditos += t.credits_charged - t.credits_refunded;
  console.log(t.created_at, t.tool, t.status, t.files_available ? t.download_url : '(arquivos já apagados)');
}
console.log('Créditos nas últimas 24 h:', creditos);

import os
from datetime import datetime, timedelta, timezone

import requests

def tarefas(**filtros):
    """Percorre todas as páginas de GET /v1/jobs (mais recentes primeiro)."""
    cursor = None
    while True:
        params = {"limit": 100, **filtros, **({"starting_after": cursor} if cursor else {})}
        res = requests.get("https://convertaja.com.br/v1/jobs", params=params,
                           headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"}, timeout=30)
        pagina = res.json()
        if not res.ok:
            raise SystemExit(f"{pagina['error']['code']}: {pagina['error']['message']}")
        yield from pagina["data"]
        if not pagina["has_more"]:
            break
        cursor = pagina["next_cursor"]

desde = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
for t in tarefas(status="error", created_after=desde):
    print(t["created_at"], t["tool"], t["error"]["code"], t["error"]["message"])

# Apaga os arquivos gerados antes de 1 hora (a tarefa continua na lista, com files_available: false)
curl -X DELETE "https://convertaja.com.br/v1/jobs/Fi_TgsjgpM19" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"

# Mesmo efeito, para clientes que só fazem GET e POST
curl -X POST "https://convertaja.com.br/v1/jobs/Fi_TgsjgpM19/delete" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"