ConverterHQDevelopers
Aktywacja deweloperska

Sprawdź API w sandboxie. Przejdź na produkcję dopiero, gdy integracja jest gotowa.

Od konta do pierwszego wywołania API, a potem bezpiecznie do produkcji.

Zacznij od projektu sandbox i klucza testowego o minimalnym zakresie. Przed zakupem planu produkcyjnego potwierdź bezpośredni upload do storage i prawdziwą konwersję.

Transport produkcyjny: bajty lokalnego pliku są przesyłane bezpośrednio do podpisanego magazynu obiektowego przez API Files; konwersje odwołują się następnie do własnego File ID. Warstwa sterująca API otrzymuje metadane i identyfikatory, a nie bajty lokalnego pliku.

Konto i checkout HQTools są obecnie wyświetlane po angielsku dla tego języka.

1

Dostęp sandbox

Sandbox i produkcja

Klucz hq_test_... powiązany z projektem daje ograniczony dostęp ewaluacyjny. Klucze hq_live_... wymagają aktywnego planu API.

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
Pełne zakresy platformy
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

Weryfikacja

Utwórz minimalny klucz

Utwórz lub wybierz projekt ConverterHQ w HQTools i nadaj tylko scope Files, Jobs i capabilities potrzebne do quickstartu.

3

Kontrola gotowości

Zweryfikuj kontekst

Wywołaj GET /v1/me i sprawdź environment, project_id, scopes oraz limits przed wysłaniem pliku, aby nie mieszać sandbox i produkcji.

4

Pierwsza konwersja

Prześlij bezpośrednio do storage i uruchom prawdziwy Job.

Utwórz File, wyślij bajty metodą PUT na podpisany URL storage, zakończ File, wyślij Job i pobierz wynik. Bajty pliku nie przechodzą przez proces API ConverterHQ.

Zweryfikuj powyżej klucz sandbox lub live, aby włączyć konwersję prowadzoną.

Pierwsza konwersja 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"