ConverterHQDevelopers
Aktivasi developer

Buktikan API di sandbox. Upgrade hanya saat siap masuk produksi.

Dari akun ke panggilan API pertama lalu ke produksi tanpa kehilangan konteks.

Mulai dengan project sandbox dan test key ber-scope kecil. Buktikan upload langsung ke storage dan satu konversi nyata sebelum berlangganan produksi.

Transport produksi: byte file lokal diunggah langsung ke penyimpanan objek bertanda tangan melalui Files API, lalu konversi merujuk File ID yang dimiliki. Control plane API menerima metadata dan ID, bukan byte file lokal.

Akun dan checkout HQTools saat ini ditampilkan dalam bahasa Inggris untuk bahasa ini.

1

Akses sandbox

Sandbox dan produksi

Test key hq_test_... yang terikat project memberi akses evaluasi dengan batasan. Live key hq_live_... tetap memerlukan paket API aktif.

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
Scope platform lengkap
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

Verifikasi

Buat key dengan scope minimum

Buat atau pilih project ConverterHQ di HQTools, lalu berikan hanya scope Files, Jobs, dan capabilities yang dibutuhkan quickstart.

3

Pemeriksaan kesiapan

Verifikasi konteks

Panggil GET /v1/me dan periksa environment, project_id, scopes, serta limits sebelum mengirim file agar resource sandbox dan live tidak tertukar.

4

Konversi pertama

Upload langsung ke storage dan jalankan Job nyata.

Alokasikan File, PUT byte ke URL object-storage bertanda tangan, selesaikan File, kirim Job, lalu unduh hasil. Byte file tidak melewati proses API ConverterHQ.

Verifikasi kunci sandbox atau live di atas untuk mengaktifkan konversi terpandu.

Konversi sandbox pertama
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"