Guía de transición-Caseware Cloud API V1 a V2

La API V1 ha ayudado a muchos clientes a automatizar los flujos de trabajo y a garantizar que los datos de Caseware Cloud estén actualizados y sean precisos. Sin embargo, a medida que han ido evolucionando las necesidades de los clientes, hemos recibido comentarios sobre las limitaciones de la V1, especialmente en lo que respecta al trabajo con las unidades de negocio y las etiquetas. Basándonos en estos comentarios, hemos introducido importantes mejoras en la API V2 para satisfacer mejor sus necesidades y ayudarle a trabajar de forma más eficiente.

Las principales mejoras de la API V2 son:

• Compatibilidad con unidades de negocio (BU): Compatibilidad mejorada con la gestión de múltiples unidades de negocio dentro de su organización.

• API de gestión de etiquetas: Un nuevo conjunto de puntos finales de API para automatizar la gestión y asignación de etiquetas para una mejor organización y filtrado.

• Documentación del SDK fácil de usar: Documentación clara y completa del SDK diseñada para simplificar la integración y el desarrollo.

La API V2 se lanzará junto con la V1 para garantizar la compatibilidad con versiones anteriores, por lo que sus integraciones actuales seguirán funcionando durante la transición. No obstante, la API V1 quedará obsoleta el 30 de octubre de 2025, por lo que dispondrá de tiempo suficiente para migrar a la V2 sin interrupciones.

Hemos diseñado estos cambios para que tengan el mayor impacto posible en la mejora de su experiencia, basándonos directamente en los comentarios que hemos recibido. Esta guía le guiará a través de las nuevas funciones, responderá a preguntas comunes sobre diferentes casos de uso y flujos de trabajo, y le ayudará a garantizar una transición fluida y satisfactoria a la API V2.

Respuestas a las preguntas más frecuentes

Información general sobre la API V2

P1: ¿Cuál es la diferencia entre API V1 y V2?

A1: La API V2 aporta varias mejoras clave con respecto a la V1, como una mayor compatibilidad con las unidades de negocio (BU), un sistema de gestión de etiquetas más flexible y un SDK fácil de usar para los desarrolladores con una documentación más clara. Estas actualizaciones están diseñadas para mejorar la eficacia, reducir la curva de aprendizaje de los desarrolladores e introducir las mejores prácticas de integración.

P2: ¿Cómo mejora la API V2 la compatibilidad con las Unidades de Negocio (BU)?

A2: En la API V2, hemos pasado de utilizar identificadores específicos de sitio a identificadores únicos globales (GUID). Esto garantiza que los datos sean identificables de forma única en todas las unidades de negocio, lo que facilita la gestión y la ampliación de las integraciones entre unidades de negocio sin conflictos. Para las organizaciones que no utilizan BU, los GUID siguen ofreciendo una forma más sólida y preparada para el futuro de gestionar los datos, ajustándose a las mejores prácticas y mejorando la flexibilidad de integración.

P3: ¿Seguirán funcionando mis integraciones V1 actuales?

A3: Sí, incluso con el lanzamiento de la API V2, Caseware sigue siendo compatible con la V1 para garantizar que sus integraciones no se vean interrumpidas.

P4: ¿Existe un calendario para la desaparición de la V1?

A4: La V1 seguirá siendo compatible con la V2, por lo que puedes seguir utilizando tus integraciones actuales por ahora. Sin embargo, la API V1 quedará obsoleta el 30 de octubre de 2025. Recomendamos realizar la transición a la V2 antes de esta fecha para garantizar una experiencia sin problemas y aprovechar al máximo las nuevas funciones y mejoras.

P5: ¿Dónde puedo encontrar la documentación de las nuevas funciones de la API V2?

