Casos de uso común

En la API de Caseware Cloud, muchos casos de uso común implican el uso del parámetro de consulta de búsqueda en las solicitudes GET para filtrar los objetos que desea recuperar. Vea a continuación los ejemplos de consultas más frecuentes. Para la sintaxis deconsulta, consulte Sintaxis de consulta en solicitudes GET.

Filtrar por GUID

CWGuid es un identificador único global para identificar objetos en todas las unidades de negocio. Está disponible como parámetro de ruta para objetos recuperables en varios endpoints de V2 de Cloud API. Puede recuperar el CWGuid después de crear un objeto, como una Entidad o Persona, o recuperando una lista de objetos. También puede recuperar el CWGuid de los resultados de la búsqueda utilizando un campo diferente. Por ejemplo, si busca entidades, busque por nombre o número.

Recuperar el CWGuid de los resultados de búsqueda

Si no conoce el CWGuid del objeto que desea recuperar, utilice una solicitud de lista filtrada GET para buscar en un campo diferente. En este ejemplo, el parámetro de consulta search se utiliza para buscar un objeto Entidad cuyo Nombre es `Canada Tiny Homes Ltd.`

Antes de la codificación URL, el ejemplo siguiente tiene este aspecto:

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

Endpoint que necesita para este ejemplo: GET /api/v2/entities/

Ejemplo de solicitud 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: Bearer ZjlhMDUxMTUtZTU1Ny00MWU5LWY1MzQtZDNkYWJlOTU3OTljOjZlYzExMTZlLTdlOWEtOTQ5Mi01ODFkLWI3ZWJmYWQ3ZDU2YjpiYTIxYWRhOC05NzdlLTRkZjgtYWY0Ny03ZTQ3M2IxNDMzNzg='

Recuperar un objeto utilizando su CWGuid

Si conoce el CWGuid del objeto que desea recuperar, existen puntos finales en los que cwGuid es un parámetro de ruta.

Antes de la codificación URL, el ejemplo siguiente tiene este aspecto:

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

Endpoint que necesita para este ejemplo: GET /api/v2/entities/{cwGuid}

Ejemplo de solicitud curl

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

Filtrar todas las entidades utilizando EntityNo

Endpoint que necesita para este ejemplo: GET /api/{número de versión}/entidades

Los valores especificados para EntityNo deben tener 10 caracteres. Si un número de entidad no tiene 10 caracteres, debe alinearlo a la derecha y rellenarlo con espacios vacíos. Por ejemplo, si EntityNo es A2 , la consulta debe ser EntityNo=' A2'. Se están introduciendo cambios en la consulta de la API para garantizar que los desarrolladores ya no tengan que rellenar la entrada con espacios vacíos. Esta documentación se actualizará cuando esté disponible.

Sugerencia: La mayoría de los campos que pueden utilizarse para formar consultas (especificados como el valor del parámetro de consulta de búsqueda) se describen en los ejemplos de respuesta para el objeto que está consultando. Por ejemplo, si está consultando entidades, los campos que se pueden consultar se enumeran en el ejemplo de respuesta de código 200:

Ejemplo de solicitud curl

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

Filtrar por metadatos de entidad

Endpoint que necesita para este ejemplo: GET /api/{número de versión}/entidades

Puede establecer el parámetro de consulta search para filtrar entidades por sus metadatos de entidad personalizados. El formato de la consulta de búsqueda de metadatos de entidad cambia en función de dónde se haya creado:

Propiedades de entidad personalizadas creadas en la configuración de la empresa

Recordemos que la sintaxis de las consultas que utilizan el parámetro de consulta de búsqueda es la siguiente:

<nombre de campo><operador><valor de campo>

Sustituya <nombredecampo> por metadatos[{Nombre}]

• Donde {Name} es el GUID que genera Caseware Cloud cuando se crea una propiedad de entidad personalizada en Configuración | Personalización | Propiedades de entidad personalizadas. Consulte Recuperar el GUID de una propiedad de entidad personalizada creada en la configuración de la empresa para obtener más información.

Recuperar el GUID de una propiedad de entidad personalizada creada en la configuración de la empresa

