Cas d'utilisation courants

Dans l'API Caseware Cloud, de nombreux cas d'utilisation courants impliquent l'utilisation du paramètre de requête de recherche dans les requêtes GET pour filtrer les objets que vous souhaitez récupérer. Voir les exemples de requêtes couramment utilisées ci-dessous. Pour la syntaxe des requêtes, voir Syntaxe des requêtes GET.

Filtrer par GUID

LeCWGuid est un identifiant unique au niveau mondial qui permet d'identifier les objets dans les différentes unités commerciales. Il est disponible en tant que paramètre de chemin pour les objets récupérables dans plusieurs points de terminaison de la V2 de l'API Cloud. Vous pouvez récupérer le CWGuid après avoir créé un objet, tel qu'une entité ou une personne, ou en récupérant une liste d'objets. Vous pouvez également extraire le CWGuid des résultats de la recherche en utilisant un autre champ. Par exemple, si vous recherchez des entités, effectuez une recherche par nom ou par numéro.

Récupérer le CWGuid dans les résultats de la recherche

Si vous ne connaissez pas le CWGuid de l'objet que vous souhaitez récupérer, utilisez une demande de liste filtrée GET pour effectuer une recherche sur un champ différent. Dans cet exemple, le paramètre de recherche est utilisé pour rechercher un objet Entité dont le nom est "Canada Tiny Homes Ltd"

Avant l'encodage de l'URL, l'exemple ci-dessous se présente comme suit :

https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/v2/entities?search=Name = 'Canada Tiny Homes Ltd.'

Dont vous avez besoin pour cet exemple : GET /api/v2/entités

Exemple de requête curl

                  curl --location 'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/v2/entities?search=Name = 'Canada Tiny Homes Ltd.'=null' \ --header 'Authorization : Bearer ZjlhMDUxMTUtZTU1Ny00MWU5LWY1MzQtZDNkYWJlOTU3OTljOjZlYzExMTZlLTdlOWEtOTQ5Mi01ODFkLWI3ZWJmYWQ3ZDU2YjpiYTIxYWRhOC05NzdlLTRkZjgtYWY0Ny03ZTQ3M2IxNDMzNzg'

Récupérer un objet à l'aide de son CWGuid

Lorsque vous connaissez le CWGuid de l'objet que vous souhaitez récupérer, il existe des points de terminaison pour lesquels cwGuid est un paramètre de chemin.

Avant l'encodage de l'URL, l'exemple ci-dessous se présente comme suit :

https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/v2/entities/208e79df-851f-4be7-93f6-25d54fccb6b2

Dont vous avez besoin pour cet exemple : GET /api/v2/entities/{entityId}

Exemple de requête curl

curl --location 'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/{version-number}/entities/208e79df-851f-4be7-93f6-25d54fccb6b2 ' \ --header 'Authorization : Bearer NTVjY2EyNjEtYTJhZi05NzNhLWRiMWMtZDFiZWVkM2M0YmJhOmNlMTYxMDE1LWJlMGQtN2I2ZS0yYzFlLTQyNDA0YjNkMjJiNTpiYTIxYWRhOC05NzdlLTRkZjgtYWY0Ny03ZTQ3M2IxNDMzNzg'

Filtrer toutes les entités en utilisant EntityNo

Dont vous avez besoin pour cet exemple : GET /api/{numéro de version}/entités

Les valeurs spécifiées pour EntityNo doivent comporter 10 caractères. Si un EntityNo n 'a pas 10 caractères, vous devez l'aligner à droite et le remplir d'espaces vides. Par exemple, si l'EntitéNo est définie sur A2 , votre requête doit être EntityNo=' A2'. Des modifications de la requête API sont en cours afin que les développeurs n'aient plus besoin de remplir les données avec des espaces vides. Cette documentation sera mise à jour dès qu'elle sera disponible.

Conseil : La plupart des champs qui peuvent être utilisés pour formuler des requêtes (spécifiés comme valeur du paramètre de requête de recherche) sont décrits dans les exemples de réponses pour l'objet que vous interrogez. Par exemple, si vous interrogez des entités, les champs qui peuvent être interrogés sont énumérés dans l'exemple de réponse de code 200 :

Exemple de requête curl

