Trkn QR Codes

This document outlines the QR code API endpoints for managing QR codes, linking them to vehicles, and scanning them. The system supports linking QR codes to vehicle information with emergency contacts and tracking device integration.

Base URL

• Base path: /api2/qr

---

Check QR Code Status

Endpoint: GET /status/:code

Description: Checks the current status of a QR code without requiring authentication. This endpoint is useful for verifying whether a QR code exists and its current linking status.

Authorization:

• No authentication required (public endpoint)

URL Parameters:

Parameter	Type	Required	Description
code	string	required	The QR code ID to check status

Example Request:

curl -X GET 'https://api.trackongps.com/api2/qr/status/abc123xyz4'

Responses:

200 OK

{
  "status": "FRESH"
}

or

{
  "status": "USED"
}

500 Internal Server Error - QR Code Not Found

{
  "message": "QR code not found."
}

QR Code Status Values:

Status	Description
FRESH	QR code has been generated but not yet linked.
USED	QR code has been linked to a vehicle.

Notes:

• This is a public endpoint accessible without authentication
• Returns only the status of the QR code
• Useful for pre-validation before attempting to link a QR code

---

Scan QR Code

Endpoint: GET /scan/:code

Description: Retrieves complete information associated with a scanned QR code. This endpoint is public and does not require authentication. It returns the full QR code details including all metadata and linked information.

Authorization:

• No authentication required (public endpoint)

URL Parameters:

Parameter	Type	Required	Description
code	string	required	The QR code ID to scan.

Example Request:

curl -X GET 'https://api.trackongps.com/api2/qr/scan/abc123xyz4'

Responses:

200 OK - Linked QR Code

{
  "$id": "abc123xyz4",
  "batch_id": "batch_2026_01",
  "status": "USED",
  "userId": "user123",
  "deviceId": 12345,
  "linked_by": "{\"user_id\":\"user123\",\"name\":\"John Doe\",\"email\":\"john@example.com\",\"phone\":\"+1234567890\"}",
  "$createdAt": "2026-01-06T10:30:00.000Z",
  "$updatedAt": "2026-01-06T14:20:00.000Z",
  "$databaseId": "694804c9002d523ae9c4",
  "$collectionId": "695cc0ad002cf3514f37"
}

500 Internal Server Error - QR Code Not Found or Not Linked

{
  "message": "QR code not found or not linked."
}

Response Fields:

Field	Type	Description
$id	string	Unique QR code identifier.
batch_id	string	Batch ID this QR code belongs to.
status	string	Status of the QR code (FRESH or USED).
userId	string	User ID who owns this QR code.
deviceId	number	Associated tracking device ID (if linked).
linked_by	string	JSON string containing user info who linked the QR code.
$createdAt	string	ISO timestamp when the QR code was created.
$updatedAt	string	ISO timestamp when the QR code was last updated.
$databaseId	string	Appwrite database ID.
$collectionId	string	Appwrite collection ID.

Notes:

• This is a public endpoint accessible without authentication
• Returns error if QR code doesn't exist or is still in FRESH status
• The linked_by field contains JSON string with user information
• Use this endpoint when a QR code is physically scanned to retrieve vehicle/contact information

---

Get User's QR Codes

Endpoint: GET /

Description: Retrieves all QR codes owned by the authenticated user. This endpoint returns both used and fresh QR codes, including extended vehicle information for linked QR codes. For QR codes linked to tracking devices, it also fetches device information from the devices API. The response is limited to 5000 QR codes per request.

Authorization:

• Requires Cookie Based Authentication

Query Parameters:

Parameter	Type	Required	Description
status	string	optional	Filter by QR code status (FRESH or USED)

Example Request:

# Get all QR codes
curl -X GET 'https://api.trackongps.com/api2/qr' \
  -H "Cookie: JSESSIONID=your_session_id"

# Get only used QR codes
curl -X GET 'https://api.trackongps.com/api2/qr?status=USED' \
  -H "Cookie: JSESSIONID=your_session_id"

Responses:

200 OK

{
  "total": 8,
  "data": [
    {
      "code": "QR12345ABC",
      "status": "USED",
      "deviceId": 12345,
      "extended_vehicle": {
        "name": "Toyota Camry",
        "category": "Car",
        "registration": "ABC-1234",
        "emergency": ["+1234567890"],
        "contact": ["+1122334455"],
        "$id": "vehicle_id_123",
        "$createdAt": "2026-01-06T10:30:00.000Z",
        "$updatedAt": "2026-01-06T14:20:00.000Z"
      }
    },
    {
      "code": "QR34567VWX",
      "status": "FRESH",
      "deviceId": null,
      "extended_vehicle": null
    }
  ]
}

