Documentación Ajax Enterprise API (traducida). Este contenido es una clonación en español de la documentación pública de Ajax: ajax.systems/support/posts/what-is-enterprise-api, api.ajax.systems/swagger-ui (secciones camera y monitoring). El objetivo es que el equipo entienda cada punto sin depender de salir de AJM.

¿Qué es la Enterprise API?

La Enterprise API de Ajax Systems es el conjunto de servicios que permite a una empresa integrar el sistema de seguridad Ajax con su propio software: panel propio, ERP, central receptora (CMS), SCADA, BMS o cualquier plataforma. No es la app del usuario final ni el PRO Desktop, es la capa company-to-cloud.

Tres componentes principales:

REST API de la empresa: leer hubs, dispositivos, clientes, objetos, usuarios, ejecutar comandos (armar/desarmar, pánico, mute), pedir fotos a MotionCam.
Company SQS queue (AWS): cola FIFO donde Ajax publica en tiempo real los eventos de todos los hubs de la company (alarmas, tampers, batería baja, etc.).
Translator channel + Receivers: puente hacia centrales monitoreo SIA-DC09 / MicroKey / receptor TCP propio.

AJM consume las dos primeras. La tercera es opcional y solo aplica si reenvías eventos a un receptor externo tipo central de monitoreo tradicional.

Arquitectura de integración

Un cliente Enterprise tiene asignado:

Integration ID (público) — identifica la integración. En nuestro caso BmwS4JgT.
X-Api-Key (secreto) — credencial estática que va en todos los requests.
Company Token (secreto) — credencial estática para los endpoints company-scoped; reemplaza al login user/password legacy.
Company ID — UUID de la empresa, presente como parámetro en muchos endpoints. En nuestro caso AABC1FAA-....
SQS URL — la URL de la cola FIFO de eventos, asignada por Ajax al activar la cola.

El flujo de control nunca es directo cliente-final → AJM. Es siempre Hubs → Ajax Cloud → (REST + SQS) → AJM.

Los dos flujos de eventos

Ajax ofrece dos caminos distintos para recibir eventos, y se confunden seguido:

Company SQS queue

Cola AWS SQS FIFO push.
Latencia ≈ tiempo real (segundos).
Recibe todos los eventos de todos los hubs de la company.
Activación: manual por Ajax, vía mail a soporte.
Pensada para integraciones tipo dashboard / BI / SCADA / nuestra app AJM.

Translator + Receivers

Reenvío en protocolo SIA-DC09 / MicroKey a una IP:puerto.
Por account (hub), no por company.
Activación: vía API /company/{cid}/receivers + asignación a hubs.
Pensado para centrales de monitoreo tradicionales (CMS).

Para AJM usamos SQS. La parte de Receivers no es necesaria salvo que duplicáramos los eventos a una central externa.

REST API · base y autenticación

Base URL: https://api.ajax.systems

Headers obligatorios:

X-Api-Key: <clave Enterprise>
X-Company-Token: <company token>
Content-Type: application/json
Accept: application/json

Los endpoints company-scoped llevan el patrón /api/v1/company/{companyId}/.... Los más usados por AJM:

GET /api/v1/company/{cid}/hubs — lista de hubs.
GET /api/v1/company/{cid}/hubs/{hubId} — detalle hub.
GET /api/v1/company/{cid}/hubs/{hubId}/devices — sensores del hub.
GET /api/v1/company/{cid}/hubs/{hubId}/logs — historial reciente de eventos.
GET /api/v1/company/{cid}/clients y /objects.
POST /api/v1/company/{cid}/hubs/{hubId}/command — armar/desarmar/pánico/mute.
POST /api/v1/company/{cid}/hubs/{hubId}/devices/{deviceId}/command — pedir foto, etc.

Rate limits: Ajax devuelve HTTP 429 con Retry-After. AJM respeta el header y reintenta con backoff.

Company SQS Queue (eventos en tiempo real)

Es una cola AWS SQS FIFO donde Ajax publica un mensaje por cada evento generado por cualquier hub vinculado a la company. La conexión se hace con credenciales AWS propias de la integración (Access Key + Secret) y la URL exacta de la cola:

SQS_URL=https://sqs.<region>.amazonaws.com/<account>/ajax-events-<intId>-prod.fifo

Patrón recomendado: Long Polling con WaitTimeSeconds=20, MaxNumberOfMessages=10. Procesar primero, luego DeleteMessage con el ReceiptHandle. Si fallás antes de borrar, el mensaje vuelve a quedar visible cuando vence el visibility timeout.

Shape del mensaje (campos clave dentro del body JSON):

{
  "eventId": "uuid",
  "eventDateTime": "2026-05-14T12:34:56.000Z",
  "eventTag": "MOTION_DETECTED",
  "hubId": "...",
  "hubName": "...",
  "sourceObjectId": "...",
  "sourceObjectType": "MOTION_PROTECT",
  "sourceObjectName": "Cocina",
  "userId": "...",
  "groupId": "...",
  "additionalData": {
    "temperature": 21.5,
    "PHOTOS_RESOURCE_DESCRIPTION": { /* MotionCam */ }
  }
}