curl -X 'GET' \                  'https://<region>.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/entities?search=EntityNo%3D%271234567890%27&page=1&pageSize=50' \                  -H 'accept: application/json' \                  -H 'Authorization: Bearer YmFjMGU4MDgtZmFjMC1kMmQzLTZkNjEtZGRmNjdiNWQzMTY5OjczOGYyZGU1LTc2YTctMzRjNC00NzhkLWQ3NGQ1ZTY5MTRhZDo1'

Filtre sur les métadonnées de l'entité

Dont vous avez besoin pour cet exemple : GET /api/{numéro de version}/entités

Vous pouvez définir le paramètre de recherche pour filtrer les entités en fonction de leurs métadonnées personnalisées. Le format de la requête de recherche de métadonnées d'entité change en fonction de l'endroit où elle a été créée :

Propriétés d'entités personnalisées créées dans les paramètres de l'entreprise

Rappelons que la syntaxe des requêtes utilisant le paramètre search query est la suivante :

<Nom du champ><opérateur><valeur du champ>

Remplacer <nom du champ> par métadonnées[{nom}]

• Où {Nom} est le GUID qui est généré par Caseware Cloud lorsque vous créez une propriété d'entité personnalisée dans Paramètres | Personnalisation | Propriétés d'entités personnalisées. Pour plus d'informations, voir Récupérer le GUID d'une propriété d'entité personnalisée créée dans les paramètres de l'entreprise .

Récupérer le GUID d'une propriété d'entité personnalisée créée dans les paramètres de l'entreprise

1. Connectez-vous à votre entreprise Caseware Cloud.
2. Affichez les outils de développement dans votre navigateur. Par exemple, dans Google Chrome, tapez Ctrl + Shift + C.
3. From the Cloud menu (), select Settings | Customization | Custom Entity Properties. Voir Propriétés du groupe pour plus d'informations.
4. Sélectionnez un champ d'entité personnalisé existant ou ajoutez-en un.
5. Sélectionnez Réseau , puis le filtre Fetch/XHR .
6. Localisez l'appel API GetEntityMetadataGroupAndDisplay et sélectionnez le filtre Response pour afficher le message de réponse en JSON.
7. Localisez l'attribut Name . Sa valeur est un GUID. Dans l'exemple de format ci-dessus, remplacez Nom par ce GUID. Voir l'exemple ci-dessous.

Exemple de requête curl

curl --request GET \ --url 'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/{version-number}/entities?search=metadata[eb367d1d-1634-416b-bcba-b748ec8146e4]='\''2024-02-08'\''' \N- --header 'Authorization : Bearer OTY5OGVkMmUtZGY1NC0xYTE5LWU0YjYtNzkyNzVlY2I3Y2I0OmY0YWY5ZTZmLTA3YzQtZWU3Mi05MjczLWE1M2M5Y2Q3NTkwYjpmMWVlODEwMy1mMGYwLTRkNDItYmZmZC0zMWVjYTNkMDkyNTA' 

Obtenir la chaîne de contexte pour mettre à jour les métadonnées de l'entité

La méthode suivante s'applique lorsqu'un champ d'entité personnalisé a été créé dans Caseware Cloud :

1. Connectez-vous à votre entreprise Caseware Cloud.
2. From the Cloud menu (), select Settings | Customization | Custom Entity Properties. Voir Propriétés du groupe pour plus d'informations.
3. Sélectionnez un champ d'entité personnalisé existant ou ajoutez-en un.
4. Sélectionnez Réseau , puis le filtre Fetch/XHR .
5. Localisez l'appel API GetEntityMetadataGroupAndDisplay et sélectionnez le filtre Response pour afficher le message de réponse en JSON.
6. Identifier la valeur de Contexte et l'utiliser dans la requête PUT /entities/{entityId}/metadata/{context} .

Exemple de réponse pour GetEntityMetadataGroupAndDisplay

j {  						"result": [ { "DefaultDisplayName" : "Champ personnalisé", "Ordre" : 1, "EntityMetadataDisplayList" : Type: "Case à cocher", "MultipleChoiceItems" : { "@context" : "dfc67a64-2797-4d92-ac0a-47111594f61f", "Name": "f5c4f531-f947-40c2-9ce4-05a09c6b143d", "DefaultDisplayName": "Case à cocher", "Ordre" : 1, "MultiValueByDate" : false, "IsRequired" : false } ], "EntityType" : "Client" } ], "error" : [],  						"Errors": [],  						"warning": []  						}  						}

