URL Structure & Parameters

Created: Tue 29 Jul 2025 06:49:39 CEST
Document Version: 1.0 - Initial documentation
Security Classification: Public Technical Documentation
Target Audience: Frontend Developers, Backend Developers
Author: Paul Wisén

Overview

This document details the URL structure and parameter specifications for the s.plings.io Director service, including incoming QR code parameters and outgoing redirect parameters.

Incoming URL Format

Base Structure

https://s.plings.io?t=<type>&i=<instance>&p=<path>&cp=<class_pointer>

Core Parameters

Parameter	Name	Required	Description	Valid Values	Example
`t`	Type	Yes	Tag type identifier	`q`, `n`, `r`, `b`	`q` (QR code)
`i`	Instance Key	Yes	Unique instance identifier	Base58 string	`4kyQCd5tMDjJVWJH5h95gUcjq3qTX2cj5nwjVyqBRwLo`
`p`	Path	Yes	HD wallet derivation path	Dot-separated integers	`4.2.3.3.6`
`cp`	Class Pointer	No	Cryptographic class identifier	Base58 string	`4K7mX9abDcE`

Extended Parameters (Future)

Parameter	Name	Description	Example
`tx`	Transaction	Transaction type	`buy`, `rent`, `service`
`svc`	Service	Service identifier	`repair`, `insurance`
`price`	Price	Amount in cents	`2500`
`dur`	Duration	Time period	`1d`, `1w`, `1m`

Path Structure Breakdown

The path parameter (p) follows the HD wallet hierarchy:

p=4.2.3.3.6
  │ │ │ │ └── Instance ID
  │ │ │ └──── Batch/Series
  │ │ └────── Category
  │ └──────── Plant/Location
  └────────── Manufacturer ID

Outgoing Redirect Parameters

After processing, s.plings.io enriches the URL with additional parameters:

Standard Redirect Parameters

Parameter	Name	When Included	Description	Example
`oid`	Object ID	When object exists	Database UUID for object	`obj-550e8400-e29b-41d4`
`ikey`	Instance Key	Always	Original scanned identifier	`4kyQCd5tMDjJVWJH5h95gUcjq3qTX2cj5nwjVyqBRwLo`
`path`	HD Path	Always	Base58-encoded wallet path	`4.2.3.3.6`
`class`	Class ID	When resolved	Class UUID	`550e8400-e29b-41d4-a716-446655440000`
`cptr`	Class Pointer	When available	Cryptographic class pointer	`4K7mX9abDcE`
`src`	Source	Always	Tracking source	`scan`
`loc`	Location	With consent	GPS coordinates	`59.3293,18.0686`
`ts`	Timestamp	Optional	Scan timestamp	`1699123456789`

URL Transformation Examples

Example 1: Known Object for Sale

Input:
https://s.plings.io?t=q&i=4kyQCd5tMDjJVWJH5h95gUcjq3qTX2cj5nwjVyqBRwLo&p=4.2.3.3.6

Processing:
- Identifier verified ✓
- Object found in database
- Status: FOR_SALE
- Route to marketplace

Output:
https://market.plings.io/item?oid=obj-123&ikey=4kyQCd5tMDjJVWJH5h95gUcjq3qTX2cj5nwjVyqBRwLo&path=4.2.3.3.6&src=scan

Example 2: Unknown Generic Tag

Input:
https://s.plings.io?t=q&i=7mnPQd8uNEkKWXKI6i06hVdjr4rUY3dk6oxkWyrCSwMp&p=1.1.1.1.1

Processing:
- Identifier verified ✓
- No object found
- Generic Plings tag
- Route to creation flow

Output:
https://plings.io/create?ikey=7mnPQd8uNEkKWXKI6i06hVdjr4rUY3dk6oxkWyrCSwMp&path=1.1.1.1.1&cptr=4K7mX9&src=scan

Example 3: Manufacturer Pre-printed Tag

Input:
https://s.plings.io?t=q&i=9abCDe3vOPqRStUvWxYz&p=17.3.42.1.1001&cp=3K7mX9

Processing:
- Class pointer verified ✓
- No object instance yet
- IKEA product tag
- Route to claim flow

Output:
https://plings.io/claim?ikey=9abCDe3vOPqRStUvWxYz&path=17.3.42.1.1001&class=550e8400-e29b-41d4-a716-446655440000&cptr=3K7mX9&src=scan

Service-Specific Routing

The Director routes to different services based on object status:

Object Status	Target Service	Example URL
FOR_SALE	market.plings.io	`/item?oid=...`
FOR_RENT	rent.plings.io	`/listing?oid=...`
LENDABLE	lend.plings.io	`/borrow?oid=...`
LOST	plings.io	`/found?oid=...`
NORMAL	plings.io	`/o/{oid}?...`
UNKNOWN	plings.io	`/create?ikey=...`

Parameter Validation Rules

Instance Key (`i`)

Must be valid Base58 string
Length: 32-48 characters
No special characters except Base58 alphabet

Path (`p`)

Dot-separated integers only
Maximum 10 levels deep
Each segment: 1-999999
Example: 1.2.3.4.5

Type (`t`)

Enum: q (QR), n (NFC), r (RFID), b (Bluetooth)
Case sensitive
Default: q if missing

Class Pointer (`cp`)

Optional but recommended for manufacturer tags
Base58 encoded
Used for offline verification

Error Handling

Invalid parameters result in redirects to error pages:

https://plings.io/scan-error?reason=invalid&details=bad_instance_key
https://plings.io/scan-error?reason=rate_limit&retry_after=60
https://plings.io/scan-error?reason=system&code=500

Security Considerations

All parameters are validated and sanitized
SQL injection prevention on all inputs
XSS protection through proper encoding
Rate limiting applied per parameter combination
Invalid UTF-8 sequences rejected

Mobile App Integration

Native mobile apps should parse QR codes locally and use the GraphQL API directly rather than redirecting through s.plings.io:

// Mobile app direct API usage
const { data } = await api.resolveIdentifier({
  instanceKey: 'extracted_from_qr',
  path: 'extracted_from_qr'
});

Web browsers continue to use s.plings.io for routing and analytics.

Search Results: