API HBM Zero Touch

Propósito del Documento

El presente documento define la especificación técnica oficial para la integración de los Socios Comerciales de EQ con el Hub de Herramientas de Bloqueo (HBM Equality), mediante el consumo de APIs REST y la recepción de eventos asíncronos vía webhooks.

El objetivo es proporcionar una referencia orientada a integradores técnicos, que permita una implementación correcta.

Alcance de la Integración

Esta integración permite al socio comercial:

• Ejecutar acciones remotas de administración y bloqueo de
• Consultar información de dispositivos
• Gestionar el ciclo de vida de servicios asociados a
• Recibir notificaciones de eventos de estado mediante

Modelo de Seguridad y Autenticación

• TokendeAcceso
• El acceso a las APIs está protegido mediante token de autenticación.
• El token es emitido y administrado por
• Tipo de autenticación: Bearer
• El token es obligatorio para todas la colección.

Headers requeridos

Authorization: Bearer <ACCESS_TOKEN> 
Content-Type: application/json

Alcance del Token

• Cada token está asociado a:
  • Un Socio
  • Un conjunto específico de ServiceCode
• El uso de un servicio no habilitado resultará en rechazo de la

Activación de Servicios

• Control de Servicios por Cliente

Los servicios expuestos por HBM Equality no se habilitan de forma implícita.

• Cada ServiceCode debe ser activado explícitamente para el socio
• La activación es gestionada por

Convenciones Técnicas Generales

• Estilo arquitectónico: REST
• Formato de intercambio: JSON
• Codificación: UTF-8
• Fechas y horas: ISO-8601 (UTC)
• Campos case-sensitive
• Métodos HTTP estrictos (POST según endpoint) Manejo de errores
• 400 – Request inválido o incompleto
• 404 – Recurso inexistente
• 409 – Conflicto de estado o duplicidad
• 5xx – Error interno del servicio

Modelo de Servicios (Service Code)

Las acciones sobre los dispositivos se ejecutan mediante solicitudes REST que contienen un objeto service, el cual define explícitamente:

• El variant del Hub a
• El code que identifica la operación.
• Los parámetros requeridos por cada

Este modelo permite a HBM equality enrutar y validar la solicitud de forma consistente, manteniendo independencia de la implementación interna.

Device Management

 

ServiceCode	Descripción Técnica
DEVICE_ARCHIVE	Marca el dispositivo como inactivo sin eliminarlo
DEVICE_BLOCK_ADB	Restringe el uso de comandos ADB
DEVICE_BLOCK_AEPROVISION	Bloquea el aprovisionamiento Android Enterprise
DEVICE_BLOCK_FACTORY_RES ET	Impide restablecimiento de fábrica
DEVICE_SIMCTRL_DISABLE	Deshabilita reglas de control SIM
DEVICE_IMSI_SWAP	Registra cambio de IMSI
DEVICE_LOCK	Bloqueo completo del dispositivo
DEVICE_LOCK_MESSAGE	Bloqueo con mensaje personalizado
DEVICE_NOTIFY	Notificación informativa
DEVICE_PIN_UNLOCK	Desbloqueo mediante PIN autorizado
DEVICE_RELEASE	Libera el dispositivo del control del Hub
DEVICE_RELOAD	Recarga políticas y configuración del dispositivo
DEVICE_UNLOCK	Desbloqueo y restauración operativa

• Inventory

 

ServiceCode	Descripción Técnica
INVENTORY_UPLOAD	Registro de dispositivos en inventario

 

 

 

 

• Query

 

ServiceCode	Descripción Técnica
QUERY_DEVICES	Consulta de información de dispositivos

 

 

• Service Lifecycle

 

ServiceCode	Descripción Técnica
SERVICE_GET	Consulta servicios asociados
SERVICE_UPDATE	Actualización de servicios
SERVICE_DELETE	Eliminación de servicios
SERVICE_ACTIVATE	Activación de servicios

Estructura General de Solicitud

 

Toda solicitud de ejecución de servicio debe incluir, como mínimo, la siguiente estructura:

{ 

"service": {

"code": "QUERY_DEVICES",

"variant": "A"

},

"data": { "...": "..."

}

}

 

Descripción de Campos

Campo	Tipo	Descripción
service.code	string	Código del servicio a ejecutar
service.variant	string	Grupo de servicios
service.parameters	object	Parámetros específicos del servicio

 

 

Webhooks – Notificación de Eventos

 

HBM Equality soporta notificación asíncrona mediante webhooks HTTP.

• Gestión de Webhooks

ServiceCode	Descripción Técnica
WEBHOOK_CREATE	Alta de suscripción
WEBHOOK_GET_ALL	Consulta de suscripciones activas
WEBHOOK_DELETE	Eliminación de suscripción

Tipos de Eventos Soportados

• readyForUse
• idle
• enrolled
• active
• locked
• released
• Payload recibido del Evento

{

"eventType": "readyForUse", "deviceUid": "866XXXXXXXXXX08",

"status": "actionCompleted",

"receivedAt": "2025-12-18T05:23:23.546Z

}

Consideraciones de Integración

• El socio comercial debe validar códigos 401/403 antes de
• Reintentos automáticos solo recomendados para errores
• Cada solicitud válida la pertenencia del deviceUid al
• El webhook puede presentar un daley de envío de estatus, para mayor precisión del estatus actual del dispositivo usar Query Devices

Uso de la Colección Postman

 

Esta colección Postman proporciona ejemplos funcionales para consumir las APIs del Hub de Herramientas de Bloqueo (HBM Equality) y permite validar rápidamente la integración desde un entorno controlado.

La colección está organizada por dominio funcional (Device Management, Inventory, Query, Webhooks), y cada request refleja la estructura canónica requerida por la plataforma.

• Base URL

Todas las solicitudes deben ejecutarse contra el siguiente endpoint base: Base URL (Producción):

http://hbm-api.solucionfaas.com/v1/hbm

Base URL (Sandbox): N/A

Este valor debe configurarse como variable de entorno o variable de colección en Postman (baseUrl), y utilizarse en todas las requests.

• Autenticación

La colección asume autenticación mediante Bearer Token.

• El token es proporcionado por
• Debe enviarse en el header
• Es obligatorio para todas las

Ejemplo de header:

Authorization: Bearer