401 Unauthorized

{
  "message": "Authentication required"
}

500 Internal Server Error - Device Fetch Failed

{
  "message": "Failed to fetch device info."
}

Response Fields:

Field	Type	Description
total	number	Total number of QR codes owned by the user.
data	array	Array of QR code objects.
data[].code	string	Unique QR code identifier.
data[].status	string	Status of the QR code (FRESH or USED).
data[].deviceId	number	Associated device ID (null if not linked to a device).
data[].extended_vehicle	object	Vehicle information (null if QR code is not linked).
data[].extended_vehicle.name	string	Name of the vehicle (from device API if deviceId exists).
data[].extended_vehicle.category	string	Category of the vehicle (from device API if deviceId exists).
data[].extended_vehicle.registration	string	Vehicle registration number.
data[].extended_vehicle.emergency	string[]	Array of emergency contact phone numbers.
data[].extended_vehicle.contact	string[]	Array of regular contact phone numbers.
data[].extended_vehicle.$id	string	Extended vehicle document ID.
data[].extended_vehicle.$createdAt	string	ISO timestamp when the vehicle info was created.
data[].extended_vehicle.$updatedAt	string	ISO timestamp when the vehicle info was last updated.

Notes:

• Returns all QR codes where the user ID matches the authenticated user
• Maximum of 5000 QR codes returned per request
• QR codes with FRESH status will have extended_vehicle as null
• QR codes with USED status will include full vehicle information in extended_vehicle
• If a QR code has a deviceId, the system fetches device information (name, category, registration) from the devices API
• Device information takes precedence over extended_vehicle data for name, category, and registration fields
• The query selects only specific fields: status, $id, deviceId, and extended_vehicle.*
• Results include both linked and unlinked QR codes owned by the user

---

Link QR Code to Vehicle

Endpoint: POST /link-vehicle

Description: Links a QR code to a vehicle by providing vehicle information, category, emergency contacts, and regular contacts. The QR code must be in FRESH status to be linked. Once linked, the status changes to USED, and vehicle information is stored in the extended_vehicles table.

Authorization:

• Requires Cookie Based Authentication

Request Body:

Parameter	Type	Required	Description
code	string	required	The QR code ID to link.
device_id	number	optional	Associated device ID (if linking to a tracking device).
name	string	optional	Name/description of the vehicle or owner.
category	string	required	Category of the vehicle (e.g., Car, Bike, Truck).
registration	string	optional	Vehicle registration number.
emergency	string[]	required	Array of emergency contact phone numbers.
contact	string[]	required	Array of regular contact phone numbers.

Example Request:

curl -X POST 'https://api.trackongps.com/api2/qr/link-vehicle' \
  -H 'Content-Type: application/json' \
  -H "Cookie: JSESSIONID=your_session_id" \
  -d '{
    "code": "abc123xyz4",
    "device_id": 12345,
    "name": "Toyota Camry 2024",
    "category": "Car",
    "registration": "ABC-1234",
    "emergency": ["+1234567890", "+0987654321"],
    "contact": ["+1122334455", "+5566778899"]
  }'

Request Body:

{
  "code": "abc123xyz4",
  "device_id": 12345,
  "name": "Toyota Camry 2024",
  "category": "Car",
  "registration": "ABC-1234",
  "emergency": ["+1234567890", "+0987654321"],
  "contact": ["+1122334455", "+5566778899"]
}

Responses:

200 OK

{
  "message": "QR code linked successfully!.",
  "success": true
}

500 Internal Server Error - QR Code Not Found or Already Linked

{
  "message": "QR code not found or already linked."
}

500 Internal Server Error - Different User

{
  "message": "QR code is linked to a different user."
}

500 Internal Server Error - Link Failed

{
  "message": "Failed to link QR code."
}

500 Internal Server Error - Vehicle Creation Failed

{
  "message": "Failed to create vehicle info."
}

Notes:

• QR code must exist and have FRESH status
• If the QR code already has a userId, it must match the authenticated user's ID
• Once linked, the QR code status changes to USED
• Vehicle information is stored in the extended_vehicles table
• The device_id is optional and can be set to link the QR code to a tracking device
• Emergency and contact arrays are optional but recommended for emergency purposes

---

Update QR Code Information

Endpoint: PUT /:code

Description: Updates the information associated with a QR code. This endpoint allows users to update vehicle details, device association, emergency contacts, and regular contacts for QR codes they own.

Authorization:

• Requires Cookie Based Authentication

