Numérisation par API

La numérisation par API transforme un PDF en copie numérisée réaliste via un appel REST, ce qui convient aux traitements automatisés et aux intégrations applicatives. Créez la tâche, importez le PDF, puis interrogez le statut ou attendez le webhook : trois étapes, depuis n'importe quel environnement ou langage capable d'envoyer une requête HTTP. L'espace colorimétrique, la résolution, la rotation, le flou, le bruit, la luminosité, le contraste et la bordure se règlent librement.

Déroulé d'un appel

  1. Créer la tâche

    POST /v1/scan-jobs

    Envoyez votre config et, si vous le souhaitez, un webhookUrl ; vous recevez un jobID et une uploadURL présignée.

  2. Importer le PDF

    PUT {uploadURL}

    Faites un PUT du fichier directement vers l'adresse S3 présignée de l'étape précédente : aucun jeton n'est nécessaire.

  3. Récupérer la copie numérisée

    GET /v1/scan-jobs/{jobID}

    Interrogez le statut ou attendez le webhook ; une fois la tâche completed, téléchargez-la depuis downloadURL.

Cas d'usage

Production par lot côté serveur

Les contrats, factures et rapports générés sur le serveur passent directement par l'effet de numérisation, sans que personne refasse l'opération à la main sur la page web.

Dans un système existant

Ajoutez une action « exporter une copie numérisée » à un CRM, un ERP ou un outil de tickets, et laissez-le appeler l'API.

Chaînes d'automatisation

CI, n8n, Zapier et consorts lancent une tâche sur un événement, et le webhook enchaîne sur l'étape suivante une fois terminé.

Files de fichiers volumineuses

Les tâches sont asynchrones : créez-les et chacune est traitée de son côté, l'avancement restant consultable via status et createdAfter.

Langages et environnements

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLLigne de commande / CI
PlusN'importe quel client HTTP

L'API repose sur HTTP et JSON standard : tout langage ou toute plateforme d'automatisation capable d'envoyer une requête peut l'appeler.

Exemples de code

API Bearer Token

Le jeton est rattaché à votre compte et peut être régénéré à tout moment. La numérisation par API exige un compte Pro : sans jeton valide l'API répond 401, et sans le rôle Pro elle répond 403.

Essayer

Réglez les paramètres, regardez le corps de la requête suivre, puis lancez les trois appels vers l’API.

Paramètres de numérisation

L’essai appelle l’API avec votre jeton et exige un compte Pro ; les paramètres et le corps de la requête restent librement consultables.

POST/v1/scan-jobs
{
  "config": {
    "rotate": 1,
    "rotate_var": 0.5,
    "colorspace": "gray",
    "blur": 0,
    "noise": 0,
    "border": false,
    "brightness": 1.3,
    "contrast": 1.3,
    "resolution": 150,
    "output_format": "image/jpeg"
  }
}

Informations sur la tâche de numérisation

exemple
{
  "jobID": "3f9c1e64-0000-4000-8000-00000000a71b",
  "userID": "8f21c4b0-0000-4000-8000-000000004a17",
  "createdAt": 1724409600,
  "status": "completed",
  "inputUploadedAt": 1724409601,
  "completedAt": 1724409602,
  "numPages": 6,
  "downloadURL": "https://…/output/3f9c.pdf?X-Amz-…"
}

Référence de l'API

MéthodeCheminDescription
POST/v1/scan-jobsCrée une tâche de numérisation. Envoyez config et, si besoin, webhookUrl ; vous recevez l'objet de la tâche avec le statut created et une uploadURL présignée.
PUT{uploadURL}L'adresse S3 présignée de l'étape précédente, qui ne se trouve pas sur api.lookscanned.ioEnvoie le PDF source avec Content-Type: application/pdf et Content-Length. L'adresse porte sa propre signature : n'ajoutez pas d'en-tête Authorization.
GET/v1/scan-jobs/{jobID}Lit une seule tâche, pour l'interrogation périodique. En created, elle contient uploadURL ; en completed, downloadURL.
GET/v1/scan-jobsListe vos propres tâches, filtrées par jobID, status ou createdAfter.
Statutcreatedprocessingcompletedfailed
  • 401 aucun jeton valide
  • 403 le compte n'est pas Pro
  • 404 tâche introuvable

