ConverterHQDevelopers
Ativação para desenvolvedores

Valide a API no sandbox. Faça upgrade apenas quando entrar em produção.

Da conta à primeira chamada de API e depois à produção sem perder o contexto.

Comece com um projeto sandbox e uma chave de teste com escopo mínimo. Valide upload direto para o armazenamento e uma conversão real antes de contratar produção.

Transporte em produção: os bytes do arquivo local são enviados diretamente ao armazenamento de objetos assinado pela API Files; depois, as conversões referenciam o File ID próprio. O plano de controle da API recebe metadados e IDs, não os bytes do arquivo local.

A conta e o checkout do HQTools são exibidos atualmente em inglês para este idioma.

1

Acesso sandbox

Sandbox e produção

Uma chave hq_test_... vinculada ao projeto oferece acesso de avaliação limitado. Chaves hq_live_... exigem um plano de API ativo.

converterhq.convert, converterhq.capabilities.read, converterhq.files.read, converterhq.files.write, converterhq.jobs.read, converterhq.jobs.write, converterhq.tasks.read, converterhq.tasks.write, converterhq.usage.read
Scopes completos da plataforma
converterhq.convert, converterhq.capabilities.read, converterhq.files.read, converterhq.files.write, converterhq.jobs.read, converterhq.jobs.write, converterhq.tasks.read, converterhq.tasks.write, converterhq.usage.read, converterhq.workflows.read, converterhq.workflows.write, converterhq.connections.read, converterhq.connections.write, converterhq.webhooks.read, converterhq.webhooks.write, converterhq.logs.read, converterhq.signed_urls.read, converterhq.signed_urls.write, converterhq.realtime.connect
2

Verificar

Criar uma chave mínima

Crie ou selecione um projeto ConverterHQ no HQTools e conceda apenas os escopos de Files, Jobs e capabilities necessários ao quickstart.

3

Verificação de prontidão

Verificar o contexto

Chame GET /v1/me e confirme environment, project_id, scopes e limits antes de enviar arquivos. Isso evita misturar recursos de sandbox e produção.

4

Primeira conversão

Envie diretamente ao armazenamento e execute um Job real.

Crie um File, envie os bytes via PUT para a URL de armazenamento assinada, conclua o File, envie um Job e baixe o resultado. Os bytes não atravessam o processo API do ConverterHQ.

Verifique acima uma chave sandbox ou live para ativar a conversão guiada.

Primeira conversão sandbox
set -eu
API='https://sandbox.api.converterhq.io/v1'
KEY="hq_test_..."
FILE='input.docx'
FROM='docx'
TO='pdf'
OUTPUT="result.$TO"

# Allocate metadata, upload bytes directly to storage, then complete the File.
OWNED=$(curl -fsS "$API/files" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg filename "$FILE" '{filename:$filename,content_type:"application/octet-stream"}')")
FILE_ID=$(printf '%s' "$OWNED" | jq -er .id)
UPLOAD_URL=$(printf '%s' "$OWNED" | jq -er .upload.url)
CONTENT_TYPE=$(printf '%s' "$OWNED" | jq -r '.upload.headers["Content-Type"] // "application/octet-stream"')
curl -fsS -X PUT "$UPLOAD_URL" --upload-file "$FILE" -H "Content-Type: $CONTENT_TYPE"
curl -fsS -X POST "$API/files/$FILE_ID/complete" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{}'

# Reuse this key when retrying this submission after a transport failure.
IDEMPOTENCY_KEY="activation-$FILE_ID"
CONVERSION=$(curl -fsS -X POST "$API/convert" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg file_id "$FILE_ID" --arg from "$FROM" --arg to "$TO" '{input:{file_id:$file_id},input_format:$from,output_format:$to,options:{}}')")
JOB_ID=$(printf '%s' "$CONVERSION" | jq -er .job_id)
printf 'Job: %s\n' "$JOB_ID"

# Wait up to five minutes. A terminal failure is never treated as a download.
ATTEMPT=0
while [ "$ATTEMPT" -lt 10 ]; do
  JOB=$(curl -fsS "$API/jobs/$JOB_ID/wait?timeout=30" -H "Authorization: Bearer $KEY")
  STATUS=$(printf '%s' "$JOB" | jq -er .status)
  case "$STATUS" in
    succeeded) break ;;
    failed|cancelled)
      printf '%s\n' "$JOB" >&2
      exit 1 ;;
  esac
  ATTEMPT=$((ATTEMPT + 1))
done
if [ "$STATUS" != succeeded ]; then
  printf 'Timed out. Resume with GET %s/jobs/%s/wait?timeout=30\n' "$API" "$JOB_ID" >&2
  exit 1
fi
OUTPUT_FILE_ID=$(printf '%s' "$JOB" | jq -er '[.tasks[] | select(.operation == "convert" and .status == "succeeded") | (.result.file_id // .result.output_file_id) | select(. != null)][0]')
RESULT=$(curl -fsS "$API/files/$OUTPUT_FILE_ID" -H "Authorization: Bearer $KEY")
DOWNLOAD_URL=$(printf '%s' "$RESULT" | jq -er .download_url)
# Signed storage URLs carry their own authorization; do not forward the API key.
curl -fsS "$DOWNLOAD_URL" --output "$OUTPUT"
printf 'Saved %s\n' "$OUTPUT"