API pour développeurs

API pour développeurs

Connectez votre logiciel par des actions explicites pour les sources, les traitements, les résultats et la gestion. Ce guide décrit l’API disponible dans les limites documentées de cette version. Utilisateur, droits, stockage et crédits restent liés au compte Rapportly.

Préparez votre intégration en trois étapes

1. 1
   Choisir utilisateur, environnement et droits

   Ouvrez Compte → Intégrations. Utilisez une clé de test pour le simulateur fictif et une autre clé de production pour les actions réelles avec des données fictives. L’administrateur attribue les seuls droits nécessaires et un budget adapté.

2. 2
   Essayer les réceptions et les erreurs

   Commencez par le simulateur, puis importez les contrats API et examinez les exemples synthétiques. Gardez les secrets sur votre serveur. Les modifications sont désactivées par défaut dans la collection.

3. 3
   Suivre une demande complète

   Conservez les données et l’identifiant, vérifiez le début et la fin, lisez le résultat, téléchargez un fichier disponible et contrôlez la consommation. Faites cet essai uniquement dans un environnement autorisé.

Créer votre clé API

Adresse de base

https://api.rapportly.io/api/rapportly/v1

La clé appartient à un utilisateur

Une clé délègue les droits d’un utilisateur. L’administrateur définit environnement, plafond de droits, budget mensuel et expiration. Le membre active sa clé préparée et voit le secret une fois. Chaque appel vérifie aussi les droits actuels de l’utilisateur, de l’offre et de l’objet. La gestion des clés utilise une session utilisateur, les actions de production une clé API. Gardez les secrets sur le serveur et révoquez une clé perdue dans Compte → Intégrations. Les événements Zapier ont leur propre contrat.

GET https://api.rapportly.io/api/rapportly/v1/ping
Authorization: Bearer rply_<jouw_sleutel>

Utiliser des contrats et exemples concrets

L’OpenAPI de production décrit les contrats du code source et signale les entrées ou réponses partielles. L’inventaire liste les schémas ouverts. La collection Postman contient une adresse invalide, des clés vides et des modifications désactivées. Importez pour examen, puis envoyez volontairement des données fictives dans un environnement autorisé. L’import n’a pas été testé.

• Télécharger la spécification OpenAPI de production
• Télécharger la collection Postman synthétique
• Télécharger le parcours de la source au téléchargement
• Télécharger l’inventaire des schémas et points ouverts

Commencer par des demandes fictives

Créez une clé de test et exercez votre logiciel aux demandes en cours, résultats, erreurs et budgets insuffisants. Le simulateur utilise des données fixes sans consommer de crédits.

1. Dans Compte → Intégrations, créez ou activez une clé Test avec les droits à essayer.
2. Appelez GET /test/scenarios et choisissez une action renvoyée. La liste tient compte des droits actuels.
3. Envoyez POST /test/opdrachten uniquement avec actie et scenario : succes, verwerking_mislukt, creditbudget_bereikt ou toegang_geweigerd. Chaque nouvelle simulation a son propre Idempotency-Key.
4. Conservez opdracht_id. Pour bezig, lisez GET /test/opdrachten/{id} après environ cinq secondes. Vérifiez toujours l’état : HTTP200 peut contenir un échec de traitement.

POST https://api.rapportly.io/api/rapportly/v1/test/opdrachten
Authorization: Bearer rply_test_<jouw_testsleutel>
Idempotency-Key: test-rapport-0001
Content-Type: application/json

{
  "actie": "rapport.start",
  "scenario": "succes"
}

Cet exemple nécessite rapport.start dans votre liste. Après un problème réseau, répétez les mêmes données et Idempotency-Key.

• Télécharger le guide du simulateur
• Télécharger la collection Postman d’exercice
• Télécharger l’OpenAPI du simulateur

Récupérez uniquement les données nécessaires

Recherchez les dossiers clients, conversations et rapports accessibles. /acties décrit les actions et droits, /gebruik le budget et les réservations, /verzoeken l’historique technique. Un traitement en cours n’a pas encore de résultat. Les liens de rapports expirent après 15 minutes ; relisez le rapport pour en obtenir un nouveau.

Mettre à jour la gestion des clients

