Utiliser l'API REST Reonic

Reonic propose une API REST publique qui couvre les projets résidentiels, les projets commerciaux, les contacts, les tâches, les équipes, les fichiers, les rendez-vous, les composants, les activités, le statut et le pipeline, les tags, les notes, les packs de planification, les modèles de planification, les modèles d'offres, les modèles de liste de contrôle, les sources de leads, les tableaux Kanban et leurs colonnes, le contenu du wiki, la photogrammétrie et le suivi du temps.

Si un système que vous souhaitez connecter dispose déjà d'une intégration nommée (HubSpot, Pipedrive, Lexoffice, Bexio, Hero, K2, Microsoft, Google, AroundHome, DAA, Wattfox, Bees & Bears, EOS, Photovate, et d'autres), utilisez-la. Elle est précâblée et prise en charge. L'API sert à tout le reste : systèmes maison, outils de BI, CRM de niche, tableaux de bord sur mesure et passerelles vers des outils sans intégration nommée. Pour les automatisations no-code et les envois d'événements sortants, voyez les articles Zapier et Webhooks.

À qui s'adresse cet article

Aux admins installateurs et aux admins de Workspace qui construisent des intégrations sur mesure ou exportent des données hors de Reonic. Vos clients finaux (propriétaires, acheteurs commerciaux) ne voient jamais la surface de l'API.

Avant de commencer

• Vous devez disposer des droits admin dans votre Workspace Reonic.
• L'API est disponible sur tous les Workspaces. Si le panneau des clés API n'apparaît pas dans vos paramètres, contactez l'assistance Reonic.
• Reonic fait tourner en parallèle une version actuelle et une version précédente de l'API pendant une période de transition. Si votre Workspace possède des clés sur l'ancienne version, la page Paramètres > API / Developers > API affiche un onglet pour chacune. Construisez toutes vos nouvelles intégrations sur la version actuelle.
• Un hôte de scripts, un outil de BI ou tout système capable d'envoyer des requêtes HTTPS.

Trouver la page des paramètres de l'API

La configuration de l'API et des webhooks se trouve sur une page de paramètres distincte de la liste des intégrations nommées.

1. Ouvrez Paramètres > API / Developers. C'est différent de Paramètres > Paramètres de l'entreprise > Intégrations (la page des intégrations nommées).
2. La catégorie API / Developers contient deux pages : API (créer et gérer des clés) et Webhooks (configurer les webhooks sortants et les hooks Zapier).
3. Si votre Workspace possède des clés sur la version précédente de l'API, la page API affiche un onglet pour la version actuelle (présélectionné) et un pour la version précédente. Les Workspaces dont les clés sont uniquement sur la version actuelle ne voient qu'une seule page.
4. Si vous ne voyez pas du tout la section des clés API, contactez l'assistance Reonic.

Créer une clé API

Les clés API permettent à vos scripts et à vos systèmes externes de s'authentifier auprès de Reonic.

