Dans l’API CloudRaker: un seul pipeline, du PDF brut au document signé

CloudRaker, c’est l’infrastructure de la paperasse. C’est le slogan. Voici ce que ça veut dire en code.

Retour aux notes

La plupart des API documentaires résolvent une seule étape du problème. Vous obtenez un moteur OCR, ou un modèle d’extraction structurée, ou un outil de signature électronique, et vous branchez le reste vous-même: code de mapping entre fournisseurs, logique de reprise quand une étape échoue, et aucune source unique de vérité sur ce qui est arrivé à un document de l’admission à la validation.

CloudRaker expose tout le flux (parse, extract, redact, fill, sign, et transfert à un humain ou à un agent) comme une seule API, appelable en étapes individuelles ou chaînée en un seul appel de pipeline avec un run id. Ce billet montre comment ça marche, avec un vrai flux de bout en bout.

La forme de l’API

Tout vit derrière une seule passerelle:

Base URL:      https://api.cloudraker.com
Auth:          Authorization: Bearer <org_api_key>
Format:        JSON in, JSON out
Rate limit:    ≥ 67 requests/minute per organization, shared across all endpoints

Une clé, une org. La passerelle résout votre organisation à partir du jeton, autorise l’appel et dispatch vers la capacité que vous visez; vous ne passez jamais d’id d’organisation vous-même. Des SDK existent pour TypeScript et Python si vous préférez ne pas écrire les appels HTTP à la main.

Le cas d’usage: onboarding d’un nouveau contrat fournisseur

Pour rendre ça concret, voici un flux qu’une équipe d’approvisionnement ou de legal-ops exécute constamment: un nouveau fournisseur envoie un contrat signé en PDF scanné, et avant qu’il entre dans le système d’enregistrement, quelqu’un doit le lire, en tirer les termes clés, retirer tout ce qui est sensible et ne devrait pas être stocké brut, générer une feuille de couverture d’approbation interne, obtenir une validation conformité, et collecter une contre-signature finale.

Fait à la main, ça fait quatre ou cinq personnes qui touchent le même document sur quelques jours. Voici à quoi ça ressemble comme un seul pipeline CloudRaker.

Étape 1 — Enregistrer le fichier

Chaque exécution part d’un fichier enregistré, pas d’un téléversement brut à chaque fois. Pointez CloudRaker vers le document une fois, par URL ou téléversement présigné, et réutilisez-le à chaque étape suivante: il est parsé une seule fois, pas une fois par capacité.

curl -X POST https://api.cloudraker.com/v1/files \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://vendor-portal.example.com/contracts/acme-msa.pdf",
    "name": "Acme MSA - signed"
  }'

Étape 2 — Le parser en texte propre

Pas de schéma ici: transformez simplement le PDF scanné en markdown propre ou en JSON structuré pour que chaque étape suivante travaille avec du texte, pas des pixels.

curl -X POST https://api.cloudraker.com/v1/parse \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -d '{ "file_id": "file_9f2a..." }'

Étape 3 — Extraire les termes qui comptent

C’est là que le modèle d’extraction de CloudRaker gagne sa place: donnez-lui un JSON Schema décrivant ce qui vous importe, et il renvoie des données façonnées exactement comme ce schéma, avec une citation page-et-région derrière chaque champ, pour que rien ne soit une boîte noire.

curl -X POST https://api.cloudraker.com/v1/extract \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -d '{
    "file_id": "file_9f2a...",
    "schema": {
      "type": "object",
      "properties": {
        "counterparty": { "type": "string" },
        "term_months": { "type": "integer" },
        "renewal_notice_days": { "type": "integer" },
        "payment_terms": { "type": "string" }
      }
    }
  }'

La réponse inclut une référence source pour chaque champ (p. 4, p. 6), le même modèle de citation que vous verriez dans la grille d’extraction du produit lui-même. Cette traçabilité compte ici plus que la seule exactitude: une équipe juridique peut vérifier un champ en quelques secondes au lieu de relire tout le contrat.

Étape 4 — Caviarder avant le stockage

Les contrats portent souvent des renseignements personnels du signataire qui ne devraient pas séjourner non caviardés dans un système d’archives généraliste. Retirez-les avant que le document aille plus loin en aval:

