Premiers pas avec le Bluebeam Developer Portal

L'API Bluebeam est RESTful et dispose actuellement de 2 catégories de points de terminaison :

• Authentification

• Studio

Il existe des URL de base spécifiques à la région qui s'appliquent à tous les points de terminaison :

- États-Unis : https://api.bluebeam.com

- DE : https://api.bluebeamstudio.de

- AU : https://api.bluebeamstudio.com.au

- UK: https://api.bluebeamstudio.co.uk

- SE: https://api.bluebeamstudio.se

Par exemple, https://api.bluebeam.com/publicapi/v1/sessions aux États-Unis serait https://api.bluebeamstudio.com.au/publicapi/v1/sessions en Australie.

Authentification

Quelques notes de haut niveau sur la façon dont nous gérons l’authentification :

• Authentification avec OAuth 2.0

  • Tous les appels d’API sont effectués dans le contexte d’un utilisateur. En s'authentifiant avec OAuth, un utilisateur accorde l'autorisation à votre application d'accéder à ses données et d'effectuer des demandes d'API en son nom.

• Toutes les demandes et tous les corps de réponse doivent être au format JSON. Définissez l'en-tête Content-Type : application/json sur toutes les requêtes comportant des corps.

• Les appels API doivent être effectués via HTTPS.

• Consultez notre Guide d'authentification pour commencer à configurer OAuth 2.0 dans votre application.

Studio

Studio est notre plateforme de collaboration cloud avec une connexion directe à notre application de bureau phare : Bluebeam Revu. Nos points de terminaison Studio ouvrent des lignes de communication pour une intégration transparente entre Studio et vos systèmes.

Vous pouvez généralement considérer les fonctionnalités offertes par l’API Studio comme le même ensemble de fonctionnalités qu’un utilisateur obtiendrait via l’interface graphique Studio dans Revu.

Pour en savoir plus sur Studio, visitez notre page FAQ Studio.

Pour accélérer les choses, nous vous recommandons d'utiliser une application appelée Postman. Voici comment :

1. Créez un compte Bluebeam et demandez l’accès au Bluebeam Developer Portal, si vous ne l’avez pas déjà fait.

2. Accédez à developers.bluebeam.com et connectez-vous.

3. Inscrivez-vous pour y accéder.

   1. Accédez à Mes applications et cliquez sur Demander l’accès.

   2. Remplissez le formulaire de demande d’accès (voir la capture d’écran ci-dessous). Sélectionnez l’instance API Bluebeam associée à votre région.
      
      

   Remarque sur le type de subvention :
   Sélectionnez uniquement les cases à côté de :
   • Code d’autorisation
   • Jeton de rafraîchissement

   3. Redirection uri : utilisez https://oauth.pstmn.io/v1/callback

   4. Sélectionnez Demande pour soumettre le formulaire.
      

   Courriel d'approbation
   Après avoir sélectionné Demande, vous recevrez un e-mail de marque MuleSoft avec le sujet : « Enregistrement de l'application approuvé » – veuillez l'ignorer. C'est un autre effet secondaire indésirable de l'utilisation de notre solution prête à l'emploi.
   

4. Obtenez des informations d'identification. Vous devriez maintenant voir votre application nouvellement enregistrée dans la liste (si vous ne la voyez pas, actualisez votre navigateur). Passez la souris sur la clé pour obtenir vos informations d'identification.

   
   

5. Obtenez un jeton d'accès via Postman.

   1. Accédez à Postman via leur application de bureau ou leur navigateur et créez un compte gratuit.

   2. Voici un script que vous pouvez importer dans Postman. Dans Postman, allez dans Fichier > Importer et déposez le script.

   3. Pour obtenir un access_token dans Postman, sélectionnez la collection Bluebeam API (Script xxx) .

   4. Accédez à l'onglet Autorisation et remplacez les variables orange {{client_id}} et {{client_secret}} par l'ID client et le secret que vous avez reçus dans Mes applications.

   5. Faites défiler jusqu’en bas et cliquez sur Obtenir un nouveau jeton d’accès.
      
      

   6. Connectez-vous avec votre BBID et cliquez sur Autoriser l'accès lorsque vous y êtes invité. Un jeton vous sera présenté que vous pourrez utiliser dans Postman, nos documents API ou votre propre code.

