Points clés de l'API

URL d'accès et endpoint

L'API GraphQL est disponible à tous nos clients abonnés.
Toutes les requêtes (queries et mutations) s'envoient en POST vers l'endpoint GraphQL. Une seule URL pour toute l'API :

URL

# Remplacez 'sous-domain-client' ci-dessous par votre sous-domaine.
https://sous-domain-client.ublo.immo/api/graphql

# Remplacer 'domaine-client.extension' ci-dessous par votre domaine personnalisé.
https://domaine-client.extension/api/graphql

L'URL doit correspondre à votre sous-domaine ou domaine client selon votre environnement (staging, production).

Route /search non supportée

La route REST /search exposée par notre indexeur n’est pas une API publique. Elle est utilisée exclusivement pour les besoins internes des interfaces produit (moteur de recherche, filtres, indexation).
Son utilisation pour construire une intégration client présente plusieurs risques :

• Données désynchronisées au moment des appels
• Données incomplètes ou sorties de leur contexte métier
• Structure de réponse susceptible d’évoluer sans préavis

Seule l’API GraphQL constitue l’interface officielle pour les intégrations externes.

Authentification des appels

Chaque appel doit être authentifié.
Les droits associés au profil connecté définissent les opérations et les données accessibles par API.
Ne jamais exposer tokens ou clés API côté client (navigateur, app mobile non sécurisée).

Il y a deux manières de s'authentifier à l'API GraphQL :

1. Avec la mutation login

Munissez-vous des identifiants collaborateur (email et mot de passe) créés via le parcours standard d’invitation disponible dans les règlages de l’interface d’administration.

Les restrictions d'organisation (Business Units) associées au profil connecté s’appliquent aux appels API et peuvent, dans certains cas, entraîner une erreur unauthorized.
Pour éviter toute restriction, le profil collaborateur doit être rattaché à la société mère.

• Utilisez la mutation login afin d’ouvrir une session valide pendant 7 jours.
• Utilisez la mutation logout pour vous déconnecter.

Lors du login, un cookie UBLO_TOKEN_AUTHENTICATION est créé. Il convient de joindre ce cookie aux en-têtes des appels consécutifs si cela n'est pas fait automatiquement.

2. Avec token révocable

Si votre intégration nécessite une connexion sans expiration vous avez la possibilité de générer un token révocable spécifiquement pour cette intégration.

• Connectez-vous avec la mutation login comme vu précédemment.
• Utilisez la mutation generateApiToken
• Lister les tokens API créés par cet utilisateur avec apiTokens
• Révoquer immédiatement un token avec revokeToken

Vous devez alors envoyez le token dans l'en-tête de vos appels Authorization: Bearer <token>. Exemple d'appel authentifié :

Node.js

const response = await fetch('https://example.ublo.immo/api/graphql', {
  method: 'POST',
  headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer VOTRE_TOKEN'
      // Remplacer VOTRE_TOKEN ci-dessus par la réponse de la mutation generateApiToken
  },
  body: JSON.stringify({
      query: `query {
          getTenantContext {
              nextDefaultRef
              allRefs
          }
      }`
  })
});
const data = await response.json();

Versions et compatibilité

L'API évolue dans le temps (nouveaux champs, champs dépréciés). Les dépréciations sont indiquées dans le schéma et dans la doc. Privilégiez les champs stables et tenez-vous informé des annonces de breaking changes pour adapter vos appels à temps.

API non versionnée

L'API n'est actuellement pas versionnée ; un système de versioning sera mis en place ultérieurement.

En attendant, la société Ublo ne peut être tenu responsable des dysfonctionnements liés à l’utilisation d’éléments modifiés ou dépréciés de l’API. La rétrocompatibilité des scripts externes n’est pas garantie à ce stade.

Les clients ayant développé des services reposant sur l’API sont responsables du bon fonctionnement de ces services face aux évolutions de l’API. Cette situation ne justifie ni un support spécifique, ni une suspension des mises à jour de la plateforme pour les clients abonnés.

Sécurité et responsabilité

Ublo met en œuvre les mesures nécessaires pour protéger les données traitées par ses propres produits.
En revanche, les services et automatisations conçus par les clients demeurent sous leur seule responsabilité. Ublo ne pourra être tenue pour responsable des incidents de sécurité découlant d’une intégration de l’API ne respectant pas les standards de protection requis.
Il appartient aux développeurs et éditeurs concernés d’assurer la gestion sécurisée des accès et des informations sensibles.