Cas d'utilisation courants

Dans l'API Caseware Cloud, de nombreux cas d'utilisation courants impliquent l'utilisation du paramètre de requête search dans les requêtes GET afin de filtrer les objets que vous souhaitez récupérer. Vous trouverez ci-dessous des exemples de cas d'utilisation courants. Pour la syntaxe des requêtes, veuillez consulter La syntaxe des requêtes dans les requêtes GET.

Filtrer par GUID

CWGuid est un identifiant unique au niveau mondial permettant d'identifier des objets dans l'ensemble des unités opérationnelles. Il est disponible en tant que paramètre de chemin d'accès pour les objets récupérables dans plusieurs points de terminaison de la version 2 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 recherche à l'aide d'un autre champ. Par exemple, si vous recherchez des entités, effectuez votre recherche par nom ou par numéro.

Récupérer le CWGuid à partir des résultats de recherche

Si vous ne connaissez pas le CWGuid de l'objet que vous souhaitez récupérer, utilisez une requête GET avec liste filtrée pour effectuer une recherche sur un autre champ. In this example, the search query parameter is used to search for an Entity object whose Name is `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.'

Par exemple :

• Avant l'encodage :
  
  search=Name='Caseware International'
• Après l'encodage :
  
  search=Nom%3D%27Caseware%20International%27

Si vous ne codez pas la requête, cela peut entraîner des erreurs ou ne pas renvoyer de résultats. Vous pouvez utiliser des outils tels que encodeURIComponent pour encoder vos chaînes de requête.

Point de terminaison requis pour cet exemple : GET /api/v2/entities/

Exemple de requête Curl

                curl --location 'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/v2/entities?search%3DName%20%3D%20%27Canada%20Tiny%20Homes%20Ltd.%27=null' \
 --header 'Authorization: Porteur ZjlhMDUxMTUtZTU1Ny00MWU5LWY1MzQtZDNkYWJlOTU3OTljOjZlYzExMTZlLTdlOWEtOTQ5Mi01ODFkLWI3ZWJmYWQ3ZDU2YjpiYTIxYWRhOC05NzdlLTRkZjgtYWY0Ny03ZTQ3M2IxNDMzNzg='

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

Si 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 d'accès.

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

Point de terminaison requis pour cet exemple : GET /api/v2/entities/{cwGuid}

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: Au porteur NTVjY2EyNjEtYTJhZi05NzNhLWRiMWMtZDFiZWVkM2M0YmJhOmNlMTYxMDE1LWJlMGQtN2I2ZS0yYzFlLTQyNDA0YjNkMjJiNTpiYTIxYWRhOC05NzdlLTRkZjgtYWY0Ny03ZTQ3M2IxNDMzNzg='

Filtrer toutes les entités à l'aide du numéro d'entité (EntityNo)

Point de terminaison requis pour cet exemple : GET /api/{numéro-de-version}/entités

Entité : aucune règle

EntityNo est un code client/groupe utilisé pour identifier de manière unique une entité dans Caseware Cloud. Les valeurs « EntityNo » doivent comporter entre 1 et 20 caractères ; la distinction entre majuscules et minuscules est prise en compte.

Règles de mise en forme lors de l'utilisation d'EntityNo dans les requêtes de recherche

• Pour le champ « EntityNo » : au moins 10 caractères ; compléter par des espaces à gauche jusqu'à 10 caractères.

Exemple de requête de recherche avant l'encodage de l'URL :

EntityNo=' abc'

• Si le numéro d'entité comporte au maximum 10 caractères, veuillez envoyer la valeur telle qu'elle a été saisie.

Exemple

EntityNo='12345678901234'

Important

Lorsque vous utilisez le paramètre de requête de recherche, l'intégralité de la chaîne de requête doit être encodée en URL, y compris les espaces, les signes égal = et les guillemets '.

Par exemple :

Avant l'encodage :

search=EntityNo='1234567890'

Après l'encodage :

search=EntityNo%3D%271234567890%27

Exemple de requête Curl

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

Conseil : La plupart des champs pouvant être utilisés pour formuler des requêtes (spécifiés comme valeur du paramètre de recherche) sont décrits dans les exemples de réponse correspondant à l'objet que vous interrogez. Par exemple, si vous effectuez une requête sur des entités, les champs pouvant faire l'objet d'une requête sont répertoriés dans l'exemple de réponse avec le code 200 :

Filtrer par métadonnées d'entité

Point de terminaison requis pour cet exemple : GET /api/{numéro-de-version}/entités

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

Propriétés d'entité personnalisées créées dans les paramètres du cabinet

Pour rappel, la syntaxe des requêtes utilisant le paramètre « search » est la suivante :

<nom_champ><opérateur><valeur_champ>

Remplacez <fieldName> par metadata[{Name}]

