Crear y actualizar incidencias de Autodesk con Issues API
Hasta esta entrega, Issues Manager solo leía datos. Al añadir un botón que crea incidencias, la prueba deja de ser inocua: lo que confirmes queda en un proyecto de Autodesk. Para comprobar este paso he acotado el ensayo a una única incidencia en Snowdon Towers, con revisión antes de enviarla y cierre al terminar. En esta cuarta entrega de la serie sobre las APIs de Autodesk Forma vamos a recorrer esa creación y su actualización desde nuestra aplicación. Es la misma lógica que más adelante utilizaremos al importar un Excel y, al final de la serie, desde un agente de IA mediante un servidor MCP.
El permiso de escritura se concede de nuevo
Partimos de la versión que ya encuentra proyectos y consulta miembros y capacidades de Issues. Se mantienen la aplicación APS, el Client ID y la dirección de retorno del login. El cambio de configuración es añadir data:write a los permisos que solicita el inicio de sesión; los de lectura siguen haciendo falta para consultar y comprobar el resultado.
Si tenías una sesión de la entrega anterior, desconecta Autodesk y vuelve a entrar. Revisa el consentimiento nuevo antes de aceptarlo. Renovar un token conserva los permisos ya concedidos: no incorpora por su cuenta la escritura. La referencia de creación de Autodesk exige ese permiso y un contexto de usuario.
El consentimiento tampoco convierte la cuenta en administradora. En nuestra prueba, la cuenta volvió a tener permisos de administrador del proyecto; la aplicación consultó sus capacidades antes de preparar la creación. Una cuenta con menos permisos puede recibir una respuesta distinta, aunque haya aceptado el mismo consentimiento.
Primero consulta qué tipos y qué incidencias hay
Después de seleccionar hub y proyecto aparece el bloque de incidencias. La lista devuelve una página de resultados y permite avanzar o retroceder. Si la consulta termina correctamente sin elementos, verás una lista vacía; si Autodesk deniega el acceso, verás el error. Son situaciones distintas y necesitan respuestas distintas.
El formulario consulta también el catálogo del proyecto. Aquí Autodesk utiliza dos nombres que conviene situar: lo que ves como categoría corresponde a type en la API, y el tipo concreto corresponde a subtype. Por eso el selector muestra pares como «General / General» o «Coordination / Clash». Al crear enviaremos el identificador del subtipo, no el texto del desplegable.
La consulta GET issue-types?include=subtypes recorre el catálogo y conserva categorías y subtipos activos. Un detalle útil si revisas la respuesta: el campo isReadOnly del catálogo no acredita el permiso para crear incidencias. Esa comprobación sigue viniendo de las capacidades del usuario. La referencia de tipos explica también esta diferencia de nombres.
Del formulario a los datos que recibe Autodesk
Para reproducir el recorrido, abre la versión de código de este artículo, arranca la aplicación siguiendo su README y selecciona un proyecto de prueba. Rellena título y descripción, elige un tipo activo y un estado disponible. El título admite hasta 100 caracteres y la descripción hasta 1.000. El responsable es opcional; si eliges uno, el servidor lo resuelve por su identidad Autodesk y comprueba la asignación.
El formulario no manda a Autodesk todo lo que aparece en pantalla. FastAPI prepara un conjunto pequeño de campos: title, description, issueSubtypeId y status; cuando hay responsable añade assignedTo y assignedToType. A ese contenido de una petición lo llamamos payload. El nombre te resultará menos abstracto al verlo en la revisión: son exactamente los datos que vas a enviar.
El método PlanInput.payload, en apps/api/app/issues/schemas.py, traduce los campos del formulario al cuerpo que espera Autodesk. En la versión de este artículo construye así el contenido: omite los valores ausentes y añade subtipo y responsable solo al crear. El fragmento pertenece a la clase PlanInput del repositorio.
# Método de PlanInput en la versión de este artículo.
def payload(self) -> dict[str, object]:
result: dict[str, object] = {
k: v
for k, v in (
("title", self.title),
("description", self.description),
("status", self.status),
)
if v is not None
}
if self.operation == "create":
result["issueSubtypeId"] = self.subtype_id
if self.assignee_id:
result.update(assignedTo=self.assignee_id, assignedToType="user")
return result
Construir ese cuerpo todavía no lo envía. IssueService.validate comprueba la creación y el subtipo o, si actualizamos, contrasta los campos y el nuevo estado con permittedAttributes y permittedStatuses de esa incidencia. Después de revisar y confirmar el plan, el servidor realiza el POST de creación o el PATCH de actualización con la conexión Autodesk.
Preparar la revisión todavía no crea la incidencia
Pulsa Preparar revisión · no envía a Autodesk. La aplicación muestra proyecto, operación, tipo, responsable y campos que enviará. Antes de confirmar, comprueba especialmente el proyecto y la identidad de la persona: un nombre parecido o una pestaña abierta de ayer pueden despistarte más que un error de programación.
La revisión se guarda durante diez minutos, vinculada a tu sesión y con su contenido cifrado. Para enviarla hay que marcar la aprobación y pulsar un segundo botón. Si cambias un campo del formulario, desaparece la revisión visible y tendrás que preparar otra. El servidor ejecuta lo guardado, no una versión nueva del formulario que haya llegado junto a la confirmación.
Al confirmar se vuelven a consultar el acceso al proyecto, las capacidades y, cuando procede, el responsable. Así, una revisión que fue válida hace unos minutos puede detenerse si los permisos han cambiado. Esta separación añade un paso, pero permite saber qué se estaba autorizando.
La revisión muestra el proyecto y los campos exactos antes de la única creación autorizada.
Comprueba la creación con una segunda consulta
En esta prueba se creó «Prueba Código BIM · E04», de tipo General / General, con estado open y asignada a Sergio Mirallas. La descripción deja claro que es una incidencia sintética, sin un defecto real del proyecto detrás. Autodesk la devolvió como #1 y le asignó su identificador.
Después de recibir la respuesta de creación, el servidor volvió a consultar ese ID y comparó los campos enviados con los observados. La interfaz mostró «Envío aceptado y relectura comprobada». También se contrastó la incidencia en la herramienta Issues de Autodesk. Esta segunda lectura distingue una respuesta aceptada de los datos que encontramos después.
El número #1 sirve para reconocerla en el proyecto; el ID es la referencia que usaremos al actualizar. No hace falta copiar ninguno a mano para editar desde la lista. La aplicación conserva la referencia de esa incidencia y consulta su detalle al abrirla.
Actualizar exige mirar los permisos de esa incidencia
Abre la incidencia desde la lista. El formulario de edición permite cambiar título, descripción y estado; mantiene los demás datos. Esta entrega deja la asignación en el formulario de creación, para que el recorrido de actualización sea pequeño y se pueda comprobar con claridad.
Los campos editables y los estados posibles se toman del detalle de la incidencia: permittedAttributes y permittedStatuses. Haber podido crear una no concede permiso para editar cualquier otra. La referencia de actualización pide consultar esas listas para el caso concreto.
Al preparar el cambio, la revisión compara valores anteriores y nuevos. En la confirmación se relee la incidencia; si los datos o sus permisos ya difieren de los revisados, el envío se detiene y hay que revisar de nuevo. Esta comprobación detecta una revisión obsoleta, aunque no bloquea las ediciones simultáneas que otra persona pueda hacer dentro de Autodesk.
La prueba actualizó el título a «Prueba Código BIM · E04 · verificada», cambió la descripción y pasó de open a closed. La relectura mantuvo el mismo ID y Autodesk mostró Closed. Cerrar deja la incidencia en el proyecto: no la elimina. Tampoco hemos activado su publicación desde esta aplicación.
La misma incidencia #1 aparece cerrada en Autodesk, con el título, descripción y responsable comprobados.
Si se pierde la respuesta, no vuelvas a pulsar a ciegas
El caso que más me interesa controlar aquí es un envío cuyo resultado no conocemos: puede que Autodesk haya recibido la petición aunque nuestra aplicación no haya podido leer la respuesta. Por eso ese fallo queda como incierto y no provoca una segunda creación automática.
La interfaz distingue un rechazo explícito, un envío aceptado y un resultado incierto. Si se agota el tiempo o la respuesta es ambigua, ese plan no se repite automáticamente. Utiliza Consultar resultado guardado y comprueba el proyecto en Autodesk antes de preparar otra operación. Dos preparaciones distintas no comparten una garantía absoluta contra duplicados.
La creación, actualización y relectura se han observado con Autodesk real. Los casos de permisos retirados, datos inválidos, timeout y dos confirmaciones simultáneas se han comprobado mediante pruebas automatizadas con respuestas simuladas. Ayudan a revisar el control de errores sin provocar esos fallos sobre un proyecto real.
Llévate el código de la serie
Suscríbete a la newsletter de Código BIM y te enviaré el repositorio con las instrucciones para elegir la versión de cada artículo. Un mismo recurso para seguir toda la serie, desde el login con Autodesk hasta el futuro servidor MCP.
El correo incluye el acceso a todas las versiones de la serie. Podrás darte de baja de la newsletter cuando quieras.
Siguiente paso: llevar este recorrido a un Excel
Con la incidencia #1 he comprobado el recorrido que quería conservar: preparar, revisar, enviar y volver a leer el resultado. El formulario es una forma de introducir los datos. En el siguiente artículo utilizaremos una hoja de cálculo para preparar varias filas con las mismas reglas.
La siguiente entrega preparará esa importación por filas sobre el mismo servicio de incidencias. La validación y la escritura seguirán en FastAPI; el Excel aportará datos, sin saltarse la revisión. Antes de llegar al agente de IA, interesa que una operación tenga un resultado que podamos explicar y recuperar.
Respuestas