R5: La documentación detallada de la API V2, incluida la información sobre los nuevos puntos finales y funcionalidades, está disponible en nuestra documentación del SDK. Incluye descripciones completas de los nuevos puntos finales de la V2, ejemplos y directrices para ayudarle en la transición de la V1 a la V2. La documentación del SDK está organizada para admitir ambas versiones, por lo que puede cambiar fácilmente entre los puntos finales V1 y V2 en función de sus necesidades de integración. Además, los desarrolladores pueden descargar la especificación de la API abierta directamente desde la documentación del SDK, lo que proporciona un formato estructurado para integrarse con la nueva API V2.

P6: ¿Debo pasar a la V2 aunque no utilice unidades de negocio ni etiquetas?

A6 Sí, recomendamos la transición a la API V2, incluso si actualmente no utiliza unidades de negocio o etiquetas. La API V1 quedará obsoleta con el tiempo y, cuando esto ocurra, su integración actual dejará de ser compatible. Además, desde el punto de vista de las mejores prácticas, la V2 introduce puntos finales que utilizan identificadores únicos globales (GUID), que ofrecen soluciones más fiables y escalables en comparación con las claves no únicas. Hacer la transición le ayudará a preparar su integración para el futuro.

P7: ¿Existen limitaciones o problemas conocidos con la V2?

R7: Aunque la API V2 ofrece varias mejoras, hay que tener en cuenta algunas limitaciones. Por ejemplo, los puntos finales de las etiquetas siguen utilizando ID en lugar de GUID, y tenemos previsto solucionar este problema en futuras versiones. También tenemos previsto lanzar actualizaciones menores de la V2 de forma periódica, incorporando comentarios y añadiendo nuevas funciones. También agradecemos sus valiosos comentarios para ayudarnos a priorizar las mejoras y garantizar que V2 satisfaga sus necesidades.

P8: ¿Habrá futuras actualizaciones de la API V2?

R8: Sí, seguiremos publicando actualizaciones menores de la API V2 con regularidad, incorporando nuevas funciones, mejoras y correcciones de errores. Recomendamos a los desarrolladores que visiten periódicamente el sitio de documentación del SDK para mantenerse al día de los últimos cambios y descargar las especificaciones de la API abierta más recientes. Tenga en cuenta que la API V1 dejará de recibir actualizaciones en el futuro, por lo que le recomendamos que pase a la V2 para beneficiarse de las mejoras y la asistencia continuas.

Preguntas sobre la transición de V1 a V2

P1: ¿Cómo planificar mi transición de V1 a V2?

A1: Puede pasar de V1 a V2 de dos maneras: una migración escalonada o un cambio completo.

• Migración por fases: Migre diferentes integraciones (por ejemplo, entidades, personal o grupos) en fases separadas, probando e implementando cada una a medida que avanza.

• Cambio completo: Actualice todas las integraciones existentes a la vez, pero asegúrese de realizar pruebas exhaustivas en un entorno de pruebas antes de realizar el cambio completo.

Plan your transition

1. Revise la documentación de la API V2.

2. Elija su enfoque de migración (por fases o completa).

3. Actualizar el código de integración para realizar llamadas API a los puntos finales V2.

4. Supervisa la integración tras el cambio.

Este proceso garantiza una transición fluida, independientemente de su enfoque.

Para obtener información detallada sobre la migración de casos de uso específicos, como entidades, personal, etc., consulte las secciones correspondientes a continuación.

P2: ¿Cómo debo gestionar las referencias de ID si tengo una base de datos cartográfica?

A2: Si está utilizando una base de datos de mapeo o middleware para almacenar y referenciar identificadores de objetos CW (como IDs de entidades), le recomendamos que actualice su base de datos para almacenar tanto el ID CW como el correspondiente CWGuid.

Antes de migrar a la V2, puede utilizar la API de la V1 para buscar datos por ID de CW. En la respuesta, encontrará el CWGuid de cada objeto, que podrá utilizar para actualizar su tabla de referencias. Esto garantizará que su sistema esté preparado para la transición a la V2, en la que las CWGuids serán el identificador principal.

P3: ¿Puedo seguir utilizando la V1 durante la transición a la V2?

