Qué acepta contextId

contextId es un parámetro de ruta obligatorio en todas las rutas /v1/twin/{contextId}/... y /v1/reality-plan/{contextId}/.... Es polimórfico: varios tipos de id distintos se resuelven a través de él, lo que explica por qué un UUID bien formado puede devolver 404 de todas formas. Esta página describe qué acepta cada familia de rutas y los errores exactos que verá cuando el id no encaje.

---

Qué identifica contextId

Familia de rutas	contextId acepta
/v1/twin/{contextId}/... (space, assets, POI, zonas, borradores, objetos de negocio, sesiones de embed)	Un id de twin, el id del site al que pertenece el twin, o el id de uno de sus borradores
/v1/reality-plan/{contextId}/... (space, layouts, bundles, model assets)	Un id de RealityPlan Project, o el id de uno de sus layouts

Las dos familias se excluyen mutuamente: una ruta de twin solo resuelve ids con forma de twin, y una ruta de RealityPlan solo resuelve ids con forma de proyecto.

Un id válido del tipo equivocado: 404, no 400

Un id bien formado que pertenece a la otra familia no falla la validación: se resuelve a un contexto real, simplemente no a uno que esta ruta atienda. La API responde 404 Not Found con un mensaje que indica qué atiende realmente la ruta:

{
  "statusCode": 404,
  "message": "This route serves twins. It accepts a twin id, the id of the site it belongs to, or the id of one of its drafts.",
  "error": "Not Found"
}

{
  "statusCode": 404,
  "message": "This route serves design projects. It accepts a design project id or the id of one of its layouts.",
  "error": "Not Found"
}

Algunas rutas añaden una pista que apunta a la ruta homóloga que sí atiende el otro tipo. Por ejemplo, GET /v1/twin/{contextId}/space añade:

This route serves twins. It accepts a twin id, the id of the site it belongs to, or the id of one of its drafts. The composition of a design project or a layout is served by GET /v1/reality-plan/{contextId}/space.

y GET /v1/reality-plan/{contextId}/space añade la imagen especular:

This route serves design projects. It accepts a design project id or the id of one of its layouts. The composition of a twin or a twin draft is served by GET /v1/twin/{contextId}/space.

No todas las rutas tienen una homóloga. Los assets, POI, zonas, borradores y la búsqueda de objetos de negocio existen solo para twins, y los model assets y layouts existen solo para RealityPlan Project; esas rutas no llevan pista, solo el mensaje base de lo que atienden.

Nota

La respuesta para el tipo equivocado es siempre 404, nunca 400: el id en sí es válido, simplemente no es direccionable en esa ruta. Trátelo igual que cualquier otro “no encontrado en esta ruta”.

Un contextId que no es un UUID: 400

Si contextId ni siquiera es un UUID, la API lo rechaza antes de que llegue a ningún controlador de ruta:

{
  "statusCode": 400,
  "message": "Context ID must be a UUID",
  "error": "Bad Request"
}

Esta comprobación ocurre antes de la validación estándar de la solicitud, por lo que es el mensaje que verá para un contextId mal formado, sea cual sea la familia de rutas que esté llamando.

Encontrar el id correcto

Baje desde GET /oauth/api-info a través de GET /v1/nodes/{id}/browse para encontrar un id de twin, site, borrador, proyecto o layout: consulte Finding Your IDs para el recorrido completo. Una vez que tenga un id, esta página le indica qué familias de rutas desbloquea.