• Où {Nom} correspond au GUID 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é personnalisées. Pour plus d'informations, consultez Récupérer le GUID d'une propriété d'entité personnalisée créée dans les paramètres du cabinet .

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

1. Connectez-vous à votre compte Caseware Cloud.
2. Affichez les outils de développement dans votre navigateur. Par exemple, dans Google Chrome, tapez Ctrl + Maj + C.
3. Dans le menu Cloud (), sélectionnez Paramètres | Personnalisation | Propriétés des entités personnalisées. Pour plus d'informations, consultez la section Propriétés des entités personnalisées .
4. Sélectionnez un champ d'entité personnalisée existant ou ajoutez-en un.
5. Sélectionnez Réseau , puis le filtre Fetch/XHR .
6. Recherchez l'appel d'API GetEntityMetadataGroupAndDisplay et sélectionnez le filtre Réponse pour afficher le message de réponse au format JSON.
7. Repérez l'attribut Name . Sa valeur est un GUID. Dans l'exemple de format ci-dessus, remplacez Nom par ce GUID. Consultez 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%5Beb367d1d-1634-416b-bcba-b748ec8146e4%5D%3D'\''2024-02-08'\''' \
 --header 'Authorization: Au porteur OTY5OGVkMmUtZGY1NC0xYTE5LWU0YjYtNzkyNzVlY2I3Y2I0OmY0YWY5ZTZmLTA3YzQtZWU3Mi05MjczLWE1M2M5Y2Q3NTkwYjpmMWVlODEwMy1mMGYwLTRkNDItYmZmZC0zMWVjYTNkMDkyNTA=' 

Récupérez la chaîne de contexte permettant de 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 compte Caseware Cloud.
2. Dans le menu Cloud (), sélectionnez Paramètres | Personnalisation | Propriétés des entités personnalisées. Pour plus d'informations, consultez la section Propriétés des entités personnalisées .
3. Sélectionnez un champ d'entité personnalisée existant ou ajoutez-en un.
4. Sélectionnez Réseau , puis le filtre Fetch/XHR .
5. Recherchez l'appel d'API GetEntityMetadataGroupAndDisplay et sélectionnez le filtre Réponse pour afficher le message de réponse au format JSON.
6. Identifiez la valeur de Context et utilisez-la dans la requête PUT /entities/{entityId}/metadata/{context} .

Exemple de réponse pour la méthode GetEntityMetadataGroupAndDisplay

{
						"d": {
						"result": [
						{
						"DefaultDisplayName": "Custom field",
						"Order": 1,
						"EntityMetadataDisplayList": [
						{
						"Type": "Checkbox",
						"MultipleChoiceItems": [],
						"Context": "dfc67a64-2797-4d92-ac0a-47111594f61f",
						"Name": "f5c4f531-f947-40c2-9ce4-05a09c6b143d",
						"DefaultDisplayName": "Check box",
						"Order": 1,
						"MultiValueByDate": false,
						"IsRequired": false
						}
						],
						"EntityType": "Client"
						}
						],
						"error": [],
						"Errors": [],
						"warning": []
						}
						}

Filtrer les entités par entityId

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

Point de terminaison requis pour cet exemple : GET /api/{numéro-de-version}/entities/{identifiant-de-l'entité}

Exemple de requête Curl

curl -X 'GET' \
 'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/{version-number}/entities/4' \
 -H 'accept: application/json' \
 -H 'Authorization: Au porteur MDdiZTQ1ZjUtZDY0NC1jZDI3LTZlZGQtOWYyZTFkYjQwNjY4OjEwNTUyYzFhLTU0MGItMTM3Ny0yYzA3LTRhYThhZjYwNGFlNTo1'

Filtrer les utilisateurs par adresse e-mail

Point de terminaison requis pour cet exemple : GET /api/{numéro-de-version}/users

Exemple de requête Curl

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

Filtrer les utilisateurs par identifiant

Point de terminaison requis pour cet exemple : GET /api/{numéro-de-version}/users/{userId}

Exemple de requête Curl

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

Filtrer les rôles en fonction de leur nom (celui du rôle)

Point de terminaison requis pour cet exemple : GET /api/{numéro-de-version}/roles

Exemple de requête Curl

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

Filtrer l'ensemble des Working Papers confidentiels

Point de terminaison requis 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/{version-number}/engagements?search=Confidential%3D%27true%27&itemType=WorkingPapersBundle&page=1&pageSize=50' \
        -H 'accept: application/json' \
 -H 'Authorization: Au porteur NTliMDQ5ZjMtZmVkYi0xMDYwLWViYjItMTFkZTM1MjI2YTA2OjAxMTUzNzVkLWJhOTctOGQwMy0wNTY3LTVkODBhZDBjODgzMzo1'