Filtrer les entités par entityId

Dans Caseware Cloud, vous pouvez obtenir l'ID de l'entité dans laquelle vous vous trouvez actuellement à partir de l'URL de votre entreprise. Dans l'exemple ci-dessous, entityId = 4 :

Dont vous avez besoin pour cet exemple : GET /api/v1/entities/{entityId}

Exemple de requête curl

curl -X 'GET' \          'https://<region>.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/entities/4' \          -H 'accept: application/json' \          -H 'Authorization: Bearer MDdiZTQ1ZjUtZDY0NC1jZDI3LTZlZGQtOWYyZTFkYjQwNjY4OjEwNTUyYzFhLTU0MGItMTM3Ny0yYzA3LTRhYThhZjYwNGFlNTo1'

Filtrer les utilisateurs par courriel

Dont vous avez besoin pour cet exemple : GET /api/{numéro de version}/utilisateurs

Exemple de requête curl

curl -X 'GET' \          'https://<region>.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/users?search=Email%3D%27domain.admin%40yourfirm.com%27&page=1&pageSize=50' \          -H 'accept: application/json' \          -H 'Authorization: Bearer YzZhZGUxNjItZDQ1MS01MjYyLWUyZjEtYjgwYWYxNTdhYmEwOmRjNmI3YWRhLTAxM2ItMmMyNi1iZjhhLTY4ODEyZjc0OTI3ZTo1'

Conseil : Conseil La plupart des champs qui peuvent être utilisés pour formuler des requêtes (spécifiés comme valeur du paramètre de requête de recherche) sont décrits dans le schéma du corps de la requête dans l'opération POST Create pour l'objet que vous interrogez. Par exemple, si vous interrogez des utilisateurs, consultez l'opération POST Create pour les utilisateurs :

Filtrer les utilisateurs par ID

Dont vous avez besoin pour cet exemple : GET /api/v1/users/{userId}

Exemple de requête curl

curl -X 'GET' \          'https://<region>.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/users/2' \          -H 'accept: application/json' \          -H 'Authorization: Bearer YWJhZDE3MmQtMGIyOC1hZWVlLWZjM2EtY2VmZjBlYjUwZWNiOjJkODdiODY1LTY0NTUtNjgwNS0xMDQ5LWFjZWMzMWI5ZTZkNTo1'

Filtrer les rôles sur la base du nom (du rôle)

Dont vous avez besoin pour cet exemple : GET /api/{numéro de version}/rôles

Conseil : La plupart des champs (ou paramètres de requête) qui peuvent être utilisés pour former des requêtes dans les requêtes GET sont décrits dans le schéma du corps de la requête dans l'opération POST ou PATCH pour l'objet que vous interrogez. Par exemple, si vous interrogez des rôles, consultez l'opération PATCH Update pour les affectations de rôles :

Exemple de requête curl

curl -X 'GET' \          'https://<region>.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/roles?search=Name%3D%27Contact%20-%20Entity%20Access%27&page=1&pageSize=50' \          -H 'accept: application/json' \          -H 'Authorization: Bearer YWJhZDE3MmQtMGIyOC1hZWVlLWZjM2EtY2VmZjBlYjUwZWNiOjJkODdiODY1LTY0NTUtNjgwNS0xMDQ5LWFjZWMzMWI5ZTZkNTo1'

Filtrer toutes les offres de documents de travail confidentiels

Dont vous avez besoin pour cet exemple : GET /api/{numéro de version}/engagements

Champs utilisés pour créer la requête dans l'exemple de demande

Exemple de requête curl

curl -X 'GET' \          'https://<region>.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/engagements?search=Confidential%3D%27true%27&itemType=WorkingPapersBundle&page=1&pageSize=50' \          -H 'accept: application/json' \          -H 'Authorization: Bearer NTliMDQ5ZjMtZmVkYi0xMDYwLWViYjItMTFkZTM1MjI2YTA2OjAxMTUzNzVkLWJhOTctOGQwMy0wNTY3LTVkODBhZDBjODgzMzo1'