Votre premier PDF avec l’API Docoki.

1. Préparer votre accès

Utilisez Node.js 24 pour TypeScript ou Python 3.11 et plus. Munissez-vous de l’adresse API de votre environnement. Dans Vos clés API, créez une clé dédiée à cet essai et copiez l’identifiant de votre espace.

Accordez assets:read, assets:write, jobs:read et jobs:write. Ajoutez usage:read pour consulter la consommation. Aucun autre droit n’est nécessaire pour ce tutoriel. Conservez la clé dans un gestionnaire de secrets et exécutez le SDK sur votre serveur.

Le script envoie le PDF après votre lancement explicite, réserve au maximum 1 DU et consomme 1 DU en cas de réussite. Le dépôt et le devis ne débitent aucune unité. Le fichier et le résultat sont temporaires : téléchargez-les avant leur expiration de deux heures.

2. Télécharger les ressources

Choisissez le SDK et son exemple, puis enregistrez le PDF d’essai dans le même répertoire. Installez l’archive correspondant au client choisi avec les commandes ci-dessous.

• Référence de l’API (OpenAPI)
• SDK TypeScript 0.2.0
• SDK Python 0.2.0
• Exemple TypeScript
• Exemple Python
• PDF synthétique d’essai
• Récepteur webhook TypeScript
• Récepteur webhook Python
• Empreintes SHA-256 des téléchargements

La référence de l’API décrit les opérations, leurs paramètres et leurs réponses. Les empreintes SHA-256 permettent de vérifier l’intégrité des ressources téléchargées.

3. Installer et lancer l’exemple

Les commandes suivantes utilisent PowerShell 7. La saisie de la clé est masquée et reste dans l’environnement du processus. Renseignez l’adresse HTTPS de votre API avant de lancer l’exemple.

npm install ./docoki-sdk-0.2.0.tgz
$env:DOCOKI_API_URL = Read-Host "Adresse HTTPS de votre API Docoki"
$env:DOCOKI_WORKSPACE_ID = "identifiant de votre espace"
$env:DOCOKI_API_KEY = Read-Host -MaskInput "Clé API de votre essai"
$env:DOCOKI_SAMPLE_FILE = "sample.pdf"
$env:DOCOKI_RUN_DIR = "docoki-essai-typescript"
node tutorial.ts
Remove-Item Env:DOCOKI_API_KEY

python -m venv .venv
.venv\Scripts\python.exe -m pip install ./docoki_sdk-0.2.0-py3-none-any.whl
$env:DOCOKI_API_URL = Read-Host "Adresse HTTPS de votre API Docoki"
$env:DOCOKI_WORKSPACE_ID = "identifiant de votre espace"
$env:DOCOKI_API_KEY = Read-Host -MaskInput "Clé API de votre essai"
$env:DOCOKI_SAMPLE_FILE = "sample.pdf"
$env:DOCOKI_RUN_DIR = "docoki-essai-python"
.venv\Scripts\python.exe tutorial.py
Remove-Item Env:DOCOKI_API_KEY

Le script dépose le PDF, reprend un transfert interrompu si nécessaire, attend que le fichier soit prêt et prépare un devis. Il conserve la demande et sa clé d’idempotence dans state.json avant le lancement, puis suit l’avancement du traitement.

À la fin, le répertoire d’essai contient resultat.pdf, resultats.zip et manifest.json. Le PDF contient la première page tournée de 90°. Le SDK vérifie sa taille et son empreinte. La sortie console indique l’identifiant du traitement, son état et la DU consommée.

4. Reprendre une réponse incertaine

Relancez le même exemple, avec la même source, le même espace et le même répertoire. Les parties présentes sont réutilisées. Le lancement reprend le même corps et la même clé d’idempotence : Docoki retrouve le traitement accepté sans second débit.

Gardez state.json pendant la reprise ; il contient des identifiants et le hash de la source, sans clé API ni mot de passe. Pour une nouvelle opération volontaire, utilisez un nouveau répertoire. Après un arrêt forcé, vérifiez qu’aucun processus du script ne tourne avant de retirer son fichier run.lock.

Un devis expire après cinq minutes. Si le serveur confirme ESTIMATE_EXPIRED pour une demande jamais acceptée, préparez un nouvel essai explicitement. Un fichier expiré nécessite un nouveau dépôt. Interrompre le suivi arrête l’attente ; l’annulation d’un traitement se demande séparément avec cancelJob ou cancel_job.

5. Comprendre une erreur

DocokiError expose le code, le statut HTTP, l’identifiant de requête et le délai Retry-After numérique. Journalisez ces seuls champs pour le diagnostic. Les SDK refusent les redirections et ne transmettent jamais votre clé aux URLs de stockage.

6. Terminer votre essai

Supprimez source et résultats depuis Dépôt serveur, ou avec deleteAsset / delete_asset, puis révoquez la clé dédiée depuis Développeurs. La révocation bloque les prochains appels et laisse les traitements déjà acceptés suivre leur cycle normal.

Pour poursuivre vos essais, créez une nouvelle clé dédiée et choisissez un nouveau répertoire pour chaque nouvelle opération.

7. Recevoir un webhook signé

Créez un webhook depuis Vos webhooks, enregistrez son secret et choisissez son identifiant au lancement via webhook_endpoint_id. Utilisez une URL HTTPS publique sur le port 443. L’adresse de réception doit être accessible publiquement ; les adresses locales ou privées sont refusées.

Les exemples TypeScript et Python vérifient Docoki-Signature sur les octets bruts avant de parser le JSON. Le timestamp est accepté dans une fenêtre de cinq minutes ; le Docoki-Event-Id doit correspondre au payload. Les exemples enregistrent chaque événement vérifié avant de confirmer sa réception. Un doublon reçoit aussi 204, sans second effet.

verifyWebhook(rawBody, signatureHeader, eventIdHeader, signingSecret, {workspaceId})
verify_webhook(raw_body, signature_header, event_id_header, signing_secret, workspace_id=workspace)

Injectez DOCOKI_WEBHOOK_SECRET et DOCOKI_WORKSPACE_ID dans l’environnement du récepteur ; conservez sa base de reçus au moins pendant les trente jours de conservation des événements. Ne journalisez ni secret, ni signature, ni corps. Un 2xx acquitte la livraison ; les autres réponses et erreurs réseau déclenchent des reprises bornées à six tentatives.

Le journal dans Développeurs permet d’avancer une reprise déjà en attente, dans le budget restant. Une livraison livrée ou épuisée ne peut pas être remise à zéro. Le suivi du traitement et des fichiers fonctionne indépendamment de la livraison.