Corps de la requête

ChampTypePar défautDescription
webhookUrlstring · —Appelé une fois la tâche terminée, ce qui évite d’avoir à interroger le statut.
config.colorspace'gray' | 'sRGB' · graygrayEspace colorimétrique de l'image produite ; gray correspond à une numérisation en noir et blanc.
config.resolutionnumber · 7272Résolution de l'image produite, en PPP.
config.rotatenumber · —Rotation de tout le document, en degrés.
config.rotate_varnumber · —Amplitude de la rotation aléatoire page par page, en degrés : l'aspect d'une feuille posée de travers.
config.blurnumber · 00Intensité du flou.
config.noisenumber · 00Intensité du bruit.
config.brightnessnumber · 11Luminosité ; 1 ne change rien.
config.contrastnumber · 11Contraste ; 1 ne change rien.
config.borderboolean · falsefalseAjouter ou non une bordure de numérisation à la page.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegFormat d'image dans lequel les pages sont rendues.

Tous les champs sont facultatifs. Les valeurs de départ d'« Essayer » (résolution 150, rotation 1, luminosité et contraste 1,3) sont la combinaison recommandée par l'application web, pas les valeurs par défaut de l'API.

Champs à surveiller dans l'objet de la tâche

status
created / processing / completed / failed : détermine la présence des deux adresses ci-dessous.
uploadURL
Uniquement tant que la tâche est created. Adresse d'import présignée, à durée limitée.
downloadURL
Uniquement une fois la tâche completed. Adresse de téléchargement présignée, à durée limitée.
inputUploadedAt / completedAt
Fin de l'import du fichier source et fin de la tâche ; l'écart donne la durée de traitement.

Questions fréquentes

La numérisation par API nécessite-t-elle Pro ?

Oui. Sans jeton valide l'API répond 401, et un compte sans le rôle Pro reçoit 403. Une fois l'offre Pro souscrite et la session ouverte, le jeton s'affiche sur cette page.

Comment savoir qu'une tâche est terminée ?

De deux manières : interroger GET /v1/scan-jobs/{jobID}, ou transmettre un webhookUrl à la création de la tâche et laisser le service vous rappeler une fois.

Le résultat est-il identique à celui de la page web ?

Oui. Les deux utilisent la même implémentation de l'effet de numérisation, et l'espace colorimétrique, la résolution, la rotation, le flou, le bruit, la luminosité, le contraste et la bordure de config correspondent aux options de même nom sur la page web : à paramètres identiques, résultat identique. Seul l'endroit du traitement diffère — en local sur la page, à distance via l'API.

Puis-je stocker les adresses d'import et de téléchargement pour les réutiliser ?

Mieux vaut éviter. uploadURL et downloadURL sont des adresses présignées à durée limitée ; une fois expirées, il faut relire la tâche pour en obtenir de nouvelles.

Combien de temps prend une tâche ?

Cela dépend du nombre de pages et de la résolution. Quelques pages se terminent généralement en quelques secondes ; une résolution plus élevée ou un document plus long prennent plus de temps. L'écart entre inputUploadedAt et completedAt donne la durée réelle.

Que faire si une tâche échoue ?

Le statut passe à failed. Les causes habituelles sont un fichier qui n'est pas un PDF valide, des restrictions de chiffrement ou un import interrompu. Vérifiez que le fichier s'ouvre, puis créez une nouvelle tâche.

Puis-je consulter les tâches passées ?

Oui. GET /v1/scan-jobs liste vos propres tâches et accepte des filtres sur jobID, status et createdAfter, ce qui suffit pour un rapprochement ou un nouveau téléchargement.