Los mensajes son FIFO con MessageGroupId por hub. Eso garantiza orden por hub y permite paralelizar por grupos.

Translator channel + Receivers

Flujo paralelo, pensado para reenviar eventos a una central receptora tradicional (formato SIA-DC09 o MicroKey). Pasos:

Crear un Receiver: POST /api/v1/company/{cid}/receivers con host, puerto, protocolo, cuenta.
Asignar receiver a un hub (account number).
Activar el canal Translator en cada hub: translatorChannelState=ENABLED.

Importante: NO existe un endpoint público tipo POST /translator/activate. La activación del canal Translator a SQS (no Receivers) requiere que Ajax lo habilite del lado de la company; se solicita por email a soporte.

Camera · fotos on-demand de MotionCam

MotionCam, MotionCam Outdoor y MotionCam (PhOD) Jeweller pueden tomar fotos a pedido. El flujo es asíncrono: pedís la foto y la imagen llega después en un evento por la cola SQS, no en la respuesta HTTP.

1) Solicitar foto:

POST /api/v1/company/{cid}/hubs/{hubId}/devices/{deviceId}/command
{
  "command": "MAKE_PHOTO",
  "deviceType": "MotionCam"
}

2) Esperar el evento PHOTO_BY_SCENARIO / VISUAL_ALARM_VERIFICATION en SQS. En additionalData.PHOTOS_RESOURCE_DESCRIPTION.orderedResourceLinks[] vienen las URLs S3 firmadas (expiran rápido, hay que bajarlas / cachearlas).

Otros endpoints de la sección camera: listar fotos por panic alarm de un hub, listar fotos por scenario, descargar un recurso por ID.

Monitoring · operaciones

Conjunto de endpoints orientados a empresas con perfil Security Company (central de monitoreo). Incluye:

Asignación de hubs a operadores / equipos.
Solicitudes de usuario (panic test, dudas, etc.) y contador /monitoring/requests/fromUsers/counter.
Manejo de alarmas activas: confirmar, ignorar, escalar.
Bitácora de intervenciones y SLA.

Si la company NO tiene perfil Security Company, Ajax devuelve HTTP 403 en estos endpoints. Es normal y esperable.

Mapeo de eventos (eventTag → AJM)

El campo eventTag que viene en la SQS es un identificador lógico (no SIA/CID). Algunos comunes:

MOTION_DETECTED → Movimiento detectado
DOOR_OPENED → Apertura
GLASS_BREAK → Rotura de vidrio
FIRE_DETECTED → Fuego
FLOOD_DETECTED → Inundación
CO_DETECTED → Monóxido
PANIC_BUTTON_PRESSED → Pánico
TAMPER_ALARM → Tamper
DEVICE_LOST → Dispositivo perdido
LOW_BATTERY → Batería baja
EXTERNAL_POWER_FAILURE → Sin 220V
JAMMING_DETECTED → Jamming RF
HUB_ARMED → Hub armado
HUB_DISARMED → Hub desarmado
DEVICE_RECONNECTED → Reconexión
EXTERNAL_POWER_RESTORED → 220V OK

AJM mantiene en src/utils/event-mapper.ts un catálogo de ~80 tags con su severidad, descripción y categoría. Tags no mapeados se muestran como tag crudo con severidad INFO.

Activación de la SQS · email a Ajax

La cola SQS de la company existe físicamente desde el momento en que Ajax provisiona la integración (por eso ya tenemos URL + Access Key + Secret), pero los eventos no se publican hasta que Ajax habilita explícitamente el flag interno translatorChannelState para nuestra company.

No hay endpoint público para hacerlo. Hay que mandar un mail. Plantilla:

Para: support@ajax.systems
Asunto: Enable Company SQS queue for Integration BmwS4JgT

Hi Ajax team,

Could you please enable the Company SQS queue (translatorChannelState)
for our Enterprise integration?

  Company name:    IES Uruguay
  Integration ID:  BmwS4JgT
  Company ID:      AABC1FAA-...
  SQS URL:         https://sqs.eu-central-1.amazonaws.com/431102941320/ajax-events-BmwS4JgT-prod.fifo

We already have X-Api-Key and Company Token working. We just need
events to start being published to the queue.

Thanks,
IES Uruguay — Mauricio Favaro

Mientras esa cola no esté activa, AJM consume eventos vía polling de /logs de cada hub cada 60s (modo de respaldo). Funciona, pero con latencia y sin payload completo.

Referencias oficiales

ajax.systems/support/posts/what-is-enterprise-api/
api.ajax.systems/swagger-ui/ (sección camera, monitoring, company)
support.ajax.systems
Contacto: support@ajax.systems

Ajax Manager

Estado de la cola

Mi perfil

Cambiar contraseña