Autodesk pushpins: el nombre informal detrás de varias APIs
La incidencia señalaba una colisión junto al núcleo. En el visor donde se creó, el marcador aparecía exactamente sobre la bandeja. Al abrirla desde otra aplicación, el punto flotaba varios metros fuera del edificio. El comentario y la captura seguían siendo correctos; el supuesto «pushpin» había perdido modelo, versión, sistema de coordenadas y cámara por el camino.
Autodesk pushpins es un nombre informal utilizado para hablar de marcadores visuales asociados a incidencias o documentos en distintos contextos Autodesk. No describe necesariamente un objeto único ni una API universal. Antes de implementar nada, conviene identificar qué producto, recurso y flujo estás utilizando: marcador de visor, incidencia vinculada a un modelo, referencia sobre un documento o extensión propia.
Tabla de contenidos
El equipo empezó preguntando qué quería conservar
La necesidad no era dibujar una chincheta roja. Era permitir que otra persona abriese una incidencia y recuperase el mismo contexto: proyecto, modelo, versión, zona, vista y objetos implicados.
El marcador aportaba una posición visual. La incidencia necesitaba además título, descripción, estado, responsable y trazabilidad. El documento o modelo aportaba el espacio donde esa posición tenía sentido.
Separar estos conceptos evitó guardar toda la información dentro de un objeto gráfico. La chincheta podía cambiar de estilo sin alterar el contrato de la incidencia.
El nombre informal escondía varios recursos
En un visor, un marcador puede ser una extensión dibujada sobre la escena. En un sistema de issues, la referencia puede vivir dentro de un recurso de incidencia. Sobre planos 2D, la posición utiliza otra relación con el documento. Los endpoints y estructuras dependen del producto y la versión.
El equipo no buscó una API llamada «Pushpins» y asumió que cubría todo. Revisó documentación oficial vigente para el flujo concreto: qué recurso se crea, qué campos acepta y cómo se relaciona con el modelo.
Esta precaución importaba porque dos ejemplos visualmente iguales podían tener ciclos de vida distintos. Uno desaparecía al recargar; otro se compartía y conservaba historia.
La coordenada sola no tuvo significado suficiente
Un vector x, y, z necesita un sistema de referencia. Puede estar en coordenadas del modelo, del visor transformado o de otro espacio. Además, el modelo puede contener transformaciones y federaciones.
El equipo guardó el contexto definido por el contrato soportado: referencia de modelo o vista, versión y datos necesarios para reconstruir la posición. No mezcló coordenadas de pantalla con coordenadas tridimensionales.
Las pruebas utilizaron modelos con origen desplazado, rotación y varias disciplinas. El marcador debía aparecer donde se creó. Probar únicamente un cubo en el origen habría sido amable con el código y poco con el proyecto.
La cámara explicó lo que el punto no podía
Un punto sobre una tubería no muestra qué elemento tapa la vista ni desde qué dirección se entendía el conflicto. La cámara, objetivo, proyección y sección podían ser parte del contexto.
El sistema conservaba una vista reproducible cuando la API y el flujo lo permitían. Si una función no era portable, se documentaba y se añadía una captura como ayuda, no como sustituto de datos.
La persona podía recuperar el encuadre y después navegar. El objetivo no era congelarla dentro de una postal, sino reducir el tiempo hasta comprender la incidencia.
Los objetos seleccionados aportaron identidad
La incidencia incluía referencias a los elementos implicados cuando eran estables en ese contexto. Los IDs internos de una traducción o visor podían cambiar entre versiones. El equipo probó su persistencia y añadió claves de negocio o IFC cuando existían.
Una nueva versión podía eliminar, dividir o recrear objetos. El sistema no trasladaba la selección como si nada. Marcaba referencias no resueltas y permitía volver a asociar.
La posición seguía ayudando, pero no justificaba afirmar que la misma entidad existía. Geometría parecida e identidad no son sinónimos, aunque a simple vista se lleven bien.
La versión quedó unida a la incidencia
El marcador se creó sobre una versión concreta. Al abrirlo, el usuario debía saber si veía esa versión o la más reciente. Ambas opciones podían ser útiles, pero no equivalentes.
Para investigar el origen, se recuperaba la versión original. Para verificar la solución, se abría la nueva y se comparaba. El estado de cierre registraba sobre qué versión se había comprobado.
El sistema no actualizaba silenciosamente la referencia al último modelo. Hacerlo habría convertido una incidencia histórica en un viaje temporal sin billete de vuelta.
Crear una incidencia manual y crearla por API exigieron el mismo contrato
La interfaz guiaba al usuario para seleccionar contexto, escribir una descripción útil y confirmar responsable. La API validaba los mismos campos y permisos. Automatizar la creación no permitía saltarse calidad.
Un proceso automático podía proponer incidencias a partir de reglas o interferencias. Antes de publicarlas, agrupaba duplicados y asignaba severidad según criterios. Las personas revisaban casos ambiguos.
La aplicación evitaba crear cientos de marcadores idénticos. El volumen visual no representa rigor; a veces solo demuestra que un bucle encontró entusiasmo.
Los duplicados se detectaron por causa y contexto
Dos personas podían señalar el mismo problema desde puntos ligeramente distintos. Comparar coordenadas exactas no bastaba. El sistema consideraba modelo, versión, objetos, regla y proximidad.
La agrupación proponía coincidencias; coordinación confirmaba. Al fusionar, se conservaban comentarios y autores. Una incidencia cerrada podía reaparecer si la condición volvía en otra versión.
La clave idempotente protegía creaciones automáticas. Reprocesar la misma detección no duplicaba el issue. La visualización recibía el estado existente.
El visor y el sistema de incidencias tuvieron responsabilidades diferentes
| Componente | Responsabilidad | Límite |
|---|---|---|
| Marcador visual | Representar una ubicación y estado | No conserva por sí solo el flujo |
| Visor | Mostrar modelo, cámara y selección | Sus IDs pueden depender de versión |
| Incidencia | Guardar descripción, estado, responsable e historia | Necesita contexto para localizarse |
| API | Leer o escribir recursos autorizados | Depende del producto, scopes y contrato vigente |
| Aplicación propia | Unir permisos, negocio y experiencia | Debe mantener sincronización y errores |
El diseño podía cambiar de tecnología conservando estas fronteras. El término pushpin describía la experiencia; la arquitectura describía quién respondía por cada dato.
Los permisos llegaron antes que el botón de crear
Un usuario podía ver el modelo y no tener permiso para crear o asignar incidencias. La aplicación comprobaba acceso al proyecto, recurso y acción. Los tokens usaban scopes mínimos.
El frontend no guardaba secretos. Las operaciones sensibles pasaban por backend cuando correspondía. Los errores distinguían autenticación, autorización y recurso inexistente.
Los colaboradores externos veían únicamente incidencias de su alcance. Compartir una coordenada no abría acceso al modelo completo.
Los estados se sincronizaron sin fingir inmediatez perfecta
Una incidencia podía cambiar en la plataforma o en la aplicación. Los eventos avisaban y la API confirmaba. Los duplicados se deduplicaban; una reconciliación periódica reparaba huecos.
Los conflictos tenían política. Si dos usuarios editaban descripción y responsable, el sistema no sobrescribía sin avisar. Las versiones o marcas de actualización ayudaban a detectar concurrencia.
La interfaz mostraba estado pendiente cuando una escritura aún no estaba confirmada. Un marcador verde no aparecía antes de saber que el cierre se había guardado.
Los fallos se probaron en 2D, 3D y federación
El equipo creó incidencias en planos y modelos, con cámaras ortográficas y en perspectiva, secciones y disciplinas transformadas. Después abrió el contexto en diferentes navegadores y versiones.
También probó objetos desaparecidos, traducciones nuevas, permisos retirados y payloads incompletos. Un fallo debía degradar con información útil: abrir la versión y mostrar captura, por ejemplo, aunque la selección no se resolviese.
Las pruebas verificaban la API real en un entorno aislado. Los contratos de ejemplo no demostraban transformaciones ni ciclo de permisos.
La documentación oficial se consultó con fecha
Los nombres de recursos, endpoints y campos podían cambiar o pertenecer a productos concretos. El artículo y la implementación no generalizaban desde una muestra antigua.
El equipo registraba versión de API o SDK, dependencias y fecha de verificación. Las actualizaciones activaban pruebas de creación y lectura.
Los términos informales se mantenían en la interfaz si ayudaban al usuario, pero el código utilizaba nombres del contrato. Una chincheta simpática no debía decidir el modelo de dominio.
Cuándo un marcador no es la herramienta adecuada
Una incidencia global del proyecto quizá no tiene una posición única. Una decisión documental puede vincularse a un plano o paquete, no a un punto 3D. Forzar un marcador inventaría precisión.
Para listas grandes de requisitos, una vista tabular puede ser mejor que llenar el modelo de iconos. El visor aporta contexto cuando la ubicación ayuda a decidir.
Si la identidad entre versiones no es fiable, conviene mostrar advertencia y conservar la original. No se debe prometer seguimiento automático que el flujo no puede demostrar.
El pushpin útil dejó de ser solo un punto
La siguiente incidencia se abrió en el lugar correcto porque conservaba modelo, versión, espacio, cámara y referencias. Cuando una selección no sobrevivió a otra versión, el sistema lo explicó y permitió verificar de nuevo.
Para trabajar con Autodesk pushpins, empieza identificando el recurso real y el producto. Separa marcador, visor e incidencia; define coordenadas y versiones; y prueba el recorrido completo con la documentación vigente.
Si una chincheta aparece en otro edificio, no discutas todavía con el color del icono. Pregunta primero en qué espacio vive la coordenada. Es menos vistoso, pero suele acercarte bastante más a la bandeja.
Respuestas