A3: Sí, puedes seguir utilizando la V1 mientras migras a la V2. Las integraciones V1 y V2 pueden funcionar en paralelo durante este proceso de migración. Por ejemplo, puede ejecutar su integración de entidades en V2 mientras que su integración de personal sigue utilizando V1

P4: ¿Tengo que modificar el código de mis integraciones actuales?

A4: Sí, para aprovechar las nuevas funciones de la V2, tendrá que actualizar sus llamadas a la API a los nuevos puntos finales de la V2. Los cambios específicos necesarios dependerán de los puntos finales que esté utilizando actualmente en la V1.

P5: ¿Cómo puedo obtener ayuda durante la transición?

R5: Nuestro equipo de asistencia está a su disposición para ayudarle con cualquier duda o problema que le surja durante el proceso de transición.

P6: ¿Tengo que crear nuevos clientes API para la V2?

A6: No, no es necesario crear nuevos clientes API o claves para V2. Sus clientes actuales de V1 seguirán funcionando sin problemas con V2. No obstante, si lo prefiere, puede crear nuevos clientes API específicos para V2. Una vez que haya realizado la transición completa a la V2, puede optar por eliminar los antiguos clientes de la V1 para asegurarse de que las integraciones de la V1 ya no se utilizan.

Cuestiones relacionadas con los casos prácticos para la migración a la V2

Entidades

T1 ¿Cómo crear un IDEAScript?

A1 Para Unidades de Negocio: Para crear una entidad en una Unidad de Negocio específica, utilice el punto final Crear una entidad en una unidad de negocio . Proporcione el nombre corto de la unidad de negocio en los parámetros de la ruta junto con otros detalles requeridos en el cuerpo de la solicitud. La API creará la entidad en la Unidad de Negocio especificada. La respuesta incluirá un CWGuid, que deberá utilizarse para cualquier operación futura sobre la entidad, sustituyendo al ID de entidad anterior.

Si no utiliza Unidades de Negocio, utilice el punto final estándar Crear una entidad , como hizo en la V1. Esto creará la entidad en su sitio en la nube, y aquí también se debe utilizar el CWGuid para las operaciones posteriores.

T2 ¿Cómo llamo a los puntos finales de obtención, actualización y eliminación de entidades en V2?

A2 En la API V2, debe utilizar CWGuids en lugar de entityIds para identificar entidades en los puntos finales Get, Updatey Delete . Funciona así:

1. Cuando se crea una entidad o se recupera una lista de entidades (por ejemplo, a través del punto final Search Filtered List), la respuesta incluirá un CWGuid para cada entidad.

2. Para las operaciones posteriores (Get, Update, Delete), debe utilizar el CWGuid proporcionado en la respuesta para hacer referencia a la entidad específica.

Para las empresas de unidades de negocio (BU) , el uso de CWGuids garantiza que la entidad se identifique de forma única en todas las BU, lo que simplifica las operaciones en múltiples unidades de negocio. El sistema utilizará el Guid para realizar la operación solicitada (Obtener, Actualizar o Borrar) en cualquier Unidad de Negocio, garantizando una integración sin fisuras.

Usuarios

P3: ¿Cómo puedo crear usuarios en la V2?

A3 La creación de usuarios en la V2 es similar a la de la V1, con una función añadida para las empresas de unidades de negocio. Funciona así:

Para todas las empresas:

Cree usuarios en V2 utilizando el punto final Crear un usuario , de forma similar a V1. El proceso sigue siendo el mismo para la mayoría de los parámetros.

Para las empresas de la Unidad de Negocio (BU):

Las empresas de BU pueden especificar los nombres abreviados de las unidades de negocio para conceder al usuario acceso a BU específicas. Esto simplifica la gestión del acceso de los usuarios a través de múltiples unidades de negocio. He aquí un ejemplo de código con la lista de BUs:

Respuesta