1. Sur la page API, cliquez sur Créer une nouvelle clé API.
2. Donnez à la clé un nom parlant qui indique à quoi elle sert, par exemple une clé en lecture seule pour l'entrepôt ou une clé Zapier de production. Le nom apparaît dans le journal d'activité, ce qui vous permet de distinguer les clés.
3. Choisissez la portée. Il y en a trois : Lecture seule (lecture sur toutes les ressources), Lecture et écriture (lecture et écriture complètes sur toutes les ressources) et Création de leads uniquement (une portée restreinte qui peut créer des leads, des projets résidentiels, des contacts et des notes, mais rien d'autre). Pour une intégration classique, choisissez Lecture seule ou Lecture et écriture. Création de leads uniquement est destinée aux clés de courtiers en leads entrants qui ne doivent qu'ajouter des leads.
4. Reonic génère la clé et l'affiche au moment de sa création.
5. Copiez-la immédiatement dans votre coffre à secrets, puis enregistrez. Si vous n'avez plus la clé, créez-en une nouvelle et supprimez l'ancienne.

Où trouver l'ID client

Votre ID client est l'identifiant de votre Workspace. Pour la plupart des intégrations, vous n'en avez pas besoin séparément. Un petit nombre d'intégrations partenaires, comme certaines configurations de courtiers en leads entrants, attendent l'ID client comme champ distinct. Demandez à l'assistance Reonic de vous confirmer le vôtre.

Clé API et ID client

La clé API est le secret, comme un mot de passe. Elle authentifie chaque requête. L'ID client est l'identifiant de votre Workspace, comme un nom d'utilisateur. Gardez la clé API privée ; l'ID client est la référence de votre Workspace pour les systèmes partenaires.

Authentifier les appels à l'API

Reonic utilise un en-tête d'authentification propriétaire plutôt que l'en-tête Authorization standard. La référence des points de terminaison nomme l'en-tête exact et montre comment le renseigner.

1. Dans votre client HTTP, renseignez l'en-tête d'authentification Reonic avec la valeur de votre clé API.
2. Envoyez la requête au point de terminaison concerné.
3. Si la requête est rejetée comme non authentifiée, vérifiez que vous avez bien renseigné l'en-tête d'authentification Reonic (et non l'en-tête Authorization standard) et que vous avez copié la clé en entier.

Trouver la référence des points de terminaison

La référence des points de terminaison est une page de documentation générée. C'est la liste faisant autorité de chaque point de terminaison, de son chemin exact, des champs de requête et de réponse, et de l'en-tête d'authentification. Ses points de terminaison se répartissent en dix grands domaines :

• Personnes — utilisateurs, équipes.
• Projets — projets résidentiels (la surface résidentielle solaire, pompe à chaleur et borne de recharge) et projets commerciaux (le pipeline commercial).
• Travailler sur un projet — activités, statut, tags, notes, fichiers, tableaux Kanban et colonnes.
• Calendrier — rendez-vous, flux de calendrier.
• Catalogue — composants, fabricants, packs de planification, modèles de planification, modèles d'offres.
• Configuration du Workspace — sources de leads, modèles de liste de contrôle, intégrations.
• Wiki — contenu du wiki.
• Services — rendez-vous de service.
• Utilitaires de l'API — points de terminaison utilitaires.
• Guides — pages de guide de migration intégrées.

Faire votre premier appel à l'API

Testez la connexion avant de construire quoi que ce soit dessus.

1. Choisissez un point de terminaison de lecture peu risqué. Une liste de projets résidentiels ou de contacts est un bon début. La référence des points de terminaison vous donne le chemin exact.
2. Lancez l'appel avec votre clé API dans l'en-tête d'authentification Reonic.
3. Reonic répond avec une charge utile JSON. Les points de terminaison de liste renvoient un tableau de données et un bloc de pagination.
4. Vérifiez que l'appel est bien arrivé dans Paramètres > Paramètres de l'entreprise > Intégrations, avec un statut de réussite.

Migrer vers la version actuelle de l'API

Les deux versions de l'API tournent en parallèle pendant la transition, et la version précédente reste stable. Planifiez votre migration à l'avance pour que vos intégrations soient sur la version actuelle bien avant le retrait de la précédente. Demandez à l'assistance Reonic la date de retrait visée afin de vous organiser.

Le groupe migration de la référence des points de terminaison détaille les étapes. En résumé :

1. Créez une nouvelle clé sur la version actuelle. Les points de terminaison actuels attendent une clé de la version actuelle.
2. Traitez les listes paginées. Chaque réponse de liste enveloppe un tableau de données et un bloc de pagination. Adaptez tout analyseur qui supposait un tableau nu.
3. Utilisez les surfaces projets résidentiels et projets commerciaux. Elles remplacent l'ancienne surface demandes-et-offres : projets résidentiels pour la ligne solaire, pompe à chaleur et borne de recharge, projets commerciaux pour la ligne commerciale.
4. Adaptez-vous aux noms de champs actuels. Certains noms de champs diffèrent de la version précédente, notamment les champs e-mail, adresse et variantes. La référence des points de terminaison liste les noms actuels.
5. Adoptez les limites et le comportement de cache actuels. La référence des points de terminaison décrit comment demander une lecture fraîche à chaque appel et comment réagir lorsqu'on vous demande de ralentir (voir Gérer les limites de débit et le cache).

Pour recréer des objets que vous construisiez auparavant avec les anciens utilitaires de duplication, utilisez le point de terminaison de création standard. La version actuelle gère la duplication par le flux de création normal.

Paginer, filtrer et récupérer les deltas

Les points de terminaison de liste utilisent une pagination par numéro de page.

• Passez un numéro de page et une taille de page pour parcourir les résultats.
• La réponse inclut des liens vers la page suivante et la page précédente. Suivez-les pour parcourir l'ensemble complet.
• Quelques points de terminaison paginent différemment. La référence des points de terminaison signale ces cas, notamment une taille de page fixe sur le suivi du temps, des points de terminaison à réponse unique comme les équipes et les tags, et une fenêtre temporelle glissante sur les événements du calendrier.

Pour les récupérations incrémentales (uniquement les enregistrements modifiés depuis votre dernière exécution), les projets résidentiels exposent un horodatage de dernière modification que vous pouvez utiliser comme repère. Sur les autres points de terminaison, conservez l'horodatage de modification le plus élevé de votre réponse précédente et repartez de là. La prise en charge du filtre « modifié depuis » varie selon le point de terminaison. Si votre script a besoin des deltas, demandez à l'assistance Reonic quels points de terminaison de liste exposent ce filtre.

Gérer les limites de débit et le cache

L'API applique une limite de débit par Workspace pour qu'aucune intégration ne sature vos données à elle seule. Si vous envoyez des requêtes plus vite que la limite, Reonic répond en vous demandant de ralentir.

1. Quand on vous demande de ralentir, temporisez avant de réessayer. Une temporisation exponentielle (2, 4, 8, 16 secondes) est un schéma sûr.
2. Si le service signale qu'il est temporairement indisponible, temporisez et réessayez.
3. Pour les gros chargements, cadencez vos appels et ajoutez une courte pause entre les pages afin de rester sous la limite.
4. Les lectures répétées sont servies depuis un cache de courte durée. Quand vous avez besoin des toutes dernières données sur un appel précis, la référence des points de terminaison montre comment demander une lecture fraîche.

Gérer les erreurs

Reonic renvoie des erreurs HTTP structurées qui suivent la sémantique standard 4xx et 5xx.

• Non authentifié — clé manquante ou non valide. Vérifiez que vous avez renseigné l'en-tête d'authentification Reonic (et non l'en-tête Authorization standard) et copié la clé en entier.
• Permission refusée — la portée de la clé ne couvre pas l'opération, ou la ressource est en dehors de ce que la clé autorise. Traitez les réponses 4xx comme définitives ; ne réessayez pas.
• Introuvable — vérifiez l'ID.
• Demande de ralentir — vous envoyez des requêtes trop vite. Temporisez et réessayez.
• Erreur serveur (5xx) — signalez-la au support avec l'horodatage. Traitez les 5xx comme transitoires et réessayez avec une temporisation.
• Temporairement indisponible — temporisez et réessayez.

Tâches courantes avec l'API

Voici les schémas les plus demandés. Prenez-les comme points de départ. La référence des points de terminaison en ligne liste chaque point de terminaison et la forme exacte de ses champs ; votre gestionnaire de comptes peut vous aider si vous bloquez.

Créer une demande

Utilisez le point de terminaison de création de projets résidentiels pour les leads solaire, pompe à chaleur et borne de recharge, et le point de terminaison de création de projets commerciaux pour le pipeline commercial. Le point de terminaison renvoie l'ID du nouveau projet.

Pour que le lead apparaisse sur la carte, Reonic a besoin d'une localisation. Fournissez une adresse que Reonic pourra rechercher, ou un jeu de coordonnées que vous avez déjà résolues. Incluez toujours un code postal, et vérifiez les coordonnées renvoyées si la précision au mètre compte.

Définissez le statut du projet à la création si vous voulez un statut de départ précis. Sinon, la demande arrive avec le statut de départ du Workspace.

C'est aussi le point de terminaison à utiliser pour importer des leads depuis un système sans intégration nommée, par exemple un formulaire de contact WordPress qui poste vers votre point de terminaison projets résidentiels ou contacts. Le chemin le moins codé est une passerelle Zapier depuis le formulaire WordPress.

Modifier une demande après sa création

Mettez à jour la plupart des champs après la création, y compris l'adresse, avec le point de terminaison de mise à jour de projet résidentiel ou de projet commercial et l'ID du projet.

Créer une offre à partir d'un projet

Une offre dans l'API est le devis chiffré, structuré en variantes, rattaché à un projet. Elle regroupe une ou plusieurs variantes (chacune avec sa propre liste des composants, sa sélection de packs, sa tarification et son éventuelle remise ou son montage de financement) ainsi que les métadonnées au niveau de l'offre (statut, état de signature, notes et fichiers joints). C'est le même objet que celui que vous voyez dans le Portal sous l'onglet Offres d'un projet.

Le flux recommandé :

1. Créez le projet via l'API.
2. Récupérez l'ID du projet dans la réponse.
3. Appelez le point de terminaison de création d'offre avec cet ID du projet et votre définition de variante.
4. La réponse contient l'ID de la nouvelle offre, que vous utilisez pour les mises à jour ultérieures.

Laissez le statut de l'offre vide à la création si vous voulez qu'elle arrive en brouillon. Pour convertir une demande en offre, appelez le point de terminaison de création d'offre avec l'ID du projet, et Reonic relie la nouvelle offre au projet d'origine.

Définir ou modifier le prix d'une offre via l'API

Le point de terminaison de mise à jour d'offre accepte un prix au niveau de la variante, ce qui est utile quand votre système de tarification externe doit pousser un prix final dans Reonic. La forme exacte du champ dépend de la variante. Consultez la référence des points de terminaison ou demandez à l'assistance Reonic.

Ajouter des notes ou des fichiers à une offre

Il existe des points de terminaison dédiés pour ajouter une note et pour téléverser un fichier. Les fichiers téléversés (PDF, images) se rattachent à l'offre, au projet ou au contact que vous ciblez.

Créer un contact

Utilisez le point de terminaison de création de contacts. Les coordonnées ne sont pas obligatoires pour créer un contact ; seuls les projets qui apparaissent sur la carte ont besoin d'une localisation.

Pour les imports en masse (migrer une liste de contacts existante vers Reonic depuis un CSV, un ancien CRM ou un tableur), bouclez sur vos enregistrements et créez un contact par appel, en cadençant vos appels pour rester sous la limite de débit. Pour les migrations ponctuelles plus volumineuses, lancez la boucle depuis votre propre infrastructure vers le même point de terminaison. Chaque point de terminaison de création renvoie l'ID de la nouvelle ressource : récupérez-le au moment de la création.

Filtrer les activités par type de parent

Le point de terminaison des activités prend en charge un filtre par type de parent qui restreint les activités à un type d'enregistrement parent précis, par exemple un projet résidentiel, un projet commercial, un pack, un composant, un contact, une tâche de photogrammétrie ou un utilisateur. Consultez la référence des points de terminaison pour connaître les valeurs exactes acceptées.

Exporter les données

Le chemin le plus propre pour un export en masse est de lister le point de terminaison concerné avec pagination et de stocker la réponse. Cibles courantes :

• Offres gagnées — récupérez toutes les offres et filtrez par statut, ou récupérez la liste au statut gagné.
• Contacts — récupérez les contacts avec pagination et stockez-les localement.
• Projets commerciaux — récupérez les projets commerciaux.
• Rendez-vous — récupérez les rendez-vous de la surface calendrier de Reonic. Récupérez les calendriers Microsoft ou Google externes directement auprès de ces services.
• Versions de composants — récupérez les composants et regroupez-les par composant parent là où des versions existent.
• État des tableaux Kanban — récupérez les tableaux Kanban et leurs colonnes pour obtenir des instantanés des tableaux de projet.
• Sources de leads — récupérez les sources de leads pour connaître la taxonomie des canaux de leads configurée dans le Workspace.

Pour produire un fichier Excel de vos demandes, offres, statistiques ou données brutes, récupérez le point de terminaison de liste concerné et chargez la réponse JSON dans Excel, Google Sheets ou votre outil de BI.

Utiliser la version actuelle de l'API pour les intégrations externes

Construisez toujours vos intégrations externes sur la version publique actuelle de l'API, y compris pour les envois de fichiers. C'est le contrat stable et pris en charge pour lire et écrire vos données depuis l'extérieur du Portal.

Faire le pont vers des outils sans intégration nommée

Pour les systèmes absents du catalogue nommé (Datev, Monday.com, Craftnote, synchronisation des contacts Office 365, Zoho CRM, e-mailing de masse), construisez sur l'API pour pousser les données vers l'extérieur selon un planning, ou reliez-les via Zapier.

• Datev — poussez les factures hors de Reonic via l'API et importez-les dans Datev côté comptabilité, ou utilisez Lexoffice ou Sevdesk comme passerelle (les deux ont un export Datev natif). Le chemin Lexoffice ou Sevdesk est aussi celui qui permet de raccorder un conseiller fiscal (Steuerbüro), qui a généralement déjà accès à l'un de ces outils.
• Synchronisation des contacts Office 365 — l'intégration Microsoft gère les calendriers ; synchronisez les contacts avec un Zap sur mesure ou une intégration API vers votre point de terminaison contacts.
• E-mailing de masse — Reonic n'est pas un outil d'e-mail marketing. Exportez vos contacts via l'API et envoyez la campagne depuis une plateforme dédiée (Mailchimp, Brevo, HubSpot Marketing).
• Zoho CRM — reliez-le avec un flux Zapier (un déclencheur Zoho CRM new-lead qui poste vers votre point de terminaison projets résidentiels ou contacts), ou scriptez une synchronisation périodique Zoho vers Reonic dans votre propre infrastructure. Les deux chemins ont besoin des champs d'adresse décrits sous Créer une demande.
• Calendrier Microsoft 365 / Google Workspace — ceux-ci disposent d'intégrations dédiées dans Paramètres > Paramètres de l'entreprise > Intégrations, et non du chemin API. Configurez-les là, puis récupérez les calendriers Outlook ou Google externes directement auprès de ces services. L'API expose les rendez-vous Reonic.
• Courtiers en leads (AroundHome, DAA, Wattfox et autres) — ceux-ci disposent d'intégrations nommées dédiées dans Paramètres > Paramètres de l'entreprise > Intégrations : utilisez-les plutôt que l'API générique. Pour AroundHome, l'identifiant client est l'identifiant propre à l'intégration ; consultez le panneau d'administration AroundHome pour connaître le format exact. Ne repassez à l'API ou à Zapier que pour les sources de leads hors du catalogue nommé.

Si vous souhaitez une intégration nommée pour une source à fort volume, parlez-en à votre gestionnaire de comptes.

Où se trouvent les intégrations nommées

Toutes les intégrations nommées se trouvent dans Paramètres > Paramètres de l'entreprise > Intégrations (et non dans API / Developers), chacune avec sa propre page de configuration et ses identifiants par Workspace. Pour le financement Bees & Bears, vous n'avez pas besoin de clé API. Configurez l'intégration directement dans Paramètres > Paramètres de l'entreprise > Intégrations, et Reonic s'occupe des identifiants.

• HubSpot, Photovate, Hero, Sevdesk — voyez leurs pages de configuration dans Paramètres > Paramètres de l'entreprise > Intégrations.
• Export d'offre Photovate / K2 et liaison des composants Photovate — des boutons d'export dédiés sur l'offre signée. Pour les offres qui ont besoin de données K2 après la signature, cliquez sur le bouton d'export de la ligne de signature.
• Financement (Bees & Bears, EOS) — Bees & Bears couvre DE, AT, FR et BE ; EOS couvre le Brésil. Une fois qu'un client a signé une offre avec une option de financement, utilisez le bouton d'export vers le financement sur l'offre signée. Reonic envoie les données de l'offre, les détails du client et le PDF signé au partenaire de financement. Si l'option d'export n'apparaît pas, vérifiez avec votre gestionnaire de comptes que l'intégration de financement est activée pour votre Workspace et que l'utilisateur a le droit Organisme de financement.
• Sevdesk après l'expiration d'un lien — pour transférer une offre signée vers Sevdesk quand le lien de signature d'origine a expiré, lancez une nouvelle demande de signature sur la même variante, téléversez le PDF signé sur la nouvelle ligne de signature, puis cliquez sur le bouton d'export Sevdesk de cette ligne.
• SMTP — Reonic envoie les e-mails destinés aux clients, comme les liens de signature et les notifications de facture. Pour envoyer depuis votre propre domaine, configurez un serveur SMTP sortant personnalisé dans Paramètres > Paramètres de l'entreprise > Intégrations > Serveur de messagerie SMTP.
• Champs du formulaire de contact et UTM — le formulaire de contact prend en charge un ensemble limité de champs supplémentaires et de tags de source de lead. La transmission des UTM sur les formulaires intégrés est gérée par le code d'intégration ; parlez à votre gestionnaire de comptes du suivi UTM pour le formulaire de contact.

Transférer des offres entre Workspaces Reonic

Pour déplacer une offre d'un Workspace Reonic à un autre :

1. Exportez le PDF de l'offre depuis le Workspace source.
2. Recréez le projet et l'offre dans le Workspace de destination, via l'API ou manuellement dans le Portal.
3. Joignez le PDF exporté comme fichier sur l'offre de destination.

Si le besoin devient récurrent, par exemple un groupe de franchise qui déplace des offres entre Workspaces, parlez à votre gestionnaire de comptes d'un meilleur schéma.

Bon à savoir

• L'API est disponible sur tous les Workspaces. Les clés apparaissent sur la page Paramètres > API / Developers > API.
• Les deux versions de l'API tournent en parallèle pendant la transition. Construisez vos nouvelles intégrations sur la version actuelle et migrez avant le retrait de la précédente ; demandez la date visée à l'assistance Reonic.
• Reonic utilise un en-tête d'authentification propriétaire, et non l'en-tête Authorization standard. De nombreux clients HTTP utilisent Authorization par défaut ; ajoutez plutôt l'en-tête d'authentification Reonic comme en-tête personnalisé. La référence des points de terminaison le nomme.
• La référence des points de terminaison est le contrat qui fait autorité. Elle liste chaque point de terminaison, son chemin exact, les champs de requête et de réponse, et l'en-tête d'authentification. Quand un champ ou un chemin diffère de la version précédente, la référence indique le nom actuel.
• Les erreurs de permission remontent sous forme d'erreurs HTTP structurées. Traitez les 4xx comme définitives (ne réessayez pas) et les 5xx comme transitoires (réessayez avec une temporisation).
• Copiez chaque clé dans votre coffre à secrets dès sa création. Si vous n'avez plus une clé, créez-en une nouvelle et supprimez l'ancienne.
• La portée d'une clé API a trois niveaux — Lecture seule, Lecture et écriture et Création de leads uniquement (une portée restreinte qui ne peut créer que des projets résidentiels, des contacts et des notes, destinée aux clés de courtiers en leads entrants). Créez des clés séparées avec des noms parlants pour la clarté de l'audit.
• Les limites de débit s'appliquent par Workspace. Si vous envoyez des requêtes trop vite, Reonic vous demande de ralentir ; temporisez et réessayez. Toutes les clés d'un Workspace partagent un seul budget.
• Les lectures répétées sont servies depuis un cache de courte durée. Quand vous avez besoin des dernières données sur un appel précis, la référence des points de terminaison montre comment demander une lecture fraîche.
• Supprimer une clé la met hors service. Désactiver, renouveler ou supprimer une clé la retire de la circulation.
• Chaque appel à l'API atterrit dans le journal d'activité de l'intégration avec votre ID client, la méthode, le statut et un horodatage, visible dans Paramètres > Paramètres de l'entreprise > Intégrations.
• Les activités se filtrent par type de parent. Restreignez les activités à un projet résidentiel, un projet commercial, un pack, un composant, un contact, une tâche de photogrammétrie ou un utilisateur ; consultez la référence des points de terminaison pour les valeurs exactes.
• Les calendriers externes ne passent pas par l'API. L'API expose les rendez-vous Reonic ; récupérez Outlook ou Google directement auprès de ces services.
• Testez sur votre Workspace avec une demande de test clairement nommée, puis nettoyez-la ensuite.

Dernière mise à jour le 12 octobre 2026