1. Inicie sesión en su empresa Caseware Cloud.
2. Muestra las herramientas para desarrolladores en tu navegador. Por ejemplo, en Google Chrome, escriba Ctrl + Mayús + C.
3. En el menú Nube (), seleccione Configuración | Personalización | Propiedades de entidad personalizadas. Para más información, consulte Propiedades de entidad personalizadas .
4. Seleccione un campo de entidad personalizado existente o añada uno.
5. Seleccione Red y, a continuación, el filtro Fetch/XHR .
6. Localice la llamada a la API GetEntityMetadataGroupAndDisplay y seleccione el filtro Response para ver el mensaje de respuesta en JSON.
7. Localice el atributo Nombre . Su valor es un GUID. En el ejemplo de formato anterior, sustituya Nombre por este GUID. Véase el ejemplo siguiente.

Ejemplo de solicitud 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: Bearer OTY5OGVkMmUtZGY1NC0xYTE5LWU0YjYtNzkyNzVlY2I3Y2I0OmY0YWY5ZTZmLTA3YzQtZWU3Mi05MjczLWE1M2M5Y2Q3NTkwYjpmMWVlODEwMy1mMGYwLTRkNDItYmZmZC0zMWVjYTNkMDkyNTA=' 

Obtener la cadena de contexto para actualizar los metadatos de la entidad

El siguiente método se aplica cuando se ha creado un campo de entidad personalizado en Caseware Cloud:

1. Inicie sesión en su empresa Caseware Cloud.
2. En el menú Nube (), seleccione Configuración | Personalización | Propiedades de entidad personalizadas. Para más información, consulte Propiedades de entidad personalizadas .
3. Seleccione un campo de entidad personalizado existente o añada uno.
4. Seleccione Red y, a continuación, el filtro Fetch/XHR .
5. Localice la llamada a la API GetEntityMetadataGroupAndDisplay y seleccione el filtro Response para ver el mensaje de respuesta en JSON.
6. Identifique el valor de Context y utilícelo en la solicitud PUT /entities/{entityId}/metadata/{context} .

Ejemplo de respuesta para 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": []  						}  						}

Filtrar entidades por entityId

En Caseware Cloud, puede obtener el ID de la entidad en la que se encuentra actualmente a partir de la URL de su empresa. En el ejemplo siguiente, entityId = 4:

Endpoint que necesita para este ejemplo: GET /api/{version-number}/entities/{entityId}

Ejemplo de solicitud curl

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

Filtrar usuarios por correo electrónico

Endpoint que necesita para este ejemplo: GET /api/{version-numero}/usuarios

Ejemplo de solicitud 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: Bearer YzZhZGUxNjItZDQ1MS01MjYyLWUyZjEtYjgwYWYxNTdhYmEwOmRjNmI3YWRhLTAxM2ItMmMyNi1iZjhhLTY4ODEyZjc0OTI3ZTo1'

Sugerencia: La mayoría de los campos que se pueden utilizar para formar consultas (especificados como valor del parámetro de consulta de búsqueda) se describen en el esquema del cuerpo de la solicitud en la operación POST Create para el objeto que está consultando. Por ejemplo, si está consultando usuarios, consulte la operación POST Crear para usuarios:

Filtrar usuarios por ID

Endpoint que necesita para este ejemplo: GET /api/{version-number}/users/{userId}

Ejemplo de solicitud curl

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

Filtrar roles en función del nombre (del rol)

Endpoint que necesita para este ejemplo: GET /api/{version-number}/roles

Sugerencia: La mayoría de los campos (o parámetros de consulta) que se pueden utilizar para formar consultas en peticiones GET se describen en el esquema del cuerpo de la petición en la operación POST o PATCH para el objeto que está consultando. Por ejemplo, si está consultando roles, consulte la operación de actualización PATCH para la asignación de roles:

Ejemplo de solicitud 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: Bearer YWJhZDE3MmQtMGIyOC1hZWVlLWZjM2EtY2VmZjBlYjUwZWNiOjJkODdiODY1LTY0NTUtNjgwNS0xMDQ5LWFjZWMzMWI5ZTZkNTo1'

Filtrar todos los documentos de trabajo confidenciales

Endpoint que necesita para este ejemplo: GET /api/{version-number}/engagements

Campos utilizados para crear la consulta en la solicitud de ejemplo

Ejemplo de solicitud 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: Bearer NTliMDQ5ZjMtZmVkYi0xMDYwLWViYjItMTFkZTM1MjI2YTA2OjAxMTUzNzVkLWJhOTctOGQwMy0wNTY3LTVkODBhZDBjODgzMzo1'