Tras crear el usuario, la respuesta incluirá un CWGuid, que deberá utilizarse para futuras operaciones (Obtener, Actualizar, Eliminar) en lugar del ID de usuario anterior.

P4: ¿Cómo puedo obtener los datos de un usuario?

A4: En V2, para recuperar los detalles de un usuario, utilice el punto final Obtener detalles del usuario y proporcione el CWGuid del usuario en los parámetros de la ruta. En la V1, se habría utilizado el ID de usuario, pero en la V2, se requiere el Guid en su lugar.

P5: ¿Cómo obtengo la lista de Unidades de Negocio a las que tiene acceso un usuario?

A5: Para obtener la lista de Unidades de Negocio a las que tiene acceso un usuario, utilice el endpoint Obtener Detalles de Usuario y proporcione el CWGuid del usuario. La respuesta incluirá todas las Unidades de Negocio a las que el usuario tiene acceso actualmente.

P6: ¿Cómo asigno o desasigno un usuario del personal a diferentes Unidades de Negocio?

A6: Puede asignar o desasignar un usuario de Unidades de Negocio mientras crea o actualiza el usuario.

Crear un usuario

Proporcione una lista de nombres abreviados de unidades de negocio en la solicitud, especificando a qué unidades de negocio debe tener acceso el usuario.

Update user details

Puede asignar el usuario a nuevas Unidades de Negocio o eliminarlo de las existentes.

Para asignar el usuario a una BU:

Incluya todas las Unidades de Negocio a las que el usuario debería tener acceso, incluyendo aquellas a las que ya tiene acceso.

Para eliminar el acceso a una BU:

Incluya sólo las BU a las que el usuario debe conservar el acceso. Cualquier BU que no esté en la lista será eliminada del acceso del usuario.

Importante:
Si no incluye el campo Unidad de Negocio en la solicitud de actualización, no se realizará ningún cambio en el acceso a la BU del usuario.

Grupos

P7: ¿Cómo se crea un grupo en V2?

A7: En V2, para crear un grupo, utilice el punto final Crear grupo y proporcione los parámetros necesarios en el cuerpo de la solicitud. A diferencia de la V1, en la que recibías un groupId, en la V2 recibirás un CWGuid en la respuesta, que deberás utilizar para cualquier operación futura en ese grupo específico (como Get, Update o Delete).

P8: ¿Cómo puedo añadir usuarios a un grupo?

A8: Para añadir un usuario a un grupo en V2, utilice el punto final "Actualizar la asignación de un usuario a un grupo". En la V2, en lugar de utilizar el ID de grupo y los ID de usuario como en la V1, tendrás que proporcionar el CWGuid del grupo y los CWGuids de los usuarios que quieras añadir en la solicitud.

Añadiendo o eliminando usuarios a grupos y asignando esos grupos a Unidades de Negocio específicas, puede gestionar eficazmente el acceso de los usuarios a las diferentes Unidades de Negocio a través de sus pertenencias a grupos.

P9: ¿Cómo obtengo la lista de Unidades de Negocio a las que tiene acceso un grupo?

A9: Para obtener la lista de Unidades de Negocio a las que un grupo tiene acceso, utilice el endpoint Obtener detalles del grupo y proporcione el CWGuiddel grupo. La respuesta incluirá todas las Unidades de Negocio a las que el grupo tiene acceso actualmente.

Q10 ¿Puedo asignar Grupos a Unidades de Negocio utilizando APIs?

A10 Sí, puede asignar o desasignar grupos de Unidades de Negocio durante la creación del grupo o utilizando el punto final de actualización.

Crear grupo

Proporcione una lista de unidades de negocio en la solicitud, especificando a qué unidades de negocio debe tener acceso el grupo.

Actualizar los datos del grupo

Puede asignar el grupo a nuevas Unidades de Negocio o eliminarlo de las existentes.

• Para asignar el grupo a una BU: Incluya todas las BU a las que el grupo debe tener acceso, incluidas las asignadas previamente.

