O que contextId aceita

contextId é um parâmetro de caminho obrigatório em todas as rotas /v1/twin/{contextId}/... e /v1/reality-plan/{contextId}/.... Ele é polimórfico: vários tipos diferentes de id são resolvidos por meio dele, o que explica por que um UUID bem formado ainda pode retornar 404. Esta página descreve o que cada família de rotas aceita e os erros exatos que você verá quando o id não corresponder.

---

O que contextId identifica

Família de rotas	contextId aceita
/v1/twin/{contextId}/... (space, assets, POIs, zonas, rascunhos, objetos de negócio, sessões de embed)	Um id de twin, o id do site ao qual o twin pertence, ou o id de um de seus rascunhos
/v1/reality-plan/{contextId}/... (space, layouts, bundles, model assets)	Um id de RealityPlan Project, ou o id de um de seus layouts

As duas famílias são mutuamente exclusivas: uma rota de twin só resolve ids no formato de twin, e uma rota de RealityPlan só resolve ids no formato de projeto.

Um id válido do tipo errado: 404, não 400

Um id bem formado que pertence à outra família não falha na validação: ele é resolvido para um contexto real, apenas não um que essa rota atenda. A API responde 404 Not Found com uma mensagem informando o que a rota realmente atende:

{
  "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"
}

Algumas rotas anexam uma dica apontando para a rota equivalente que atende o outro tipo. Por exemplo, GET /v1/twin/{contextId}/space anexa:

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.

e GET /v1/reality-plan/{contextId}/space anexa o espelho:

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.

Nem toda rota tem uma equivalente. Assets, POIs, zonas, rascunhos e a busca de objetos de negócio existem apenas para twins, e model assets e layouts existem apenas para RealityPlan Project; essas rotas não trazem dica, apenas a mensagem base do que atendem.

Nota

A resposta para o tipo errado é sempre 404, nunca 400: o id em si é válido, apenas não é endereçável nessa rota. Trate-a como qualquer outro “não encontrado nesta rota”.

Um contextId que não é um UUID: 400

Se contextId nem sequer for um UUID, a API o rejeita antes mesmo de chegar a um manipulador de rota:

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

Essa verificação ocorre antes da validação padrão da requisição, portanto é a mensagem que você verá para um contextId malformado, independentemente da família de rotas chamada.

Encontrando o id certo

Desça de GET /oauth/api-info por meio de GET /v1/nodes/{id}/browse para encontrar um id de twin, site, rascunho, projeto ou layout: veja Finding Your IDs para o passo a passo completo. Assim que tiver um id, esta página informa quais famílias de rotas ele desbloqueia.