API de Geotrackable

Crear una ubicación bajo un rastreable administrado

Esta ruta de un solo paso crea de forma atómica la nota de ubicación completa y su parada del recorrido del rastreable. El rastreable debe estar activado, y la cuenta del token bearer debe ser su propietario personal o un administrador activo del equipo propietario. Los rastreables de equipo crean automáticamente la nota en ese mismo equipo.

curl -X POST "https://Geotrackable.com/api/trackables/<TRACKABLE_ID>/notes" \
  -H "Authorization: Bearer <access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Dropped off at spot #1",
    "body": "Left near the park.",
    "contentLanguage": "en-US",
    "latitude": 41.8827,
    "longitude": -87.6233,
    "visibility": "Private",
    "commentPolicy": "Disabled"
  }'

{
  "trackableId": "13a2c0b1-582f-4a7b-92aa-16922f7bdb63",
  "journeyStopId": "3a223d33-5442-4cf7-84a1-3d937a253f30",
  "note": {
    "noteId": "26f84cdd-02e7-4c18-a153-f2754418f435",
    "title": "Dropped off at spot #1",
    "body": "Left near the park.",
    "latitude": 41.8827,
    "longitude": -87.6233
  },
  "message": "Location note created and added to the trackable journey."
}

No es seguro repetir un POST después de un tiempo de espera de resultado desconocido. Antes de reintentarlo, actualice primero el recorrido del rastreable y sus ubicaciones para que el cliente no cree una nota y una parada duplicadas.

Asociar una ubicación cuando se tiene acceso secreto o de sesión activa

Una persona que encontró el objeto pero no administra el rastreable debe usar dos llamadas: primero crear la ubicación normal, leer noteId de esa respuesta y luego asociar un rastreable activado mediante su código secreto. selectedActiveTrackableIds solo se usa para rastreables activos en la misma sesión del navegador respaldada por cookies.

curl -X POST "https://Geotrackable.com/api/public/notes/<NOTE_ID>/trackables" \
  -H "Authorization: Bearer <access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "trackableSecretCodes": "<TRACKABLE_SECRET_CODE>"
  }'

A pesar del nombre plural de la propiedad, trackableSecretCodes acepta un código por solicitud. La nota debe tener coordenadas y el rastreable ya debe estar activado. Repita la solicitud de asociación para otro rastreable.

Para un punto ligero del recorrido con coordenadas, pero sin title, body, category ni una nota de ubicación completa, use en su lugar POST /api/trackables/{trackableId}/journey-stops.

Cuando el código solicitado ya está en uso

Una colisión de código personalizado devuelve HTTP 409 con el código trackable_secret_code_taken. La solicitud no ha creado ningún rastreable. No siga reintentando el mismo valor: omita secretCode para recibir un código generado o elija otro código personalizado permitido.

{
  "type": "/en-US/api-docs#errors-and-problem-details",
  "title": "Requested secret code is unavailable.",
  "status": 409,
  "detail": "That secret code is already in use by another Geotrackable identifier. Supplying a secret code is optional: omit it to receive a unique system-generated code, or choose a different code.",
  "instance": "/api/trackables",
  "code": "trackable_secret_code_taken",
  "field": "secretCode",
  "action": "Omit secretCode to receive a unique system-generated code, or submit a different allowed secretCode.",
  "requestId": "0HN7EXAMPLE:00000001",
  "documentation": "/en-US/api-docs#errors-and-problem-details"
}

Recuperación ante prefijos reservados

• GT está reservado para códigos emitidos por el sistema de Geotrackable. Omita secretCode y permita que este host emita uno.
• LN pertenece a rastreables de LocationNotes; resuelva el elemento en su sitio de origen en lugar de adoptar aquí su código.
• TB pertenece a rastreables de Geocaching.com; use el flujo de seguimiento del sitio de origen.
• GK pertenece a rastreables de GeoKrety.org; use el flujo de seguimiento del sitio de origen.
• GC es un identificador de geocaché de Geocaching.com, no un código secreto de Geotrackable.

Los valores personalizados reservados o no válidos devuelven una respuesta de problema con una action y un enlace a la documentación. La alternativa segura siempre es quitar secretCode de la solicitud de creación.

Registrar una parada del recorrido

Una parada directa del recorrido es la actualización ligera de ruta cuando no se necesita una nota de ubicación completa.

curl -X POST "https://Geotrackable.com/api/trackables/13a2c0b1-582f-4a7b-92aa-16922f7bdb63/journey-stops" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 41.8818,
    "longitude": -87.6231,
    "accessCode": "GT-SECRET-OR-SCAN-PAYLOAD"
  }'

Comentar en un rastreable

Los solicitantes con sesión iniciada pueden comentar con su identidad bearer. Los solicitantes anónimos también pueden comentar en un rastreable activado cuando este cliente tiene la sesión activa respaldada por el secreto o envía el accessCode de ese elemento exacto.

curl -X POST "https://Geotrackable.com/api/trackables/13a2c0b1-582f-4a7b-92aa-16922f7bdb63/comments" \
  -b geotrackable.cookies \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Found near the overlook and moved west.",
    "accessCode": ""
  }'

Los errores de validación incluyen nombres de campo

Los errores de validación HTTP 400 agregan un objeto errors. Cada clave es la propiedad JSON o el área de la solicitud que necesita corrección, y cada valor es una matriz porque un campo puede infringir más de una regla.

{
  "type": "/en-US/api-docs#errors-and-problem-details",
  "title": "Request validation failed.",
  "status": 400,
  "detail": "One or more request fields are invalid. Correct every field listed in errors and submit the request again.",
  "instance": "/api/trackables",
  "code": "validation_failed",
  "action": "Correct every field listed in errors and submit the request again.",
  "requestId": "0HN7EXAMPLE:00000003",
  "documentation": "/en-US/api-docs#errors-and-problem-details",
  "errors": {
    "name": ["Name cannot be longer than 160 characters."],
    "secretCode": ["Secret code cannot be longer than 32 characters."]
  }
}

JSON mal formado y tipo de contenido

Un JSON no válido es un error de validación de la solicitud. Conserve requestId, corrija la sintaxis y vuelva a enviar el cuerpo con Content-Type: application/json. Los endpoints de carga de archivos requieren en cambio multipart/form-data y una parte files o file con el nombre de campo específico de la ruta.

Un cuerpo sintácticamente válido aún puede incumplir una regla de negocio. Use errors para problemas por campo, code para la lógica del programa, detail para el contexto y action para el siguiente paso. No muestre a los usuarios una excepción sin procesar ni un seguimiento de pila del servidor.

Reintente las escrituras de forma deliberada

Normalmente es seguro reintentar las solicitudes GET. Una solicitud POST puede crear datos incluso si el cliente agota el tiempo de espera antes de recibir la respuesta. Antes de repetir la creación de un rastreable, actualice GET /api/trackables/mine y concilie el resultado para que un tiempo de espera de red no cree elementos físicos duplicados.

Para un 429 o un 500 transitorio, use espera exponencial limitada con variación aleatoria. Deténgase cuando action indique que debe cambiar la propia solicitud. Nunca convierta un 400, 403, 404, 405, 409, 413 o 415 en un bucle de reintentos automáticos.

Mantenga los diagnósticos útiles sin filtrar credenciales

Nunca registre encabezados Authorization, tokens bearer o de actualización, contraseñas, cookies, secretCode, accessCode, cargas QR, URL privadas de escaneo ni rutas de entrada /trackable/{code} sin redactar. Ocúltelos antes de incluirlos en telemetría, informes de fallos, capturas de pantalla y archivos adjuntos para soporte.

Los campos de diagnóstico seguros incluyen requestId, ticketNumber, el estado HTTP, el code estable, el método, la plantilla de ruta, la versión del cliente y una marca de tiempo. No copie el cuerpo completo de la solicitud cuando pueda contener texto de ubicación, coordenadas exactas, datos de contacto o una credencial de rastreable.

POST /api/trackables -> 409
code=trackable_secret_code_taken
requestId=0HN7EXAMPLE:00000001
secretCode=[REDACTED]