URL Parameters:

Parameter	Type	Required	Description
code	string	required	The QR code ID to update.

Request Body:

Parameter	Type	Required	Description
device_id	number	optional	New device ID to associate with the QR code.
name	string	optional	Updated name/description of the vehicle.
category	string	optional	Updated category of the vehicle.
registration	string	optional	Updated vehicle registration number.
emergency	string[]	optional	Updated array of emergency contact numbers.
contact	string[]	optional	Updated array of regular contact numbers.

Example Request:

curl -X PUT 'https://api.trackongps.com/api2/qr/abc123xyz4' \
  -H 'Content-Type: application/json' \
  -H "Cookie: JSESSIONID=your_session_id" \
  -d '{
    "device_id": 54321,
    "name": "Honda Accord 2025",
    "category": "Car",
    "registration": "XYZ-9876",
    "emergency": ["+9876543210"],
    "contact": ["+5544332211"]
  }'

Request Body:

{
  "device_id": 54321,
  "name": "Honda Accord 2025",
  "category": "Car",
  "registration": "XYZ-9876",
  "emergency": ["+9876543210"],
  "contact": ["+5544332211"]
}

Responses:

200 OK

{
  "message": "QR Info Updated!.",
  "success": true
}

or (if no extended_vehicle exists)

{
  "message": "Qr device Updated!",
  "success": true
}

500 Internal Server Error - QR Code Not Found or Not Owned

{
  "message": "QR code not found or not owned by user."
}

Notes:

• QR code must exist and be owned by the authenticated user
• All fields in the request body are optional - only provided fields will be updated
• If device_id is provided, it updates the QR code's device association
• If the QR code has no extended_vehicle record, only the device_id will be updated
• Existing values are preserved for fields not included in the request
• The update is performed on the extended_vehicles table for vehicle-related fields

---

Link QR Code to Self

Endpoint: POST /link-me

Description: Links an unlinked QR code to the authenticated user. This endpoint is used when a user wants to claim ownership of a QR code that is in FRESH status and has no owner. Once linked, the QR code's userId is set to the authenticated user.

Authorization:

• Requires Cookie Based Authentication

Request Body:

Parameter	Type	Required	Description
code	string	required	The QR code ID to link to user.

Example Request:

curl -X POST 'https://api.trackongps.com/api2/qr/link-me' \
  -H 'Content-Type: application/json' \
  -H "Cookie: JSESSIONID=your_session_id" \
  -d '{
    "code": "abc123xyz4"
  }'

Request Body:

{
  "code": "abc123xyz4"
}

Responses:

200 OK

{
  "message": "QR code linked successfully!.",
  "success": true
}

401 Unauthorized - QR Code Not Found or Already Linked

{
  "message": "QR code not found or already linked."
}

401 Unauthorized - Different User

{
  "message": "QR code is linked to a different user."
}

401 Unauthorized - Already Linked to You

{
  "message": "QR code is already linked to you."
}

Notes:

• QR code must exist and have FRESH status
• QR code must not have a userId set, or if it does, it must match the authenticated user
• This endpoint only links the QR code to the user - it does not link it to a vehicle
• After linking, use the POST /link-vehicle endpoint to associate vehicle information
• The system stores who linked the QR code in the linked_by field (user ID, name, email, phone)

---

Send OTP for Contact

Endpoint: POST /send-otp

Description: Initiates the contact process by sending an OTP to the person scanning the QR code. This validates the scanner's phone number before allowing them to contact the vehicle owner.

Authorization:

• No authentication required (public endpoint)

Request Body:

Parameter	Type	Required	Description
code	string	required	The QR code ID.
type	string	required	The intended contact method (call, sms).
phone	string	required	The scanner's phone number.

Example Request:

curl -X POST 'https://api.trackongps.com/api2/qr/send-otp' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "abc123xyz4",
    "type": "call",
    "phone": "+9779800000000"
  }'

Responses:

200 OK

{
  "message": "OTP sent successfully!.",
  "success": true
}

500 Internal Server Error

{
  "message": "QR code not found!"
}

---

Verify OTP

Endpoint: POST /verify-otp

Description: Verifies the OTP sent to the scanner. If valid, returns a temporary access token that allows the scanner to initiate contact with the owner.

Authorization:

• No authentication required (public endpoint)

Request Body:

Parameter	Type	Required	Description
code	string	optional	The QR code ID.
otp	string	optional	The OTP received via SMS.
type	string	optional	The contact method (call, sms).
phone	string	required	The scanner's phone number.

Example Request:

