Métadonnées de suivi

Les métadonnées associent à chaque traitement des informations de suivi fournies par votre logiciel métier. Elles sont conservées sur le run et héritées par ses sous-workflows. Elles sont distinctes de l’entrée métier et du JSON CDJ Connect 1.2 : ne les ajoutez pas au schéma métier.

Identifier le client

Le workflow d’intégration accepte la métadonnée facultative client_id : l’identifiant du client pour lequel votre logiciel métier soumet la demande. Un appel sans métadonnées reste valide.

Conservez les zéros initiaux. "0042" et "42" sont deux valeurs différentes lors d’une recherche exacte. Ne convertissez pas cet identifiant en nombre.

Les métadonnées passent par le champ réservé _raydocs.metadata. Un client_id placé directement dans le payload métier n’est pas automatiquement une métadonnée du run.

Transmettre avec des fichiers

Pour l’envoi des documents, ajoutez un champ texte _raydocs contenant le JSON ci-dessous au même multipart/form-data. Répétez files[] pour chaque fichier. --form-string transmet le JSON comme du texte.

curl -X POST "https://api.raydocs.com/webhooks/workflows/{WEBHOOK_PUBLIC_UUID}" \
  -H "Authorization: Bearer {RAYDOCS_API_TOKEN}" \
  -H "Accept: application/json" \
  -F "files[]=@./document.pdf;type=application/pdf" \
  --form-string '_raydocs={"metadata":{"client_id":"0042"}}'

Ne fixez pas manuellement le Content-Type multipart : laissez votre client générer la boundary. Vous pouvez ajouter dans le même envoi le champ indépendant et facultatif notification_url.

Transmettre dans un corps JSON

Pour une requête au format JSON, _raydocs est un objet, et non une chaîne JSON sérialisée. L’extrait suivant montre uniquement l’enveloppe de métadonnées ; il ne remplace pas les fichiers nécessaires à l’analyse des documents ni les autres entrées attendues par le workflow.

{
  "_raydocs": {
    "metadata": {
      "client_id": "0042"
    }
  }
}

L’enveloppe réservée est séparée des données métier avant le traitement. Ce fragment est un exemple de transport Raydocs, pas un lot CDJ Connect complet.

Suivre et retrouver les traitements

Conservez l’association entre votre demande, son client_id et le RUN_ID retourné à l’envoi. Le RUN_ID reste l’identifiant à utiliser pour consulter le statut, récupérer le résultat et renouveler un lien de téléchargement.

Les métadonnées permettent de retrouver les runs par filtre exact dans Raydocs : une recherche de client_id égal à "0042" ne sélectionne pas "42". Les sous-workflows héritent des métadonnées du parent, ce qui conserve le contexte client pendant le traitement.

La notification webhook conserve son enveloppe run_id, status, output, en succès comme en échec. Elle n’ajoute automatiquement ni client_id, ni metadata, ni event_id. Retrouvez le client à partir de l’association conservée avec le run_id parent. Contrairement aux métadonnées, notification_url n’est pas héritée par les sous-workflows : seul le parent notifie.

Limites et validation

Des métadonnées invalides provoquent une réponse HTTP 422 avant la création du run. Aucun RUN_ID ni callback de fin de traitement n’est alors produit. Corrigez la requête avant de la soumettre de nouveau ; les bonnes pratiques détaillent la gestion des erreurs.

Identité et confidentialité

Les métadonnées sont déclarées par votre logiciel métier. Elles servent au suivi et à la recherche ; elles ne prouvent pas l’identité du client ou de l’appelant et ne donnent aucun droit d’accès. La provenance utilisateur et token est déterminée séparément côté serveur, à partir de l’authentification.

N’y transmettez aucun secret : ni token API, ni mot de passe, ni URL signée de notification ou de téléchargement. Utilisez un identifiant client stable et limitez les données aux besoins du suivi.