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 search 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 de consulta, 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.'

Por ejemplo:

• Antes de la codificación:
  
  search=Name='Caseware International'
• Después de la codificación:
  
  search=Name%3D'Caseware%20International'

Si no se codifica la consulta, pueden producirse errores o no obtenerse resultados. Puede utilizar herramientas como encodeURIComponent para codificar sus cadenas de consulta.

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.

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'

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

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'