API Geotrackable

Створити локацію для керованого трекбла

Цей одноетапний маршрут атомарно створює повну нотатку про локацію та зупинку подорожі трекбла. Трекбл має бути активований, а обліковий запис токена Bearer — бути його особистим власником або активним адміністратором команди-власника. Для командних трекблів нотатка автоматично створюється в тій самій команді.

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

Повторювати POST після тайм-ауту з невідомим результатом небезпечно. Перш ніж повторювати запит, оновіть подорож трекбла та свої локації, щоб клієнт не створив дублікати нотатки й зупинки.

Прив’язати локацію за наявності секретного доступу або доступу активного сеансу

Людина, яка знайшла трекбл, але не керує ним, має виконати два виклики: спочатку створити звичайну локацію, прочитати noteId з відповіді, а потім прив’язати один активований трекбл за його секретним кодом. selectedActiveTrackableIds призначено лише для трекблів, активних у тому самому браузерному сеансі, що підтримується файлами cookie.

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

Попри назву властивості у множині, trackableSecretCodes приймає один код на запит. Нотатка повинна мати координати, а трекбл має бути вже активований. Щоб прив’язати інший трекбл, повторіть запит на прив’язування.

Для спрощеної точки подорожі з координатами, але без заголовка, body, категорії чи повної нотатки про локацію, використовуйте POST /api/trackables/{trackableId}/journey-stops.

Коли запитаний код уже зайнятий

Конфлікт користувацького коду повертає HTTP 409 із code trackable_secret_code_taken. Цей запит не створив трекер. Не повторюйте запит із тим самим значенням: пропустіть secretCode, щоб отримати згенерований код, або виберіть інший дозволений користувацький код.

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

Дії для зарезервованого префікса

• GT зарезервовано для кодів, які видає система Geotrackable. Пропустіть secretCode і дозвольте цьому хосту видати код.
• LN належить трекованим об’єктам LocationNotes; опрацюйте предмет на сайті його походження, а не приймайте його код тут.
• TB належить трекованим об’єктам Geocaching.com; скористайтеся процесом відстеження на сайті походження.
• GK належить трекованим об’єктам GeoKrety.org; скористайтеся процесом відстеження на сайті походження.
• GC є ідентифікатором геокеша Geocaching.com, а не секретним кодом Geotrackable.

Зарезервовані або недійсні користувацькі значення повертають відповідь про проблему з action і посиланням на документацію. Безпечний запасний варіант — завжди вилучити secretCode із запиту на створення.

Записати зупинку подорожі

Пряма зупинка подорожі - це легке оновлення маршруту, коли повна нотатка локації не потрібна.

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

Коментувати трекер

Виклики від користувачів, які ввійшли, можуть додавати коментарі зі своєю ідентичністю Bearer. Анонімні виклики також можуть коментувати активований трекер, якщо клієнт має активний сеанс, підтверджений секретним кодом, або надсилає accessCode саме цього предмета.

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": ""
  }'

Помилки перевірки містять назви полів

Помилки перевірки HTTP 400 додають об’єкт errors. Кожен ключ — це властивість JSON або частина запиту, яку треба виправити, а кожне значення є масивом, оскільки одне поле може порушувати кілька правил.

{
  "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 і тип вмісту

Недійсний JSON є помилкою перевірки запиту. Збережіть requestId, виправте синтаксис і знову надішліть тіло з Content-Type: application/json. Кінцеві точки завантаження файлів натомість вимагають multipart/form-data та частину files або file з назвою поля, визначеною для конкретного маршруту.

Навіть синтаксично правильне тіло запиту може порушувати бізнес-правило. Для проблем окремих полів використовуйте errors, для програмної логіки — code, для контексту — detail, а для наступного кроку — action. Не показуйте користувачам необроблені винятки сервера чи трасування стека.

Повторюйте записи обдумано

GET-запити зазвичай безпечно повторювати. POST може створити дані, навіть якщо на клієнті сплив час очікування до отримання відповіді. Перш ніж знову створювати трекер, оновіть GET /api/trackables/mine і звірте результат, щоб через мережевий тайм-аут не створити дублікати фізичних предметів.

Для 429 або тимчасової 500 використовуйте обмежену експоненційну затримку з випадковим розкидом. Зупиніться, якщо action вказує, що треба змінити сам запит. Ніколи не перетворюйте 400, 403, 404, 405, 409, 413 або 415 на цикл автоматичних повторів.

Зберігайте корисність діагностики без витоку облікових даних

Ніколи не записуйте до журналів заголовки Authorization, токени Bearer чи оновлення, паролі, файли cookie, secretCode, accessCode, QR-дані, приватні URL-адреси сканування або необроблені вхідні шляхи /trackable/{code}. Приховуйте їх перед передаванням у телеметрію, звіти про збої, знімки екрана й додатки до звернень у підтримку.

До безпечних діагностичних полів належать requestId, ticketNumber, HTTP status, стабільний code, метод, шаблон маршруту, версія клієнта й позначка часу. Не копіюйте повне тіло запиту, якщо воно може містити текст про місце, точні координати, контактні дані або облікові дані трекера.

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