API · Visión general

Hay dos superficies públicas. Ambas son JSON sobre HTTPS y están versionadas por ruta (/v1).

API	La usa	Autenticación	Propósito
Dispositivos `/device/v1`	La app	Credenciales de dispositivo firmadas	Activar, enviar eventos, latido
Conector `/connector/v1`	Magento u otra plataforma	Llave secreta `sk_…` del cliente	Sincronizar pedidos, recoger coincidencias

Convenciones

Tiempos en ms epoch UTC; importes en céntimos enteros; moneda PEN.
Idempotente: repetir una petición idéntica nunca causa daño.
El tenant no viaja en el cuerpo: se deduce de la credencial, igual que el entorno.
El receptor ignora campos desconocidos; los cambios compatibles no suben la versión.

Método y ruta	Propósito
`POST /device/v1/activation`	Enlazar el teléfono con un código de un solo uso
`POST /device/v1/events`	Enviar un evento detectado
`POST /device/v1/heartbeat`	Salud, licencia, novedades

Cabecera	Contenido
`X-Device-Id`	Identificador recibido en la activación
`X-Timestamp`	Momento de la petición (ms epoch UTC)
`X-Signature-Alg`	`HMAC-SHA256`
`X-Signature`	Firma sobre timestamp, método, ruta y cuerpo
`Idempotency-Key`	En `events`: el `event_id`

Desviación de reloj tolerada: ±5 min.

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

Respuesta 201: device_id, secret (una sola vez), tenant_name, environment, api_base_url, license, server_time, config.

Código	Significado
`400`	Formato inválido
`401`	Dispositivo desconocido o firma incorrecta
`403`	Dispositivo revocado o licencia suspendida
`404` / `410`	Código de activación inexistente, usado o vencido
`429`	Demasiados intentos; respeta `Retry-After`