curl -X POST 'https://api.trackongps.com/api2/qr/verify-otp' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "abc123xyz4",
    "otp": "123456",
    "type": "call",
    "phone": "+9779800000000"
  }'

Responses:

200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "success": true
}

400 Bad Request

{
  "message": "Invalid OTP or phone number."
}

---

Contact Owner

Endpoint: POST /contact-owner

Description: Initiates contact with the vehicle owner. For calls, it triggers a bridge call between the scanner and owner. For SMS, it logs the message and notifies the owner.

Authorization:

• No authentication required (public endpoint)
• Requires a valid token from /verify-otp in the request body

Request Body:

Parameter	Type	Required	Description
code	string	required	The QR code ID.
token	string	required	The verification token from /verify-otp.
method	string	required	The contact method (call, sms, emergency).
isEmergency	boolean	optional	Whether this is an emergency (default: false).
category	string	optional	Category tag.
message	string	optional	Message content (required if method is SMS).

Example Request:

curl -X POST 'https://api.trackongps.com/api2/qr/contact-owner' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "abc123xyz4",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "method": "call",
    "isEmergency": false
  }'

Responses:

200 OK

{
  "message": "Owner contacted successfully!.",
  "success": true
}

400 Bad Request

{
  "message": "Invalid token!"
}

---

Get Contact Logs

Endpoint: GET /logs

Description: Retrieves contact logs for the user's QR codes. Users can fetch logs for all their QR codes or for a specific one. The logs include details about who tried to contact them, the method used, and any messages left.

Authorization:

• Requires Cookie Based Authentication

Query Parameters:

Parameter	Type	Required	Description
code	string	optional*	The QR code ID. Required if type is specific.
type	string	optional	The log type (all or specific). Default: all.
method	string	optional	Filter by contact method (call, sms, emergency).
page	number	optional	Page number for pagination (from PaginationDTO).
limit	number	optional	Items per page for pagination (from PaginationDTO).

Example Request:

# Get all logs for current user
curl -X GET 'https://api.trackongps.com/api2/qr/logs?page=1&limit=20' \
  -H "Cookie: JSESSIONID=your_session_id"

# Get logs for a specific QR code
curl -X GET 'https://api.trackongps.com/api2/qr/logs?type=specific&code=abc123xyz4' \
  -H "Cookie: JSESSIONID=your_session_id"

Responses:

200 OK

{
  "total": 24,
  "page": 1,
  "limit": 10,
  "data": [
    {
      "$id": "log_12345",
      "qr": "abc123xyz4",
      "method": "sms",
      "category": "visitor",
      "isEmergency": false,
      "message": "Please move your car, I am blocked.",
      "$createdAt": "2026-01-23T08:00:00.000Z",
      "$updatedAt": "2026-01-23T08:05:00.000Z",
      "client": {
        "ip": "1.2.3.4",
        "userAgent": "Mozilla/5.0..."
      }
    }
  ]
}

Notes:

• If type is all, it automatically fetches logs for all QR codes owned by the user.
• If type is specific, the code parameter must be provided.
• Returns logs sorted by creation date in descending order.
• The client object contains parsed metadata about the scanner.

---

Data Models

GetQrDTO

{
  status?: QrCodeStatus;  // Optional filter by status (FRESH or USED)
}

LinkQrDTO

{
  code: string;           // Required QR code ID
  device_id?: number;     // Optional device ID
  name?: string;          // Optional vehicle name
  category: string;       // Required vehicle category
  registration?: string;  // Optional vehicle registration
  emergency?: string[];   // Optional array of emergency contacts
  contact?: string[];     // Optional array of regular contacts
}

UpdateQrDTO

{
  device_id?: number;     // Optional device ID
  name?: string;          // Optional vehicle name
  category?: string;      // Optional vehicle category
  registration?: string;  // Optional vehicle registration
  emergency?: string[];   // Optional array of emergency contacts
  contact?: string[];     // Optional array of regular contacts
}

LinkMe

{
  code: string; // Required QR code ID
}

SendOTPDTO

{
  code: string; // Required QR code ID
  type: QrContactType; // Required contact type (call, sms)
  phone: string; // Required phone number (min 10 chars)
}

VerifyOTPDTO

{
  code?: string;          // Optional QR code ID
  otp?: string;           // Optional OTP
  type?: QrContactType;   // Optional contact type
  phone: string;          // Required phone number (min 10 chars)
}

ContactOwner

{
  code: string;           // Required QR code ID
  method: QrContactType;  // Required contact method
  isEmergency?: boolean;  // Optional emergency flag (default: false)
  token: string;          // Required verification token
  category?: string;      // Optional category
  message?: string;       // Optional message
}

