API · Overview

There are two public surfaces. Both are JSON over HTTPS and versioned by path (/v1).

API	Used by	Authentication	Purpose
Devices `/device/v1`	The app	Signed device credentials	Activate, send events, heartbeat
Connector `/connector/v1`	Magento or another platform	The customer’s secret key `sk_…`	Sync orders, collect matches

Conventions

Times in epoch ms UTC; amounts in integer cents; currency PEN.
Idempotent: repeating an identical request never causes harm.
The tenant is not in the body: it is derived from the credential, as is the environment.
The receiver ignores unknown fields; compatible changes do not bump the version.

Method and path	Purpose
`POST /device/v1/activation`	Link the phone with a one-time code
`POST /device/v1/events`	Send a detected event
`POST /device/v1/heartbeat`	Health, license, news

Header	Content
`X-Device-Id`	Identifier received on activation
`X-Timestamp`	Request time (epoch ms UTC)
`X-Signature-Alg`	`HMAC-SHA256`
`X-Signature`	Signature over timestamp, method, path and body
`Idempotency-Key`	On `events`: the `event_id`

Tolerated clock skew: ±5 min.

{
  "activation_code": "ABCD-1234",
  "device_label": "Main counter",
  "app_version": "1.0.0",
  "platform": "android",
  "os_version": "14"
}

201 response: device_id, secret (once only), tenant_name, environment, api_base_url, license, server_time, config.

Code	Meaning
`400`	Invalid format
`401`	Unknown device or wrong signature
`403`	Device revoked or license suspended
`404` / `410`	Activation code unknown, used or expired
`429`	Too many attempts; honor `Retry-After`