Developers

API & Webhooks

Automate code issuance and warranty registration, and receive real-time events, with the Traciqo REST API. Endpoints follow the Frappe method convention and accept and return JSON.

Base URL: your workspace URL — https://<your-workspace>.traciqo.com (or your custom domain). API access is available on plans that include it; generate keys from your dashboard under Settings → API & Webhooks.

Authentication

Authenticate every request with your API key and secret, sent as headers:

X-Traciqo-API-Key: your_api_key
X-Traciqo-API-Secret: your_api_secret

Alternatively, use a standard token header:

Authorization: token your_api_key:your_api_secret

Each workspace has independent live and sandbox key pairs. The key you use determines which environment the request runs against.

Sandbox

Use your sandbox key pair to create test codes and warranties without affecting live data or plan usage. Requests made with a sandbox key are flagged automatically. You can also force sandbox behaviour with a header:

X-Traciqo-Sandbox: true

Responses & errors

Successful responses wrap the result in a message object, following the Frappe convention:

{
  "message": {
    "status": "success",
    "codes": ["VLC-0001", "VLC-0002"]
  }
}

Errors return a non-2xx status with a JSON body describing the problem. Common cases: 401/403 for invalid keys or insufficient plan permission, and 417 for validation errors such as exceeding your plan's code limit.

Create codes

Generate a batch of authentication codes. Quantity is limited by your plan for live requests.

POST /api/method/traciqo_core.traciqo_core.api.create_code

Parameter	Type		Description
`batch_name`	string	required	Label/batch identifier for the generated codes.
`quantity`	integer	optional	Number of codes to create. Defaults to `1`.
`product_id`	string	conditional	Required when creating dashboard-visible codes tied to a product.
`is_sandbox`	boolean	optional	Create as test data. Forced `true` when a sandbox key is used.

curl -X POST https://.traciqo.com/api/method/traciqo_core.traciqo_core.api.create_code \
  -H "X-Traciqo-API-Key: $TRACIQO_KEY" \
  -H "X-Traciqo-API-Secret: $TRACIQO_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_name": "SPRING-2026",
    "quantity": 100,
    "product_id": "PROD-00042"
  }'

Activate warranty

POST /api/method/traciqo_core.traciqo_core.api.activate_warranty

Parameter	Type		Description
`serial_number`	string	required	Serial of the unit to activate.
`customer_name`	string	required	Customer's full name.
`customer_email`	string	required	Customer's email for confirmation and reminders.
`customer_phone`	string	optional	Customer's phone number.

curl -X POST https://.traciqo.com/api/method/traciqo_core.traciqo_core.api.activate_warranty \ -H "Content-Type: application/json" \ -d '{ "serial_number": "SN-2026-0042", "customer_name": "Jane Doe", "customer_email": "[email protected]", "customer_phone": "+44 7700 900000" }'

Create / update product

Create a product, or update one by passing its product_id. Products group your authentication codes and drive warranty defaults.

POST /api/method/traciqo_core.traciqo_core.api.save_product

Parameter	Type		Description
`product_name`	string	required	Display name of the product.
`sku`	string	required	Your SKU; stored as the product code. Auto-generated if blank.
`product_id`	string	optional	Pass an existing product id to update instead of create.
`category`	string	optional	Free-form category label.
`product_image`	string	optional	Public image URL.
`description`	string	optional	Short description shown on verification pages.

curl -X POST https://<your-workspace>.traciqo.com/api/method/traciqo_core.traciqo_core.api.save_product \
  -H "X-Traciqo-API-Key: $TRACIQO_KEY" \
  -H "X-Traciqo-API-Secret: $TRACIQO_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Acme Pro Drill",
    "sku": "ACME-DRILL-01",
    "category": "Power Tools"
  }'

Returns {"status": "success", "product_id": "..."}.

Delete product

Delete a product you own. Codes that referenced it are unlinked, not deleted.

POST /api/method/traciqo_core.traciqo_core.api.delete_product

Parameter	Type		Description
`product_id`	string	required	The product id returned by `save_product`.

curl -X POST https://<your-workspace>.traciqo.com/api/method/traciqo_core.traciqo_core.api.delete_product \
  -H "X-Traciqo-API-Key: $TRACIQO_KEY" \
  -H "X-Traciqo-API-Secret: $TRACIQO_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "abc123xyz"}'

API usage stats

Retrieve your recent API usage for the authenticated workspace.

POST /api/method/traciqo_core.traciqo_core.api.get_api_usage_stats

Returns per-day request counts for the last 7 days and the 10 most recent failures:

{
  "message": {
    "usage": [{ "date": "2026-06-12", "status": "Success", "count": 42 }],
    "recent_failures": [{ "endpoint": "...", "status_code": 417, "error_message": "...", "timestamp": "..." }]
  }
}

Webhooks

Webhooks let Traciqo notify your systems the moment something happens — a code is created, a warranty is registered, or a product is scanned. Configure your endpoint in the dashboard under Settings → API & Webhooks: register a URL, send a test ping, and review recent deliveries with their status. All events are delivered to your endpoint.

Deliveries are sent as POST requests and are dispatched asynchronously. Every attempt is recorded and viewable in your webhook logs.

Events

Event	Triggered when
`Code Created`	One or more authentication codes are generated.
`Warranty Registered`	A customer registers / activates a warranty.
`Scan Captured`	A code's verification page is scanned.
`Ping Test`	Sent when you trigger a test from the dashboard.

Payload

Each delivery sends a JSON body and two headers:

X-Traciqo-Event — the event name (e.g. Warranty Registered).
X-Traciqo-Signature — an HMAC-SHA256 signature of the raw request body (see below).

For backwards compatibility every delivery also carries X-Verilink-Event and X-Verilink-Signature with identical values.

{
  "event": "Warranty Registered",
  "timestamp": "2026-06-12 12:00:00",
  "is_sandbox": false,
  "data": {
    "warranty_id": "W-PRO-DRILL-0042",
    "serial_no": "SN-2026-0042",
    "product_name": "Acme Pro Drill",
    "customer_name": "Jane Doe",
    "status": "Active"
  }
}

Event-specific data fields:

Event	Fields
`Code Created`	`code_id`, `serial_number`, `product_name`, `batch_id`
`Warranty Registered`	`warranty_id`, `serial_no`, `product_name`, `customer_name`, `status`
`Scan Captured`	`scan_id`, `code_id`, `serial_no`, `product_name`, `device`, `browser`, `scanned_at`

Verifying signatures

Always verify the signature before trusting a payload. Compute an HMAC-SHA256 of the raw request body using your webhook's secret, then compare it (constant-time) to the X-Traciqo-Signature header.

import hmac, hashlib

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Use the exact raw bytes of the request body when computing the signature — re-serialising the parsed JSON may change formatting and break the comparison.

New to the platform? Start with the Documentation →