ConverterHQDevelopers
Activation développeur

Validez l’API dans le sandbox. Passez en production seulement quand vous êtes prêt.

Du compte au premier appel API, puis à la production sans perdre le contexte.

Commencez par un projet sandbox et une clé de test à portée limitée. Validez un vrai transfert direct vers le stockage avant de souscrire à un plan de production.

Transport en production : les octets du fichier local sont envoyés directement vers le stockage objet signé via l’API Files, puis les conversions référencent l’identifiant File détenu. Le plan de contrôle API reçoit les métadonnées et les identifiants, pas les octets du fichier local.

1

Accès sandbox

Accès sandbox et production

Une clé hq_test_... liée à un projet ouvre le sandbox avec des limites d’évaluation. Les clés hq_live_... restent réservées aux comptes disposant d’un abonnement API actif.

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
Portées complètes
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

Vérification

Créer une clé avec la portée minimale

Créez d’abord un projet ConverterHQ dans HQTools, puis une clé limitée aux Files, Jobs et capabilities nécessaires au quickstart. Ajoutez des portées seulement quand votre intégration en a besoin.

3

Contrôle de préparation

Vérifier le contexte

Appelez GET /v1/me pour confirmer environment, project_id, scopes et limits avant d’envoyer un fichier. Cette vérification évite de mélanger sandbox et production.

4

Première conversion

Téléversez directement vers le stockage et exécutez un vrai Job.

Allouez un File, envoyez les octets avec PUT vers son URL de stockage signée, finalisez le File, soumettez un Job puis téléchargez le résultat. Les octets du fichier ne traversent pas le processus API ConverterHQ.

Vérifiez une clé sandbox ou live ci-dessus pour activer la conversion guidée.

Première conversion 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"