Aller au contenu principal

Trouvez votre prochain outil

Documentation/Premiers pas/Prise en main de l’API : première conversion
Premiers pas

Prise en main de l’API : première conversion

Créez une clé API, envoyez un fichier, attendez la fin de la tâche et téléchargez le résultat, avec des requêtes prêtes à copier-coller.

Réponse courte

Créez une clé dans Tableau de bord → API et clés, puis envoyez POST https://maxscanner.app/api/v1/jobs/ avec l’URL publique d’un fichier, un nom de fichier et le format cible. L’API renvoie immédiatement un jobId ; interrogez GET /api/v1/jobs/{jobId}/ toutes les quelques secondes jusqu’à ce que status vaille "completed", puis téléchargez output.downloadUrl dans les cinq minutes.

Démarrage rapide

  1. 1Ouvrez Tableau de bord → API et clés, choisissez « Créer une clé API », cochez « Traiter des fichiers » et copiez la clé (elle n’est affichée qu’une seule fois).
  2. 2Stockez la clé dans une variable d’environnement, par exemple MAXSCANNER_API_KEY — jamais dans du code côté client.
  3. 3Envoyez POST /api/v1/jobs/ avec url, filename et format. Conservez le jobId de la réponse 202.
  4. 4Appelez GET /api/v1/jobs/{jobId}/ toutes les 2 à 10 secondes jusqu’à ce que status vaille completed ou failed.
  5. 5Téléchargez output.downloadUrl sans attendre : le lien signé expire au bout de cinq minutes.

Avant de commencer

Chaque requête est adressée à https://maxscanner.app/api/v1/ et transmet la clé comme jeton Bearer. Les URL de requête se terminent par une barre oblique : une URL sans barre oblique reçoit une redirection 308 que la plupart des clients HTTP suivent, mais l’ajouter vous épargne un aller-retour.

L’offre gratuite autorise 10 requêtes par jour et 100 par mois, ce qui suffit pour développer et tester une intégration. Les offres payantes fonctionnent avec des crédits mensuels ; chaque endpoint coûte de 0 à 3 crédits.

  • URL de base : https://maxscanner.app/api/v1/
  • En-tête : Authorization: Bearer <your key>
  • Corps : JSON avec Content-Type: application/json
  • Fichiers : jusqu’à 50 Mo, par import d’URL ou envoi direct

Convertir un fichier Word en PDF

L’endpoint des tâches choisit le bon processeur d’après les formats d’entrée et de sortie. Transmettez une URL publique et le serveur télécharge lui-même le fichier à la création de la tâche (jusqu’à 50 Mo en 30 secondes ; les redirections ne sont pas suivies, utilisez donc le lien final du fichier) ; pour un fichier privé, utilisez plutôt un envoi direct et transmettez sourceKey (voir le guide Fichiers et envois). Ajoutez un en-tête Idempotency-Key pour qu’une requête relancée ne crée jamais une seconde tâche.

curl -X POST 'https://maxscanner.app/api/v1/jobs/' \
  -H "Authorization: Bearer $MAXSCANNER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: quickstart-0001' \
  -d '{ "url": "https://example.com/report.docx", "filename": "report.docx", "format": "pdf" }'

Attendre le résultat

Les tâches sont asynchrones afin que les gros fichiers ne bloquent jamais votre connexion HTTP. Interrogez l’URL de statut en commençant toutes les 2 secondes environ, puis en espaçant les appels jusqu’à 10 secondes. Un petit fichier Office est généralement traité en moins de 20 secondes ; une vidéo 1080p peut prendre plusieurs minutes. Quand status vaut completed, output indique le type de contenu, la taille en octets et un downloadUrl signé.

curl 'https://maxscanner.app/api/v1/jobs/6f0c2a6e-8a1b-4a53-9a0e-2b1f4c9d7e11/' \
  -H "Authorization: Bearer $MAXSCANNER_API_KEY"

Étapes suivantes

Passez de l’interrogation à un webhook dès que vous traitez plus d’une poignée de fichiers, lisez le guide des tâches pour les règles de nouvelle tentative, puis choisissez le guide qui correspond à votre besoin : OCR, outils PDF, images, médias ou exécution d’un workflow enregistré.

Questions fréquentes

Dois-je installer un SDK ?

Non. L’API repose simplement sur HTTPS et JSON : tout langage ou outil no-code capable d’envoyer une requête HTTP convient. Le guide des exemples de code propose des versions complètes en Node.js, Python, PHP et cURL.

Combien de temps un lien de téléchargement reste-t-il valide ?

Cinq minutes. S’il a expiré, redemandez le statut de la tâche pour obtenir un nouveau lien.

Existe-t-il un mode test ?

Utilisez l’offre gratuite pour vos tests : elle donne accès aux mêmes endpoints et limite chaque compte à 10 requêtes par jour et 100 par mois.

Guides associés