Votre logiciel peut modifier les modèles du cabinet, enregistrer des recherches personnelles, consigner une visite et créer un parcours. Utilisez les droits d’administration appropriés et confirmez chaque modification. Lisez d’abord la version actuelle et conservez le même identifiant de requête si la réponse est perdue. La répétition d’une ancienne requête ne doit pas annuler une modification plus récente. Le test en production vérifie les recherches, les visites et les parcours, y compris le nettoyage et la révocation des clés. Les modèles du cabinet y ont uniquement été lus ; leur écriture a été testée localement et en CI. Le guide téléchargeable décrit les quatre routes et les limites des preuves associées.

Comparer deux versions enregistrées

Comparez deux numéros de version existants du même champ de texte de rapport ou de conversation enregistré, sans nouveau traitement par IA. Ce contrat a été testé localement et en CI ; le test CRM en production ne prouve pas le fonctionnement de la comparaison en production. L’historique manquant n’est pas remplacé par le texte actuel. Les différences longues sont tronquées à un maximum de 8000 caractères par côté, avec une indication visible. Cette comparaison ne couvre ni PowerPoint, ni les calculs de devis, ni les lettres d’accompagnement, ni la mise en forme. Les droits de lecture et les conditions de confidentialité en vigueur restent applicables.

Demander une estimation préalable

POST /generatieplan indique étapes et crédits prévus pour rapport, devis ou conversation. Utilisez gebruik:lezen. Le calcul et les paramètres d’équipe sont ceux du site.

Une estimation ne lance rien et ne débite aucun crédit. Ce n’est pas un prix maximum garanti. Affichez les incertitudes, comme les frais de lecture de fichiers encore inconnus. Le lancement revérifie droits et crédits.

Télécharger le guide d’estimation et ses exemples

Lancer un traitement depuis votre logiciel

L’API relie créations de dossiers et documents, téléversements, audio, transcription, dossiers clients, styles, sorties, workflows, Excel et messages ciblés. Chaque route garde ses données, droits, confirmations et contrôles de version. Traitements et décompte des crédits existants s’appliquent. Une réponse de lancement confirme la réception ; consultez ensuite l’état. L’inventaire indique les contrats encore ouverts.

Créer d’abord un dossier

Générez et conservez un UUID. Envoyez PUT /dossiers/{id} avec naam uniquement, au maximum 200 caractères. 201 signifie création, 200 répétition identique. Le dossier appartient à l’utilisateur et à l’organisation de la clé, sans frais de crédits. Une entrée différente renvoie 409 ; un dossier inaccessible ou supprimé, 404. GET /dossiers/{id} lit naam et klant_id avec le droit de lecture.

PUT https://api.rapportly.io/api/rapportly/v1/dossiers/00000000-0000-4000-8000-000000000002
Authorization: Bearer rply_<jouw_sleutel>
Content-Type: application/json

{ "naam": "Voorbeeldproject" }

Rapport, devis ou présentation

Commencez avec dossierId et notities. tier est facultatif : basis, standaard ou max. Sans profil de style, la mise en page est neutre. stijlprofielId, klantId, bronOpnameIds et taal sont facultatifs et soumis aux droits d’accès. Le style doit correspondre au document. Les devis utilisent les paramètres de l’entreprise et une numérotation sûre ; l’API ne les envoie pas au client.

POST https://api.rapportly.io/api/rapportly/v1/rapporten
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-rapport-2026-0001
Content-Type: application/json

{
  "dossierId": "00000000-0000-4000-8000-000000000002",
  "notities": "Team Atlas besprak de training. Noor plant de volgende bijeenkomst op donderdag.",
  "tier": "standaard"
}

Conservez versie_id et suivez GET /rapporten/{versie_id}, y compris pour devis et présentations. À l’état klaar, resultaat contient les fichiers disponibles : export_url pour PDF, export_url_docx pour Word, export_url_pptx pour PowerPoint. Les liens durent 15 minutes. En cas de mislukt, vérifiez traitement et consommation avant tout nouveau lancement avec une autre clé.

Télécharger le parcours de la source au téléchargement

Téléverser vos exemples de style

Transmettez un ensemble complet de un à trois fichiers. Rapportly utilise les mêmes contrôles de fichiers et de styles que le site. Stockage et crédits sont ceux de l’utilisateur associé.

