Commencez à utiliser l'API Cloud

Remarque : Si vous utilisez déjà l'API Caseware Cloud et que vous avez mis en œuvre la version 1, veuillez planifier votre transition vers la version 2. Si vous êtes un nouvel utilisateur, veillez à commencer par la version 2. Tous les exemples sont tirés de la version 2.

L'API Caseware Cloud propose un ensemble d'opérations API permettant d'automatiser la gestion des données de votre cabinet, telles que les clients, les utilisateurs, les groupes, les autorisations, etc.

L'application SDK illustre les points suivants :

Points de terminaison disponibles et opérations possibles sur chaque point de terminaison
Paramètres d'entrée et de sortie pour chaque opération
En-têtes obligatoires et d'en-têtes de réponse

Authentification et autorisation

En enregistrant un client API et en obtenant un jeton API, vous pouvez envoyer des requêtes aux points de terminaison de l'API Cloud. L'API Caseware Cloud s'articule autour de l'architecture REST. Les URL prévisibles orientées ressources fournissent des réponses au format JSON, ainsi que des codes de réponse HTTP standard.

L'API Cloud respecte les exigences d'authentification du flux d'autorisation par identifiants client du protocole OAuth 2.0. Ce flux est conçu pour permettre une communication confidentielle de serveur à serveur, sans intervention d'un utilisateur final.

Pour commencer :

Obtenez un identifiant client et une clé secrète client. Pour plus d'informations, consultez la section Paramètres de l'entreprise - Intégration .
Ensuite, utilisez l'identifiant client et la clé secrète générés pour obtenir un jeton API via la requête POST /auth/token :

Demande

curl --location 'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/v2/auth/token' \
        --header 'accept: application/json' \
        --header 'Content-Type: application/json' \
        --data '{
        "ClientId": "966592b3-8586-4541-9909-f7a901ef0b9a",
        "ClientSecret": "sg1eb53tkbn6dez0momdxr0gm87fih1kkoekm40u",
        "Language": "en"
        }'

Réponse

Code d'état : 200 OK


            {
            "Token": "YTA1NGNiOTgtOWJjOS02NDg5LWIyYTgtZTZhNDA5MDJiNGQwOjk1Y2U2YmRjLWUzMDktMmMxZS00ZDYyLWY5NWJmZGE4MGY1ZjpiYTk4OTc1YS04Mjc4LTRhZWEtOWVjOC0wMDcyM2FhMjRjNGY="
            }

Utilisez le jeton API en tant que jeton « bearer » dans un en-tête d'autorisation pour effectuer d'autres requêtes API. Le jeton API reste valable pendant 30 minutes.

Durée de vie de la session

Chaque authentification via l'API Cloud génère une nouvelle session d'une durée de 30 minutes, qui n'entraîne pas l'invalidation des sessions précédentes. La réinitialisation d'un secret client invalide toutes les sessions existantes de ce client API. Par conséquent, une nouvelle autorisation est nécessaire.

Politique de limitation du nombre de requêtes

La limite de débit vise à éviter l'épuisement des ressources de l'API Cloud. Lorsqu'un client API effectue une requête, la disponibilité des ressources diminue temporairement, puis est rétablie après un certain délai.

Lorsqu'aucune ressource n'est disponible, le code d'état HTTP 429 (nombre de requêtes trop élevé) est renvoyé. Vous pouvez utiliser l'en-tête de réponse « ratelimit » pour déterminer le nombre de requêtes restantes, la capacité de pointe, le taux de réapprovisionnement et le nombre de jetons demandés. L'algorithme du « token bucket » régule les requêtes entrantes. Imaginez un seau rempli de jetons. Lorsqu'une requête API est effectuée, un jeton doit être extrait du compartiment pour permettre la suite du traitement de la requête. La requête API est rejetée si aucun jeton n'est disponible dans le compartiment. Les jetons sont automatiquement ajoutés au réservoir au rythme de réapprovisionnement, à mesure que les requêtes API consomment des jetons issus du pool disponible.

En-têtes de réponse

En-tête	Description
x-ratelimit-burst-capacity	Le nombre maximal de jetons que le compartiment peut contenir et qui peuvent être utilisés en une seconde.
x-ratelimit-remaining	Le nombre de jetons restants dans le panier.
x-ratelimit-replenish-rate	Le nombre de jetons réapprovisionnés par seconde.
x-ratelimit-requested-tokens	Le nombre de jetons nécessaires pour effectuer une requête API.

Remarque : Les valeurs de la configuration de limitation du débit sont susceptibles de changer. Ne codez pas ces valeurs en dur.

Consulter la documentation de l'API

Le point de terminaison et les paramètres de l'API Cloud sont décrits dans l'application Caseware Cloud SDK :

Pour consulter la documentation de l'API :

Dans votre navigateur, rendez-vous à l'adresse suivante :

https://{region}.casewarecloud.com/{firm}/sdk

À gauche, développez /caseware-cloud
Veuillez sélectionner la version que vous utilisez.
Utilisez la fonction de recherche pour trouver l'opération dont vous avez besoin :

Les paramètres de requête pouvant être utilisés dans la requête API sont décrits ci-dessous.

Pour consulter le format de l'URL de la requête, développez le menu déroulant de la signature du point de terminaison :

Veuillez vous reporter aux exemples de réponses figurant à droite pour consulter la liste et la description des données que vous pouvez vous attendre à trouver dans la réponse.