Envoyer les documents

POST — Transmettre les fichiers d’une demande et démarrer leur traitement.

POST https://api.raydocs.com/webhooks/workflows/{WEBHOOK_PUBLIC_UUID}

Envoyer les fichiers d’une même demande et obtenir un identifiant de suivi. Consultez l’authentification pour configurer le token. Pour recevoir le résultat par webhook, vous pouvez ajouter le champ texte facultatif notification_url au même envoi.

Paramètres de la requête

Paramètre	Emplacement	Type	Obligatoire	Description
`WEBHOOK_PUBLIC_UUID`	Chemin de l’URL fournie	UUID	Oui	Identifiant du webhook configuré.
`files[]`	Corps multipart	Fichier répété	Oui	Un ou plusieurs fichiers de la même demande.
`notification_url`	Corps multipart	Texte	Non	URL de réception des notifications, activées sur le workflow d’intégration publié.
`_raydocs`	Corps multipart	Texte JSON	Non	Enveloppe des métadonnées de suivi, par exemple `client_id`.
`erp_reference`, `source`	Corps multipart	Champs métier	Non	Informations additionnelles disponibles dans l’entrée du workflow.

Ne fixez pas manuellement le Content-Type multipart : laissez votre client produire la boundary.

Pour rattacher la demande à un client, transmettez client_id dans _raydocs.metadata, en conservant sa valeur sous forme de chaîne : voir les exemples JSON et multipart. Un champ client_id au premier niveau du payload métier ne crée pas une métadonnée du run. Les métadonnées sont facultatives.

Corps de la requête

Utiliser multipart/form-data avec le champ fichier files[]. Répéter ce champ pour chaque fichier ; pour un seul fichier, utiliser également files[]. Les fichiers sont envoyés en binaire, avec leur nom et leur type MIME.

Formats acceptés

Format	Traitement
PDF, PNG, JPEG	Analyse des documents et restitution des pièces.
EML, MSG	Extraction du corps et des pièces jointes ; original conservé.
DOC, DOCX	Conversion en PDF pour l’analyse ; original conservé.
XLSX	Conservation du fichier Excel téléchargeable.
ZIP	Extraction des documents pris en charge ; archive et fichiers sources conservés.

Les emails présents dans un ZIP restent des fichiers sources : ils ne sont pas analysés automatiquement comme de nouveaux emails. Convertissez les images TIFF/WebP en PNG, JPEG ou PDF et les fichiers XLS en XLSX.

Limites de transfert

Exemples de requête

Un document PDF

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" \
  -F "erp_reference=DOSSIER-12345"

Avec notification facultative

Ajoutez le champ texte notification_url (au singulier) dans le même multipart/form-data. Utilisez de préférence une URL unique par demande, signée et temporaire côté logiciel métier : voir les bonnes pratiques de sécurisation du retour. Exemple fictif :

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" \
  -F "erp_reference=DOSSIER-12345" \
  --form-string "notification_url=https://logiciel-metier.example.com/raydocs/notifications?job=12345&expires={EXPIRATION_NOTIFICATION}&signature={SIGNATURE_NOTIFICATION}"

Une valeur absente, vide ou composée uniquement d’espaces ne déclenche aucune notification : le polling reste utilisable. La destination doit être HTTPS publique sur le port 443, sans redirection. Consultez le contrat de notification et les exemples de réception.

Plusieurs documents de la même demande

Répétez files[] pour chaque fichier, quel que soit son rôle. Les pièces peuvent être envoyées séparément ou incluses dans un email EML/MSG.

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" \
  -F "files[]=@./piece-complementaire.pdf;type=application/pdf" \
  -F "erp_reference=DOSSIER-12345"

Les pièces du résultat sont référencées dans dossiers[].pieces_jointes[] avec leur file_id. Les champs additionnels, comme erp_reference, client_id ou source, sont disponibles dans l’entrée du workflow.

Emails EML et MSG

Envoyez l’email dans files[] avec le type MIME message/rfc822 pour un EML ou application/vnd.ms-outlook pour un MSG. Vous pouvez joindre des fichiers complémentaires dans le même appel.

Le corps et les pièces jointes sont extraits ; l’original reste téléchargeable dans extensions_prestataire.RAYDOCS.fichiers_sources[]. Les emails joints restent des fichiers distincts. Une perte de contenu ou un email illisible peut provoquer EMAIL_PARSING_INCOMPLETE.

curl -X POST "https://api.raydocs.com/webhooks/workflows/{WEBHOOK_PUBLIC_UUID}" \
  -H "Authorization: Bearer {RAYDOCS_API_TOKEN}" \
  -H "Accept: application/json" \
  -F "files[]=@./message.msg;type=application/vnd.ms-outlook" \
  -F "files[]=@./piece.pdf;type=application/pdf"

Réponse — `202 Accepted`

{
  "id": "{RUN_ID}",
  "status": "pending",
  "trigger_node_id": "webhook_trigger"
}

Conserver id: c'est l'identifiant du run à utiliser pour les appels de statut, de résultat et de demande de lien de téléchargement.

Champ retourné	Description
`id`	Identifiant `RUN_ID` à conserver.
`status`	État initial annoncé dans cette réponse.
`trigger_node_id`	Identifiant technique du déclencheur.

Erreurs et suite du parcours

Un transfert invalide, des métadonnées invalides ou un dépassement des limites est rejeté avec HTTP 422, avant création du run. Aucune notification n’est envoyée pour cette requête rejetée. Corrigez la requête avant de la renvoyer. Les erreurs d’analyse après réception apparaissent dans le traitement : voir les bonnes pratiques et erreurs.

Après réception du RUN_ID, attendez la notification si elle est configurée, ou consultez le statut. Le statut et le résultat restent disponibles pour reprendre si le callback n’arrive pas. Une nouvelle soumission crée un nouveau traitement ; elle ne reprend pas le précédent.