1. Envoyez fichiers, nom, type de document, portée personnelle ou équipe, confirmation explicite et identifiant fixe. Un style d’équipe exige administrateur ou responsable d’équipe.
2. Conservez l’identifiant de réception et consultez l’état. Reçu signifie que l’ensemble complet est stocké ; contrôle de l’aperçu et approbation peuvent suivre.
3. Après interruption, répétez exactement la demande sans créer un deuxième style. Les téléversements incomplets peuvent être repris pendant trente jours, puis sont nettoyés de manière contrôlée.

Télécharger le guide multipart des exemples de style et des erreurs

Connecter calendrier ou boîte mail

L’utilisateur consent lui-même chez Google ou Microsoft. Votre logiciel suit la demande et peut arrêter volontairement la connexion. Mots de passe et jetons du fournisseur ne figurent pas dans la réponse.

Utilisez verbindingen:beheren pour les connexions et agenda:lezen pour les rendez-vous. L’envoi exige aussi un droit d’envoi et une demande explicite.

Conservez numéro de demande, identifiant et base actuelle. Répétez une demande perdue à l’identique ; une ancienne déconnexion ne doit pas supprimer une connexion plus récente.

L’API permet de choisir la boîte mail par défaut avec droits de gestion et d’envoi. Lisez d’abord choix et connexion actuels. Une ancienne répétition ne modifie pas un choix plus récent ; les envois existants gardent leur expéditeur.

Télécharger les étapes de consentement, rendez-vous, déconnexion et reprise

Ensemble de résultats à partir d’une transcription

Envoyez une transcription d’au moins cent caractères. Suivez le résultat grâce à gesprek_id. Champs facultatifs : titel, tier, klantId et taal.

POST https://api.rapportly.io/api/rapportly/v1/gesprekken
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-gesprek-2026-0001
Content-Type: application/json

{
  "transcript": "Team Atlas bespreekt uitsluitend een fictieve oefening. Het team plant een training en verzamelt algemene voorbeeldvragen zonder klantgegevens.",
  "titel": "Kennismaking"
}

Lire les variantes linguistiques existantes

Consultez les résultats linguistiques existants. Les routes de workflow décrites pour démarrer, mettre en pause, reprendre et rétablir le traitement ont été testées localement et en CI ; le test CRM en production ne vérifie pas ce traitement linguistique. Utilisez-les uniquement dans un environnement autorisé à cet effet. L’utilisateur, la clé, la source et les coûts d’origine restent liés à la requête. L’état actuel de la source, les droits, le budget et le règlement vérifié restent requis ; une source expirée ou supprimée n’autorise pas un nouveau démarrage. Le traitement en lot avec une deuxième langue activée reste bloqué, y compris avec des paramètres hérités. La complétion payante d’un résultat de traduction manquant reste exclue.

GET https://api.rapportly.io/api/rapportly/v1/gesprekken/00000000-0000-4000-8000-000000000001/taalvarianten
Authorization: Bearer rply_<jouw_sleutel>

Être informé de la fin d’un traitement

Rapportly peut envoyer des références techniques à votre serveur. Récupérez ensuite le contenu avec les droits de lecture appropriés, sans interroger continuellement la progression.

1. Créez un récepteur HTTPS et enregistrez-le par POST /webhooks avec webhooks:beheren. Utilisez la même clé de production pour les traitements concernés.
2. Vérifiez la signature sur les octets d’origine et conservez chaque identifiant d’événement une seule fois. Accusez réception après stockage sûr avec la tâche suivante. Une répétition ne doit pas déclencher une deuxième demande.
3. Consultez GET /webhook-afleveringen et ses détails. Rapportly réessaie les erreurs temporaires au maximum huit fois ; un cycle supplémentaire peut être demandé. Accepté signifie seulement reçu par votre serveur : contrôlez la suite du traitement chez vous.

• Télécharger le guide des webhooks et des reprises
• Télécharger l’exemple Node.js de vérification de signature

Le simulateur n’envoie pas de notifications réelles. Testez votre récepteur avec des données fictives et une connexion de production distincte. L’exemple vérifie la notification ; votre serveur assure stockage et actions suivantes.

Que signifie un code d’erreur ?

Protéger la clé et les données clients

• Utilisez la clé uniquement sur votre serveur, jamais dans du code public du navigateur.
• Utilisez une clé par intégration et révoquez les anciennes.
• Ne placez pas clés, résultats ou liens temporaires dans des journaux ou conversations publics.
• Conservez les données clients selon les règles d’accès de votre système.