curl -X POST https://api.cloudraker.com/v1/redact \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -d '{ "file_id": "file_9f2a...", "targets": ["signatory_personal_info"] }'

Étape 5 — Remplir la feuille de couverture interne

Prenez les champs extraits à l’étape 3 et remplissez votre propre modèle d’approbation interne, sans retaper manuellement les mêmes données dans un second document.

curl -X POST https://api.cloudraker.com/v1/fill \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -d '{
    "template_id": "tmpl_approval_cover_v4",
    "values": { "client_name": "Acme Corp", "term_months": 36 }
  }'

Étape 6 — Transférer pour validation conformité (agent run)

C’est l’étape à laquelle la plupart des produits «API documentaire» n’ont pas de réponse. Un réviseur conformité doit valider avant que le contrat soit final, et vous voulez qu’un agent gère la coordination plutôt qu’une personne qui court après des messages Slack. Une exécution d’agent gère exactement ça: un processus multi-étapes sur un ensemble de fichiers qui s’arrête pour une validation humaine et reprend quand on la lui donne.

curl -X POST https://api.cloudraker.com/v1/agent-runs \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -d '{
    "file_ids": ["file_9f2a..."],
    "workflow": "contract-compliance-review",
    "assignee": "compliance-team"
  }'

Votre application interroge l’exécution (ou mieux, l’écoute) plutôt que de bâtir sa propre machine à états pour «en attente d’un humain.»

Étape 7 — Collecter la signature finale

Une fois la conformité validée, le contrat part en signature électronique, avec une piste d’audit scellée derrière:

curl -X POST https://api.cloudraker.com/v1/sign \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -d '{ "file_id": "file_9f2a...", "signer_email": "legal@acme.example.com" }'

Ou: le tout, en un seul appel

Les étapes 2 à 5 (et, selon votre flux, plus loin) n’ont pas à être des allers-retours séparés. Un pipeline exécute plusieurs capacités sur un ensemble de fichiers en un seul appel: un run id, un résultat à interroger, et le fichier n’est parsé qu’une seule fois peu importe le nombre d’étapes qui suivent:

curl -X POST https://api.cloudraker.com/v1/pipelines \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -d '{
    "file_id": "file_9f2a...",
    "steps": ["parse", "extract", "redact", "fill"],
    "schema": { "...": "as above" }
  }'

Le différenciateur: ce n’est pas la colle de cinq fournisseurs et cinq endroits où quelque chose peut échouer en silence entre les étapes. C’est une exécution, un statut à vérifier, un endroit où vit la piste d’audit.

Étape 8 — Savoir quand c’est terminé

Plutôt que de sonder en boucle, abonnez-vous à des webhooks signés et réagissez aux événements d’exécution au fur et à mesure. Chaque livraison est un JWT signé par clé publique que vous vérifiez contre un JWKS publié, donc aucun secret partagé nulle part dans une variable d’environnement:

import { CloudRaker } from "@cloudraker/sdk";

const client = new CloudRaker({ apiKey: process.env.CLOUDRAKER_API_KEY });

app.post("/webhooks/cloudraker", async (req, res) => {
  const event = await client.webhooks.verify(req.body, req.headers);
  if (event.type === "run.completed") {
    // move the fully processed, signed contract into the system of record
  }
  res.sendStatus(200);
});

Ce que ça enlève

Exécutez le même flux sans CloudRaker et vous intégrez: un fournisseur OCR/parsing, un modèle d’extraction séparé (ou une couche prompt-et-parse maison), une étape de caviardage que vous bâtissez probablement vous-même, un outil de formulaires, un moteur de flux pour l’étape conformité humain-dans-la-boucle, et une API de signature électronique, chacun avec sa propre auth, ses propres limites de débit, ses propres modes d’échec, et un ensemble de code-colle au milieu que personne n’aime maintenir.

Le pipeline ci-dessus remplace toute cette pile par une poignée d’appels API contre une seule passerelle. C’est le sens derrière «infrastructure de la paperasse»: pas un parser plus lisse, mais la plomberie que vous auriez autrement à bâtir vous-même, déjà bâtie.

Où aller ensuite

Si vous maintenez aujourd’hui votre propre version de la pile ci-dessus, on aimerait savoir où ça fait le plus mal; c’est ce feedback qui oriente ce qu’on bâtit ensuite.

À lire ensuite

Tous les articles