API ng Geotrackable

Gumawa ng lokasyon sa ilalim ng pinamamahalaang trackable

Atomikong ginagawa ng one-step route na ito ang buong location note at ang trackable journey stop nito. Kailangang naka-activate ang trackable, at ang bearer-token account ay dapat na personal na may-ari nito o aktibong admin ng team na nagmamay-ari. Awtomatikong ginagawa ng mga team trackable ang note sa team ding iyon.

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

Hindi ligtas ulitin ang isang POST pagkatapos ng timeout na hindi alam ang resulta. I-refresh muna ang trackable journey at ang iyong mga lokasyon bago subukang muli upang hindi makagawa ang client ng dobleng note at stop.

Iugnay ang lokasyon kapag may secret o active-session access

Ang nakahanap na hindi namamahala sa trackable ay dapat gumamit ng dalawang call: gawin muna ang karaniwang lokasyon, basahin ang noteId mula sa tugon, at pagkatapos ay ikabit ang isang na-activate na trackable gamit ang secret code nito. Ang selectedActiveTrackableIds ay para lamang sa mga trackable na aktibo sa parehong cookie-backed browser session.

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

Sa kabila ng plural na pangalan ng property, isang code lamang bawat request ang tinatanggap ng trackableSecretCodes. Kailangang may coordinates ang note at naka-activate na ang trackable. Ulitin ang association request para sa isa pang trackable.

Para sa magaan na journey point na may coordinates ngunit walang title, body, category, o buong location note, gamitin sa halip ang POST /api/trackables/{trackableId}/journey-stops.

Kapag ginagamit na ang hiniling na code

Kapag ginagamit na ang custom code, nagbabalik ang server ng HTTP 409 na may code na trackable_secret_code_taken. Walang nalikhang trackable ang request. Huwag paulit-ulit na subukan ang parehong value: alisin ang secretCode para makatanggap ng generated code, o pumili ng ibang pinapayagang custom code.

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

Pag-recover mula sa reserved prefix

• GT ay nakalaan para sa mga code na inilalabas ng Geotrackable system. Alisin ang secretCode at hayaan ang host na ito na magbigay ng code.
• LN ay kabilang sa mga trackable ng LocationNotes; ayusin ang item sa pinagmulang site nito sa halip na gamitin dito ang code nito.
• TB ay kabilang sa mga trackable ng Geocaching.com; gamitin ang tracking flow ng pinagmulan.
• GK ay kabilang sa mga trackable ng GeoKrety.org; gamitin ang tracking flow ng pinagmulan.
• GC ay Geocaching.com geocache identifier, hindi Geotrackable secret code.

Nagbabalik ang reserved o invalid na custom values ng problem response na may action at link sa dokumentasyon. Ang palaging ligtas na fallback ay alisin ang secretCode sa create request.

Mag-log ng journey stop

Ang direct journey stop ay magaan na route update kapag hindi kailangan ang buong location note.

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

Magkomento sa trackable

Maaaring mag-comment ang mga naka-sign-in na caller gamit ang kanilang bearer identity. Maaari ring mag-comment ang anonymous na caller sa activated trackable kapag may active secret-backed session ang client na ito o ipinapadala nito ang accessCode para sa eksaktong item na iyon.

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

Kasama sa validation errors ang mga field name

Nagdaragdag ng errors object ang mga HTTP 400 validation failure. Ang bawat key ay ang JSON property o bahagi ng request na kailangang itama, at array ang bawat value dahil maaaring lumabag ang isang field sa higit sa isang rule.

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

Maling JSON at content type

Request validation failure ang invalid na JSON. Panatilihin ang requestId, ayusin ang syntax, at ipadala muli ang body na may Content-Type: application/json. Sa halip, nangangailangan ang mga file-upload endpoint ng multipart/form-data at ng files o file part na may field name na partikular sa route.

Maaari pa ring lumabag sa business rule ang body na tama ang syntax. Gamitin ang errors para sa mga problema sa field, code para sa program logic, detail para sa konteksto, at action para sa susunod na hakbang. Huwag ipakita sa mga user ang raw server exception o stack trace.

Maingat na ulitin ang writes

Karaniwang ligtas subukang muli ang mga GET request. Maaaring lumikha ng data ang POST kahit mag-timeout ang client bago matanggap ang response. Bago ulitin ang paggawa ng trackable, i-refresh ang GET /api/trackables/mine at itugma ang resulta upang hindi lumikha ng magkaparehong pisikal na item ang network timeout.

Para sa 429 o pansamantalang 500, gumamit ng bounded exponential backoff na may jitter. Huminto kapag sinasabi ng action na kailangang baguhin ang mismong request. Huwag kailanman gawing automatic retry loop ang 400, 403, 404, 405, 409, 413, o 415.

Panatilihing kapaki-pakinabang ang diagnostics nang hindi naglalantad ng credentials

Huwag kailanman i-log ang Authorization headers, bearer o refresh tokens, passwords, cookies, secretCode, accessCode, QR payloads, private scan URLs, o raw na /trackable/{code} entry paths. I-redact ang mga ito bago ilagay sa telemetry, crash reports, screenshots, at support attachments.

Kabilang sa mga ligtas na diagnostic field ang requestId, ticketNumber, HTTP status, stable na code, method, route template, client version, at timestamp. Huwag kopyahin ang buong request body kapag maaari itong maglaman ng location text, eksaktong coordinates, contact details, o trackable credential.

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