ConverterHQDevelopers
Geliştirici aktivasyonu

API’yi sandbox’ta doğrulayın. Yalnızca canlıya geçerken yükseltin.

Hesaptan ilk API çağrısına, ardından bağlamı kaybetmeden üretime geçiş.

Önce bir sandbox projesi ve dar kapsamlı test anahtarı oluşturun. Üretim planına geçmeden önce doğrudan storage yüklemesini ve gerçek bir dönüşümü doğrulayın.

Üretim aktarımı: yerel dosya baytları Files API üzerinden doğrudan imzalı nesne depolamaya yüklenir; dönüşümler daha sonra sahip olunan File ID’ye başvurur. API kontrol düzlemi yerel dosya baytlarını değil, meta verileri ve ID’leri alır.

HQTools hesap ve ödeme adımları bu dil için şu anda İngilizce gösterilir.

1

Sandbox erişimi

Sandbox ve üretim

Projeye bağlı hq_test_... anahtarı sınırlı değerlendirme erişimi sağlar. hq_live_... anahtarları aktif API planı gerektirir.

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
Tam platform scope’ları
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

Doğrula

Minimum kapsamlı anahtar oluşturun

HQTools içinde bir ConverterHQ projesi seçin ve quickstart için yalnız Files, Jobs ve capabilities kapsamlarını verin.

3

Hazırlık kontrolü

Bağlamı doğrulayın

Dosya göndermeden önce GET /v1/me ile environment, project_id, scopes ve limits değerlerini kontrol edin; sandbox ve live kaynaklarını karıştırmayın.

4

İlk dönüşüm

Doğrudan depolamaya yükleyin ve gerçek bir Job çalıştırın.

Bir File ayırın, byte’ları imzalı object-storage URL’sine PUT edin, File’ı tamamlayın, Job gönderin ve sonucu indirin. Dosya byte’ları ConverterHQ API sürecinden geçmez.

Yönlendirmeli dönüşümü etkinleştirmek için yukarıda bir sandbox veya live anahtarını doğrulayın.

İlk sandbox dönüşümü
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"