Flujo de API rastreable

Flujo rastreable autenticado

Utilice esta guia cuando una persona encuentre un trackable, llegue al flujo de acceso secreto, inicie sesion y luego quiera realizar el flujo mas completo de propiedad o de parada respaldada por nota sin perder la opcion mas simple de reporte directo.

Siga la secuencia Documentos de API principales Flujo anónimo Referencia de error

Cuándo usar este flujo

Este es el mejor flujo para las personas que desean propiedad duradera, comentarios editables, conversión de notas, poder de moderación o la capacidad de volver más tarde y administrar lo que publicaron. La persona puede comenzar con un código secreto o un token QR antes de iniciar sesión, pero una vez que se autentica, no necesita seguir reenviando el código de acceso en cada escritura.

Paso 1: resolver el elemento encontrado

La ruta corta de entrada al sitio web es siempre /trackable/{code}. Los clientes API también pueden resolver el token directamente.

POST https://www.locationnotes.com/api/trackables/lookup
Content-Type: application/json

{
  "code": "LN4C8R2Z"
}

{
  "found": true,
  "trackableId": "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31",
  "isPublicCodeMatch": false,
  "usesSecretAccess": true,
  "redirectUrl": "/en-US/trackables/active/f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31"
}

Si usesSecretAccess es verdadero, el navegador ahora tiene una sesión activa respaldada por un secreto para ese rastreable. Esa sesión es independiente del inicio de sesión y existe específicamente para que el usuario pueda seguir avanzando a través del flujo de trabajo rastreable primero.

Paso 2: leer la carga útil de aterrizaje de la sesión activa

GET https://www.locationnotes.com/api/trackables/active/{trackableId}

Esto le indica al cliente si aún se requiere la activación, si el elemento pertenece a un grupo y qué contextos de activación están disponibles después de iniciar sesión.

Paso 3: Inicie sesión y actívelo cuando sea necesario

Si el artículo aún no está activado, inicia sesión y actívalo para un propietario personal o un equipo.

POST https://www.locationnotes.com/api/trackables/{trackableId}/activate
Authorization: Bearer <access token>
Content-Type: application/json

{
  "name": "",
  "description": "",
  "statusMessage": "",
  "useGroupDefaultTitle": true,
  "useGroupDefaultDescription": true,
  "useGroupDefaultStatusMessage": true,
  "teamId": null,
  "externalLinkUrl": "",
  "externalLinkDescription": "",
  "useGroupDefaultExternalLink": true,
  "initialJourneyStopLatitude": 47.6205,
  "initialJourneyStopLongitude": -122.3493
}

Si el elemento viene de un grupo, la activacion tambien es donde se confirma la identidad final a nivel del elemento. Los clientes pueden enviar valores explicitos para name, description y statusMessage, o dejarlos en blanco mientras usan useGroupDefaultTitle, useGroupDefaultDescription y useGroupDefaultStatusMessage para mantener los valores predeterminados actuales del grupo en el elemento activado.

Los clientes pueden incluir opcionalmente <code>initialJourneyStopLatitude</code> mas <code>initialJourneyStopLongitude</code> cuando la activacion tambien deba crear de inmediato la primera ubicacion rastreada.

Paso 4: Elija entre las rutas de registro simples y enriquecidas

Una vez autenticado, el cliente aún puede utilizar la ruta ligera de informe directo o la ruta de notas más completa. Los dos caminos son complementarios, no mutuamente excluyentes.

Ruta sencilla: cree una parada directa del recorrido con POST /api/trackables/{trackableId}/journey-stops.
Ruta completa: cree primero una nota y luego adjunte el trackable a la nota mediante POST /api/public/notes/{noteId}/trackables.
Ruta de conversión solo del sitio web: un usuario que haya iniciado sesión puede convertir su propia parada de ubicación directa en una nota más adelante sin duplicar el segmento de ruta.

Paso 5A: Guardar una parada de viaje directo

POST https://www.locationnotes.com/api/trackables/{trackableId}/journey-stops
Authorization: Bearer <access token>
Content-Type: application/json

{
  "latitude": 41.8819,
  "longitude": -87.6278
}

La parada guardada es una instantánea logística inmutable. Si una nota vinculada se mueve más adelante, el viaje mantiene la coordenada original para que el historial de ruta no cambie silenciosamente.

Paso 5B: Crear una nota y adjuntar el rastreable

POST https://www.locationnotes.com/api/notes/mine
Authorization: Bearer <access token>
Content-Type: application/json

{
  "categoryId": "4de6bb76-f25d-4c73-b8e3-81b9ca3bf08f",
  "title": "North lobby handoff",
  "body": "Visible as a note and as a trackable stop.",
  "latitude": 41.8818,
  "longitude": -87.6231,
  "visibility": "Private"
}

POST https://www.locationnotes.com/api/public/notes/{noteId}/trackables
Authorization: Bearer <access token>
Content-Type: application/json

{
  "trackableSecretCodes": "LN4C8R2Z"
}

Adjuntar el trackable mientras se guarda la nota tambien registra una instantanea de parada del recorrido en ese momento. Esa parada respaldada por nota es la que protege la ruta del trackable si el propio punto del mapa de la nota cambia mas adelante.

El adjunto de la nota tambien concede a ese trackable el alcance de acceso requerido de la nota. La parada conserva el historial del lugar, pero el acceso a la nota sigue regido por la propia visibilidad de la nota y sus reglas de alcance.

Paso 6: Comentar como usuario autenticado

POST https://www.locationnotes.com/api/trackables/{trackableId}/comments
Authorization: Bearer <access token>
Content-Type: application/json

{
  "body": "Picked up and moving again."
}

Los comentarios rastreables registrados solo pueden ser editados por el autor del comentario registrado. Los propietarios y administradores actuales del equipo pueden eliminar comentarios o paradas del viaje, pero aún no pueden reescribir las palabras de otra persona.

Paso 7: Leer la ruta completa y los comentarios

GET https://www.locationnotes.com/api/trackables/{trackableId}/journey
GET https://www.locationnotes.com/api/trackables/{trackableId}/comments

La carga útil del viaje ya está ordenada cronológicamente y precargada para la representación del mapa. Si una parada proviene de una nota privada que el espectador no puede abrir, la API aún puede exponer el punto de ubicación y omitir el contenido de la nota protegida.

Las lecturas del recorrido exponen la parada guardada junto con currentNotesAtCoordinate. Esa coleccion es el modelo de lectura de notas visibles de hoy para la misma coordenada, no una prueba de que la parada sea propietaria permanente de una sola nota.

Notas operativas

Si un usuario que ha iniciado sesión quiere el flujo de mapa superior simple, permítale usarlo. La autenticación debería eliminar la fricción, no forzar una interfaz de usuario diferente.
Las exportaciones de usuarios y equipos ahora incluyen paradas de recorrido de trackables, historial de paradas respaldadas por notas y comentarios de trackables.
Eliminar una cuenta no elimina automáticamente todo el rastreable si otras personas o un equipo aún dependen de su historial.

Referencias relacionadas: Que es un trackable?, flujo rastreable anónimo, y referencia de error rastreable.