Découvrez où se trouve votre clé API Karbon dans Karbon et comment créer votre premier appel vers un point final dans Postman.

Les applications personnalisées qui interagissent avec l'API Karbon auront besoin de la clé d'accès à l'API de votre locataire avant de pouvoir interagir avec vos données. Voici comment la trouver en trois étapes simples :

1. Enregistrez votre application

Rendez-vous sur https://developers.karbonhq.com et soumettez votre nouvelle application. L'application devra être approuvé avant que vous puissiez récupérer la clé d'accès à l'API de votre locataire.

2. Connectez-vous à Karbon et accédez aux paramètres de vos applications connectées

Connectez-vous à Karbon et allez dans « Paramètres » dans la barre latérale, puis cliquez sur « Applications connectées ».

3. Trouvez votre intégration personnalisée et cliquez sur « Gérer »

Votre clé API s'affichera sur la page suivante. Utilisez cette clé en conjonction avec votre jeton d'autorisation d'application pour interagir avec l'API de Karbon.

Remarque : N'oubliez pas de ne donner cette clé d'accès qu'aux personnes et aux applications en qui vous avez confiance.
​

Vous vous êtes inscrit à l'API Karbon et vous disposez de votre clé d'application et de votre clé API. Il est maintenant temps de passer à l'action. L'application de test d'API la plus courante semble être Postman, voici donc un aperçu de l'utilisation de cet outil.

1. Ouvrez Postman et commencez par télécharger la spécification OpenAPI à partir de developers.karbonhq.com.

Glissez-déposez la spécification OpenAPI téléchargée dans la boîte de dialogue d'importation de Postman.

Si tout a été saisi correctement, vous devriez voir une nouvelle collection dans Postman :

2. Ajout de l'accès et de la clé API

Nous allons créer un environnement et ajouter ces importantes clés d'accès dans des variables. Il existe des moyens encore plus sûrs de gérer ces clés et nous vous suggérons de les mettre en œuvre et de suivre les bonnes pratiques.

Editez la collection Karbon API 3.0 et ajoutez un type de Token Bearer d'autorisation.

Ajoutez la variable

que vous avez créée lorsque vous avez ajouté la variable dans l'environnement.

Veillez à définir votre baseUrl comme suit

Il ne nous reste plus qu'à ajouter la clé d'accès à l'en-tête :

Nous avons créé un préréglage qui est plus facile à gérer, mais vous pouvez l'ajouter à chaque point de terminaison si vous le souhaitez.

Et voilà, c'est parti! Nous avons simplement utilisé le point de terminaison Personnes-ressources avec la méthode GET et supprimé tous les paramètres.

3. Bon codage!

L’interface API publique de Karbon nécessite que deux en-têtes HTTP distincts soient définis pour authentifier une requête : Authorization et AccessKey (noter l’orthographe anglais d'Authorization).

S’il y a un problème avec les renseignements d’authentification que vous avez fournis avec votre requête API, le serveur API renverra un code de réponse 401 et un message d’erreur tel que Unauthorized. Auth token is missing or invalid.

Vous trouverez ci-dessous quelques raisons courantes de problèmes d’authentification, ainsi que des vérifications qui pourraient vous aider à authentifier correctement votre requête.

De nombreux utilisateurs d’API qui rencontrent des problèmes d’authentification ont accidentellement inversé les valeurs affectées aux en-têtes Authorization et AccessKey.

Notez : les exemples de Application ID et AccessKey ci-dessus ne vous permettront pas d’authentifier votre requête.

Voici un scénario similaire au précédent, mais une ou les deux valeurs sont totalement manquantes. Le message d’erreur peut vous aider à identifier quel champ pose problème :

Certains outils d’intégration peuvent ajouter automatiquement le préfixe Bearer avant l’Application ID — pour vérifier si c’est votre cas, essayez de supprimer le préfixe Bearer de la valeur que vous envoyez dans l’en-tête Authorization.

Certains points de terminaison ne sont pas accessibles à tous les utilisateurs de l’API — dans ce cas, vous verrez un code de réponse 401 et soit aucun message d’erreur, soit un message expliquant la restriction d’accès spécifique appliquée.