Voici un processus étape par étape pour migrer une intégration existante vers notre nouvelle plateforme.

1. Créez un compte BBID, si vous ne l'avez pas déjà fait.

2. Accédez à developers.bluebeam.com et connectez-vous.

3. Enregistrez une nouvelle application.

   1. Accédez à Mes applications et sélectionnez Demander l’accès.

   2. Remplissez le formulaire de demande d’accès (voir la capture d’écran ci-dessous). Sélectionnez l’instance API Bluebeam associée à votre région.
      

      Remarque sur le type de subvention :

      Sélectionnez uniquement les cases à côté de :

      • Code d’autorisation
      • Jeton de rafraîchissement

   3. Sélectionnez Demande pour soumettre le formulaire.
      

4. Obtenez des informations d'identification. Vous devriez maintenant voir votre application nouvellement enregistrée dans la liste. Passez la souris sur la clé pour obtenir vos informations d'identification.

   
   

5. Mettez à jour votre intégration existante avec les nouvelles routes API pour l’autorisation et les points de terminaison Studio répertoriés ci-dessous.
   

   Serveurs des États-Unis
   Environnement	Itinéraire de base original	Nouvelle route de base
   Authentification – Production (États-Unis)	https://authserver.bluebeam.com/auth/oauth/authorize	https://api.bluebeam.com/oauth2/authorize
   Authentification – Production (États-Unis)	https://authserver.bluebeam.com/auth/token	https://api.bluebeam.com/oauth2/token
   Studio – Production (États-Unis)	https://studioapi.bluebeam.com:443/publicapi/v1	https://api.bluebeam.com/publicapi/v1

6. Partout où votre identifiant client et votre secret client hérités sont configurés dans votre intégration, remplacez-les par votre nouvel identifiant client et votre nouveau secret.

7. Dans vos appels API, ajoutez un en-tête appelé « client_id» avec la valeur de votre nouvel ID client. Ceci est obligatoire pour toutes les demandes arrivant sur la nouvelle plateforme.

   Remarque
   Nous travaillons toujours à rendre nos messages d'erreur plus précis et plus significatifs, mais en attendant, si vous envoyez votre demande sans l'en-tête "client_id" , vous verrez un message d'erreur comme celui-ci :
   

   copy

   {
       "msg": "Internal Server Error"
   }

8. Notre nouvelle plateforme gère l'authentification légèrement différemment de notre ancienne plateforme, nous vous recommandons donc de consulter notre nouveau Guide d'authentification . Deux changements notables :

   • Nous avons introduit une portée d' offline_access pour les jetons d'actualisation (voir l'étape 1 du Guide d'authentification ).

   • Nos réponses de point de terminaison de jeton ont changé (consultez le Guide d’authentification pour des exemples de réponses).

9. Si tout est configuré correctement, vous devriez recevoir une réponse identique à la réponse de l'API Studio précédente pour tous les points de terminaison Studio.
   Par exemple, si vous demandez une liste de projets Studio, le corps de votre réponse ressemblera à ceci :
   

   copy

   {
     "$id": "1"
     "Projects": [
       {
         "$id": "2",
         "Id": "385-509-537",
         "Guid": "Mzu1D6xhLE2bE0y2F4ozfQ",
         "Name": "Nom du projet de test",
         "Restricted": true,
         "Created": "2024-02-29T17:40:58.043",
         "OwnerNameIdentifier": "e149e277-3052-4f3e-a376-29fc6c5aa76c",
         "OwnerEmail": "jdoe@bluebeam.com"
       }
     ]
   }

10. Tu l'as fait ! Testez votre application et faites-nous savoir si vous rencontrez des problèmes.