• Para eliminar el acceso a una BU: Incluya sólo las BU a las que el grupo debe conservar el acceso. Cualquier BU que no esté en la lista será eliminada del acceso del grupo.

Nota: Todos los usuarios del grupo heredarán el acceso a las Unidades de Negocio asignadas al grupo.

Funciones y permisos

P11: ¿Cómo asigno funciones a usuarios y grupos para entidades y compromisos?

A11 En primer lugar, recupere la lista de roles disponibles y sus GUIDs utilizando la API Get Role List.

Asignar funciones a un usuario

Para asignar permiso de acceso a un usuario:

• Proporcione el CWGuid del usuario, las funciones que deben asignarse o eliminarse y los detalles del objeto:

  • Si la función es para todo el sistema (aplicable a todo el sistema), no se requieren detalles adicionales.

  • Si la función es específica de una entidad o compromiso, indique el tipo de objeto (por ejemplo, entidad o compromiso) y las CWGuid de dichos objetos.

Asignar funciones a un grupo

Para asignar una cuenta a un grupo:

• Proporcione el CWGuid del grupo, los roles (GUIDs) a asignar o eliminar y los detalles del objeto:

  • Si el rol es para todo el sistema, no se necesitan parámetros adicionales.

  • Si la función es específica de una entidad o compromiso, indique el tipo de objeto y las CWGuids correspondientes a dichos objetos.

Nota para las empresas de Unidades de Negocio (BU): El uso de CWGuids para la asignación de roles mejora la eficiencia de las empresas BU al permitir una gestión fluida de la asignación de roles entre entidades y compromisos de diferentes Unidades de Negocio.

encargo

P12: ¿Se ha producido algún cambio en las API de compromiso?

R12: Las API Get Engagement no han cambiado de la V1 a la V2 y siguen funcionando como antes. Los parámetros de la solicitud siguen utilizando ID, como en la V1. Sin embargo, si tiene integraciones existentes para compromisos que utilicen la V1, deberá migrar a la V2 para garantizar una compatibilidad continuada, ya que la V1 quedará obsoleta con el tiempo.

Pregunta específica de la BU

P13: ¿Qué es un apodo BU?

A13: Cada Unidad de Negocio (BU) tiene varios atributos: una URL, un Nombre BU, un Nombre para Mostrary un Nombre Corto BU. Mientras que el nombre de la UB y el nombre para mostrar pueden no ser únicos, el nombre corto de la UB es único en todo el mundo, por lo que se utiliza como identificador de las UB.

El BU Shortname se deriva del sufijo URL de la BU y forma parte del dominio caseware. Se puede recuperar fácilmente desde la URL de la BU.

Atributos BU descritos

URL de la BU (no editable)	Nombre	Mostrar etiqueta	Nombre corto
ca.caseware.ca/test-site	Sitio de pruebas	Oficina-NY	sitio de pruebas
us.caseware.com/empresa-1-a-b	Empresa: {1}	Oficina 1 (de A a B)	empresa-1-a-b

Nota importante: Actualmente, no hay ninguna API disponible para recuperar la lista de BUs y sus Shortnames. Puede ver la lista de todas las unidades de negocio accediendo al sitio en la nube y navegando hasta Configuración | Unidades de negocio.

P14: ¿Qué BU debo utilizar para llamar a las API de gestión de otras BU?

R14: Recomendamos utilizar la URL de la Unidad de Negocio (BU) del Administrador para configurar sus integraciones API y gestionar los datos a través de otras BUs. La BU Admin sirve como eje central para gestionar múltiples BUs, en línea con la forma en que sugerimos gestionar las tareas administrativas a través de la UI.

Del mismo modo que aconsejamos a los administradores que gestionen el personal, los grupos y otros objetos desde la Admin BU en la interfaz de usuario, utilizar la Admin BU para sus llamadas a la API garantiza la coherencia y simplifica la administración. Este enfoque le ayuda a mantener un mejor control y visibilidad cuando gestiona datos de varias unidades de negocio.