Eventos dinámicos (API)¶

El endpoint de eventos dinámicos expone un servicio HTTP en la instancia de Netsocs que permite crear eventos en la plataforma de forma totalmente dinámica, sin necesidad de dar de alta previamente el dispositivo, el objeto ni el tipo de evento.

URL del endpoint¶

Las peticiones deben enviarse con el método POST a la siguiente ruta (sustituye netsocs-server-instance por el host real de tu despliegue, por ejemplo https://mi-instancia.ejemplo.com):

POST https://netsocs-server-instance/api/netsocs/dh/dynamic-events

La ruta relativa sobre la base de la API es: /api/netsocs/dh/dynamic-events.

Autenticación¶

La autenticación para este endpoint es opcional. Si tu instancia tiene un token configurado para eventos dinámicos, debes enviarlo como Bearer token en la cabecera Authorization:

Authorization: Bearer <tu-token>

Puedes crear y administrar esos tokens en el módulo de Configuración, en la sección Tecnologías → Dynamic events (la misma área donde se gestionan dispositivos y motores de vídeo). Más contexto en Tecnologías.

Comportamiento¶

En una sola llamada, la plataforma puede:

Registrar el dispositivo de origen (si aún no existe).
Registrar el objeto asociado al evento (si aún no existe).
Registrar el tipo de evento (si aún no existe).
Crear el evento.

Es adecuado para integraciones externas, sistemas de terceros o cualquier origen que deba emitir eventos sin un proceso previo de configuración manual en la interfaz.

Solicitud¶

Cabeceras¶

Cabecera	Valor	Obligatorio
`Content-Type`	`application/json`	Sí
`Authorization`	`Bearer <token>`	No — solo si hay token definido en Configuración → Tecnologías → Dynamic events

Cuerpo (JSON)¶

{
  "source": {
    "device_name":   "string",
    "object_id":     "string",
    "object_domain": "string",
    "object_name":   "string",
    "object_type":   "string"
  },
  "event": {
    "event_type": {
      "event_type":          "string",
      "display_name":        "string",
      "display_description": "string"
    },
    "event_data": {
      "event_additional_properties": {
        "clave": "valor"
      },
      "images":      ["string"],
      "video_clips": ["string"]
    }
  }
}

Sección `source` (obligatoria)¶

Identifica el origen del evento: dispositivo y objeto.

Campo	Tipo	Obligatorio	Descripción
`device_name`	string	Sí	Nombre único del dispositivo que origina el evento. Si no existe, se crea automáticamente.
`object_id`	string	Sí	Identificador del objeto dentro del dominio (sin incluir el dominio en el valor).
`object_domain`	string	Sí	Dominio lógico del objeto (p. ej. `security`, `iot`). Se sugiere un formato del estilo `marca_dispositivo.tipo_objeto.funcionalidad`.
`object_name`	string	Sí	Nombre descriptivo del objeto.
`object_type`	string	Sí	Tipo de objeto (p. ej. `video_channel`, `sensor`, `door`).

El identificador final del objeto en la plataforma es {object_domain}.{object_id} (ej.: dominio security e id cam-01 → security.cam-01).

Sección `event` (obligatoria)¶

`event_type`¶

Campo	Tipo	Obligatorio	Descripción
`event_type`	string	Sí	Identificador único del tipo de evento (p. ej. `motion_detected`).
`display_name`	string	Sí	Nombre visible en la interfaz.
`display_description`	string	Sí	Descripción breve del tipo de evento.

Si el tipo de evento ya existe en el dominio, se respeta la configuración existente; si no, se crea con los valores enviados.

`event_data`¶

Campo	Tipo	Obligatorio	Descripción
`event_additional_properties`	objeto clave-valor	No	Propiedades personalizadas; los valores deben ser cadenas (pares string → string).
`images`	array de strings	No	URLs de imágenes asociadas al evento.
`video_clips`	array de strings	No	URLs de clips de vídeo asociados al evento.

Propiedad especial base64_image: dentro de event_additional_properties, la clave reservada base64_image puede contener una imagen en Base64 (con o sin prefijo data:image/...;base64,). La plataforma decodifica la imagen, la almacena y añade su URL a la lista images del evento. Formatos admitidos: JPEG, PNG, GIF, WEBP.

Respuestas¶

200 OK¶

Devuelve los datos del evento creado, por ejemplo:

{
  "id": "uuid-del-evento",
  "domain": "security",
  "event_type": "motion_detected",
  "rels": ["/objects/security.cam-01"],
  "images": [],
  "video_clips": [],
  "event_additional_properties": {},
  "created_at": "2026-02-18T10:30:00.000000000Z",
  "updated_at": "2026-02-18T10:30:00.000000000Z"
}

400 Bad Request¶

Faltan campos obligatorios o el JSON es inválido.

{
  "error": "source is required"
}

500 Internal Server Error¶

Error interno al registrar dispositivo, objeto o evento.

Comportamiento automático (resumen)¶

Situación	Comportamiento
El dispositivo no existe	Se crea como dispositivo genérico.
El dispositivo ya existe	Se reutiliza sin modificar.
El objeto no existe	Se crea y se asocia al dispositivo y dominio indicados.
El objeto ya existe	Se reutiliza el existente.
El tipo de evento no existe	Se crea con nombre y descripción enviados.
El tipo de evento ya existe	Se respeta la configuración existente.
Hay `base64_image`	Se decodifica, almacena y se añade la URL en `images`.

Notas importantes¶

Todos los campos de source son obligatorios; si alguno va vacío, la petición se rechaza con 400.
En object_id no debes incluir el dominio; la plataforma forma el ID completo como {object_domain}.{object_id}.
created_at y updated_at los asigna la plataforma en formato RFC 3339 (UTC).
El id del evento es un UUID generado automáticamente y se devuelve en la respuesta.

Ejemplo mínimo¶

POST https://netsocs-server-instance/api/netsocs/dh/dynamic-events
Content-Type: application/json

{
  "source": {
    "device_name":   "nvr-edificio-norte",
    "object_id":     "cam-entrada-01",
    "object_domain": "netsocs_partner.video_channel.video_stream",
    "object_name":   "Cámara entrada principal",
    "object_type":   "camera"
  },
  "event": {
    "event_type": {
      "event_type":          "motion_detected",
      "display_name":        "Movimiento detectado",
      "display_description": "Se detectó movimiento en el área monitoreada"
    },
    "event_data": {
      "event_additional_properties": {
        "zone":       "entrance",
        "confidence": "0.92"
      },
      "images": []
    }
  }
}