GetContactLogsDTO

{
  code?: string;      // Optional (Required if type is 'specific')
  type?: QrLogType;   // Default: QrLogType.ALL
  method?: QrContactType;
  page?: number;      // Page number
  limit?: number;     // Items per page
}

QrCodeStatus Enum

enum QrCodeStatus {
  FRESH = "FRESH", // Generated but not linked
  USED = "USED", // Linked to a vehicle
}

QrLogType Enum

enum QrLogType {
  ALL = "all",
  SPECIFIC = "specific",
}

QrContactType Enum

enum QrContactType {
  CALL = "call",
  SMS = "sms",
  EMERGENCY = "emergency",
}

---

Workflow Examples

Complete QR Code Lifecycle

Workflow 1: User Claims and Links QR Code to Vehicle

1. User checks QR code status:

GET /api2/qr/status/abc123xyz4
# Response: { "status": "FRESH" }

1. User claims ownership of the QR code:

POST /api2/qr/link-me
{
  "code": "abc123xyz4"
}
# Response: { "message": "QR code linked successfully!.", "success": true }

1. User links the QR code to their vehicle:

POST /api2/qr/link-vehicle
{
  "code": "abc123xyz4",
  "device_id": 12345,
  "name": "My Toyota Camry",
  "category": "Car",
  "registration": "XYZ-789",
  "emergency": ["+1234567890"],
  "contact": ["+0987654321"]
}
# Response: { "message": "QR code linked successfully!.", "success": true }

1. User retrieves all their QR codes:

GET /api2/qr
# Response includes the newly linked QR code with vehicle info

1. Public user scans the QR code:

GET /api2/qr/scan/abc123xyz4
# Returns complete QR code information including user and vehicle details

Workflow 2: Update Existing QR Code Information

1. User wants to update vehicle registration:

PUT /api2/qr/abc123xyz4
{
  "registration": "NEW-REG-123"
}
# Response: { "message": "QR Info Updated!.", "success": true }

1. User wants to change the linked device:

PUT /api2/qr/abc123xyz4
{
  "device_id": 99999
}
# Response: { "message": "QR Info Updated!.", "success": true }

1. User updates emergency contacts:

PUT /api2/qr/abc123xyz4
{
  "emergency": ["+1111111111", "+2222222222", "+3333333333"]
}
# Response: { "message": "QR Info Updated!.", "success": true }

Workflow 3: Filter User's QR Codes by Status

1. Get only used QR codes:

GET /api2/qr?status=USED
# Returns only QR codes with status "USED"

1. Get only fresh QR codes:

GET /api2/qr?status=FRESH
# Returns only QR codes with status "FRESH"

Workflow 4: Contact Vehicle Owner

1. Scanner requests OTP:

POST /api2/qr/send-otp
{
  "code": "abc123xyz4",
  "type": "call",
  "phone": "+9779800000000"
}
# Response: { "message": "OTP sent successfully!.", "success": true }

1. Scanner verifies OTP:

POST /api2/qr/verify-otp
{
  "code": "abc123xyz4",
  "otp": "123456",
  "type": "call",
  "phone": "+9779800000000"
}
# Response: { "token": "ey...", "success": true }

1. Scanner initiates call to owner:

POST /api2/qr/contact-owner
{
  "code": "abc123xyz4",
  "token": "ey...",
  "method": "call"
}
# Response: { "message": "Owner contacted successfully!.", "success": true }

---

Error Handling

All endpoints follow standard HTTP status codes:

• 200 OK: Request successful
• 401 Unauthorized: Authentication required or insufficient privileges
• 500 Internal Server Error: Server-side error (includes validation failures)

Error responses include a message field describing the error and may include additional fields like description for more context.

---

Important Implementation Notes

Device Integration

When a QR code has a deviceId associated with it, the GET / endpoint fetches additional device information from the devices API (/devices?id={deviceId}). This information includes:

• Device name
• Device category
• Device registration (from attributes)

This device information takes precedence over the data stored in extended_vehicles for the name, category, and registration fields.

Data Consistency

• The extended_vehicles table stores vehicle-specific information linked to a QR code
• The qr_codes table stores the QR code metadata, status, and device association
• When updating QR information, both tables may be updated depending on the fields provided

Status Transitions

QR codes follow this status lifecycle:

1. FRESH: Initial state when QR code is generated or claimed by a user
2. USED: Final state after QR code is linked to a vehicle via POST /link-vehicle

Once a QR code reaches USED status, it cannot be unlinked or returned to FRESH status.