Aller au contenu principal
Référence de l'API

API publique Revel’Home (bêta)2026.12-beta1

⚠️ API en phase bêta. Le contrat est susceptible d'évoluer, y compris de façon incompatible, avant sa version stable : chaque changement incompatible est annoncé 30 jours à l'avance dans l'historique des versions ci-dessous. Prévenez l'équipe Revel’Home avant toute mise en production d'une intégration afin d'être informé directement des changements.

Porte d'entrée canonique permettant à un partenaire (éditeur de logiciel de chiffrage, connecteur métier) de déposer un document (devis, facture, bon de commande) dans Revel’Home. Le document est traité immédiatement : la réponse contient le lien du projet créé ou retrouvé, à parité avec les connecteurs historiques (ProDevis, HerculePro).

Le partenaire peut aussi lire un projet de son organisation, avec ses adresses et ses contacts, à partir de l'identifiant reçu dans un événement.

En retour, Revel’Home peut pousser les événements du cycle de vie d'un projet vers une URL du partenaire : voir la section Webhooks. Leur installation passe par l'équipe Revel’Home, aucune API de souscription n'étant exposée.

Authentification

Chaque appel est authentifié par la clé API de l'organisation, transmise dans l'en-tête Authorization selon le schéma Bearer :

Authorization: Bearer <clé_api>

L'organisation cible est résolue à partir de cette clé. Toute requête non authentifiée renvoie un 401 au format JSON, que la clé soit invalide ou inconnue ({"message": "API token unknown"}) ou que l'en-tête Authorization soit absent ou d'un autre schéma que Bearer ({"message": "Missing or invalid API key."}).

Versionnement

Chaque appel doit porter l'en-tête X-API-Version, qui déclare la version du contrat que vous attendez. Le format est AAAA.MM (année.mois), suffixé d'une pré-release pendant la bêta ; version courante : 2026.12-beta1. L'en-tête est obligatoire : un appel sans X-API-Version renvoie 400. À partir de la fin du préavis de 2026.12-beta1, une valeur inconnue renverra aussi 400.

Le chemin /v1 ne change pas : les évolutions passent par la version datée.

Changements incompatibles. Un changement est incompatible s'il retire ou renomme un champ, une route ou un paramètre, change le type d'un champ, ajoute un paramètre obligatoire, refuse une valeur jusque-là acceptée, ou modifie l'authentification ou un code d'erreur. Il donne lieu à une nouvelle version datée.

Hors bêta, l'ancienne version reste honorée 6 mois après l'annonce, puis répond 410. L'annonce est publiée dans l'historique ci-dessous, portée par les en-têtes Deprecation et Sunset des réponses de l'ancienne version, et adressée aux intégrateurs concernés.

Pendant la bêta, l'ancienne version n'est pas conservée : passé les 30 jours de préavis, le nouveau comportement s'applique quelle que soit la version déclarée.

Les webhooks ne portent pas d'en-tête : leur version est fixée par abonnement et suit le même calendrier.

Changements compatibles, sans préavis. Votre intégration doit les tolérer :

  • un nouveau champ dans une réponse ou un événement ;
  • une nouvelle route ;
  • une nouvelle valeur dans une liste de valeurs (statut, type…) ;
  • un nouveau type d'événement webhook ;
  • un ordre différent des champs.

Sortie de bêta. La première version stable sortira en une seule fois, avec l'ensemble des changements incompatibles prévus pour le contrat définitif, afin que chaque intégration ne migre qu'une fois. Elle sera annoncée 30 jours à l'avance et mettra fin au support de la version bêta.

Historique des versions

VersionChangements incompatiblesFin de support
2026.12-beta1identifiants publics préfixés ; valeur inconnue de X-API-Version refuséesortie de bêta
2026.07-beta1version initialefin du préavis de 2026.12-beta1

2026.12-beta1 — identifiants publics. Chaque ressource est désignée par un identifiant opaque, préfixé par son type, à la place de son numéro : prj_ projet, ctc_ contact, quo_ devis, doc_ document, pay_ règlement, apt_ RDV, org_ organisation, fac_ établissement, rcp_ PV de réception, evt_ événement webhook. Exemple : prj_01JD3K8Z9XQ4T7M2B6N5V0WCRE. Un identifiant porteur du préfixe d'une autre ressource rend 404. Pendant les 30 jours de préavis, une route accepte encore l'ancien numéro, et une réponse déclarée en 2026.07-beta1 le rend encore ; ensuite, seul l'identifiant préfixé existe, et un X-API-Version inconnu renvoie 400, comme un en-tête absent. Les webhooks suivent la version de leur abonnement.

Limite de débit

Les appels sont limités à 1 200 par minute et par organisation, toutes clés et tous chemins confondus. Au-delà, l'API répond 429 : réessayer plus tard.

Toutes les requêtes utilisent cette URL de base :

  • https://api.revelhome.appProduction
AuthorizationstringheaderBearer token

Clé API de l'organisation, transmise en Authorization: Bearer <clé_api>.

curl --request GET \
  --url https://api.revelhome.app/v1/me \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Version: 2026.12-beta1'
X-API-Versionstringheaderobligatoire

Version du contrat au format AAAA.MM (année.mois). Version courante : 2026.12-beta1.

Exemple: 2026.12-beta1

Besoin d'aide supplémentaire ? Demander à l'équipe