Passer au contenu principal
Hyperline prend en charge la création d’intégrations externes, afin que votre produit puisse se connecter à n’importe quel compte Hyperline. Cette capacité permet aux applications externes de mettre en place des cas d’usage tels que :
  • automatiser ou white-labeller des besoins spécifiques à la facturation
  • permettre à votre application de consulter les données d’un compte Hyperline
  • permettre à votre application de gérer la base de clients d’un compte Hyperline
  • permettre à votre application de gérer le catalogue produits d’un compte Hyperline
  • permettre à votre application de gérer les abonnements récurrents ou les paiements ponctuels d’un compte Hyperline
  • récupérer les factures depuis un compte Hyperline
Cette liste n’est pas exhaustive et une variété de flux peut être construite en s’appuyant sur ce type d’application.

​
Premiers pas

Hyperline utilise le standard OAuth pour permettre à votre application d’accéder aux données d’un compte connecté avec le consentement de l’utilisateur. Cela évite d’avoir à échanger manuellement des clés API. Par exemple, avec le consentement de l’utilisateur, en utilisant OAuth, vous pouvez appeler l’API d’abonnement au nom de votre utilisateur pour créer un abonnement Hyperline. Notre API prend en charge le flux Authorization Code Grant (RFC 6749 section 4.1), qui permet à votre application d’obtenir des jetons d’accès distincts pour chaque compte Hyperline connecté. Nous recommandons l’utilisation d’une bibliothèque bien établie pour effectuer les requêtes OAuth. Vous trouverez quelques recommandations ici.

​
Enregistrer votre application

​
Prérequis

La capacité de création d’applications tierces est accordée manuellement par Hyperline. Veuillez contacter notre support si cela vous intéresse et que vous souhaitez l’activer.

​
Créer une application

La première chose à faire est de créer une nouvelle application en utilisant l’API Apps. Vous recevrez un Client ID et un Client Secret, qui doivent tous deux être gardés secrets. Ces identifiants peuvent être utilisés pour :
  1. Rediriger les utilisateurs vers le formulaire d’autorisation de votre application (Client ID)
  2. Échanger les codes d’autorisation contre des jetons d’accès (Client ID et Client Secret)
  3. Renouveler vos jetons d’accès
  4. Désautoriser les utilisateurs de votre application (Client ID et Client Secret)
Utilisez l’API de création d’application en incluant les attributs suivants dans un corps JSON :
  • name : affiché à l’utilisateur durant le flux d’autorisation
  • description (optionnel) : pour afficher plus de détails à l’utilisateur
  • logo_uri (optionnel) : pour personnaliser l’écran d’autorisation avec votre marque
  • callbacks : URLs autorisées à servir de callback/redirection après l’autorisation (par exemple, une URL dans votre application qui traite les autorisations)
Pour l’instant, les applications ne peuvent être gérées (listées, mises à jour, supprimées) qu’au moyen de notre API.

​
Flux OAuth

1

Autoriser

Pour initier le flux, vous devez diriger votre utilisateur vers https://api.hyperline.co/v1/oauth/authorize (ou https://sandbox.api.hyperline.co/v1/oauth/authorize). Vous devez ajouter ces quatre paramètres de requête à l’URL :
  • client_id : reçu lors de l’enregistrement de l’application
  • redirect_uri : où l’utilisateur sera envoyé après l’autorisation ; cela doit correspondre à l’URL définie lors de l’enregistrement de votre application
  • response_type=code : le seul mode pris en charge pour le moment
  • state : une chaîne aléatoire pour prévenir les attaques CSRF, que vous vérifiez lorsque l’utilisateur revient à votre application — plus d’informations
Cet endpoint redirigera l’utilisateur vers la page de connexion Hyperline.
2

Récupérer les jetons

Après l’autorisation, l’utilisateur est redirigé vers votre redirect_uri avec les paramètres de requête code et state. Vous devez vous assurer que le paramètre state correspond au state initial que vous avez transmis au début du flux.Si c’est le cas, vous pouvez échanger le code fourni contre des jetons en effectuant une requête POST à https://api.hyperline.co/v1/oauth/tokens (https://sandbox.api.hyperline.co/v1/oauth/tokens), en incluant les attributs suivants dans un corps JSON :
  • client_id : comme ci-dessus
  • client_secret : reçu lors de l’enregistrement de l’application
  • grant_type: "authorization_code"
  • code : tel que fourni dans les paramètres de requête
  • redirect_uri : doit correspondre à la valeur définie à l’étape 1. Autoriser
Vous recevrez alors les jetons dans le corps JSON :
Response JSON body
{
  "access_token": "<token>",
  "refresh_token": "<token>",
  "expires_in": 3600,
  "token_type": "bearer"
}
3

Utiliser les jetons

Les jetons d’accès doivent être fournis à chaque appel API, spécifiés dans l’en-tête Authorization après un préfixe Bearer. Par exemple :
API call using cURL
curl -H "Authorization: Bearer <access token>" https://api.hyperline.co/v1/customers

​
Expiration des jetons

Les jetons d’accès sont limités dans le temps — vous devez les rafraîchir périodiquement à l’aide du jeton de rafraîchissement. Les limites de temps sont listées ci-dessous.
  • Jeton d’accès : 24 h
  • Jeton de rafraîchissement : n’expire pas automatiquement (peut être révoqué)
Vous pouvez utiliser le champ expires_in pour connaître le nombre de secondes restantes avant l’expiration du jeton d’accès de l’application. Veillez à le renouveler avant qu’il n’atteigne zéro.

​
Gestion des jetons

​
Rafraîchir un jeton

Si vous souhaitez renouveler un jeton d’accès, vous pouvez effectuer une requête POST à https://api.hyperline.co/v1/oauth/tokens (ou https://sandbox.api.hyperline.co/v1/oauth/tokens), en incluant les attributs suivants dans un corps JSON :
  • client_id : reçu lors de l’enregistrement de l’application
  • client_secret : reçu lors de l’enregistrement de l’application
  • grant_type: "refresh_token"
  • refresh_token : reçu lors du premier flux d’autorisation

​
Révoquer un jeton

Une fois émis, les jetons d’accès ne peuvent pas être révoqués de la même manière que les cookies avec des ID de session pour les sessions côté serveur. Par conséquent, les jetons doivent être rafraîchis périodiquement si l’utilisateur reste actif. Vous pouvez révoquer les jetons de rafraîchissement s’ils deviennent compromis. Effectuez simplement une requête POST à https://api.hyperline.co/v1/oauth/revoke (ou https://sandbox.api.hyperline.co/v1/oauth/revoke), en incluant les attributs suivants dans un corps JSON :
  • client_id : reçu lors de l’enregistrement de l’application
  • client_secret : reçu lors de l’enregistrement de l’application
  • token : jeton de rafraîchissement que vous souhaitez révoquer

​
Comptes multiples

Découvrez les comptes multiples sur Hyperline.
Chaque jeton d’accès donne accès à toutes les entreprises associées à l’utilisateur. Pour récupérer la liste de toutes les entreprises accessibles par l’utilisateur, utilisez l’endpoint https://api.hyperline.co/v1/companies. Pour cibler une entreprise particulière, incluez l’en-tête Hyperline-CompanyId dans chaque requête API.
Si un utilisateur a accès à plusieurs entreprises et que vous ne spécifiez pas l’en-tête Hyperline-CompanyId, la première entreprise (la plus ancienne) liée à l’utilisateur sera utilisée.Nous recommandons d’inclure cet en-tête par défaut lors de la construction d’une application/flux tiers.