Integración Genérica SITIA Cloud Events

Especificación para integrar sistemas usando CloudEvents 1.0 en formato JSON. Evento: sitia.ingestion.vehicle-detected.v1.

Esta especificación define el evento genérico de ingesta vehicular basado en CloudEvents 1.0 en formato JSON. Soporta envío unitario y en lote.

Hasta el momento solo se soporta CloudEvents en formato JSON (RFC8259). Formatos y bindings adicionales podrán incorporarse en versiones futuras.

🏗️ Arquitectura de Integración

Ejemplo mínimo (evento unitario)

{
  "specversion": "1.0",
  "id": "1118d68a-e245-4e6c-b768-64b085bd9e1f",
  "source": "urn:codigo-productor-datos:type:identifier",
  "type": "sitia.ingestion.vehicle-detected.v1",
  "datacontenttype": "application/json",
  "time": "2025-08-06T03:22:00Z",
  "subject": null,
  "data": {
    "detectionTime": "2025-08-05T23:22:00-04:00",
    "vehiclePlate": null,
    "vehicleTypeBasic": "",
    "vehicleTypeSpecific": "",
    "vehicleColor": "",
    "vehicleMake": "",
    "vehicleModel": "",
    "latitude": -33.4489078,
    "longitude": -70.6693825,
    "vehicleOrientation": "",
    "relativeMotion": "",
    "contextImage": "",
    "vehiclePlateImage": "",
    "plateConfidence": null,
    "vehicleTypeConfidence": 0.92,
    "vehicleColorConfidence": null,
    "vehicleMakeConfidence": null,
    "vehicleModelConfidence": null
  }
}

Las imágenes (contextImage, vehiclePlateImage) deben enviarse como base64 con prefijo de tipo MIME (ej: data:image/jpeg;base64,/9j/4AAQ...). No se soporta autenticación para URLs externas por razones de seguridad.

Detección sin placa: El ejemplo muestra vehiclePlate: null y subject: null para casos donde se detecta un vehículo pero no se logra leer la placa (calidad de imagen, vehículo sin placa, etc.). En estos casos, el evento sigue siendo válido y útil para investigaciones de vehículos sin placas (con imágenes de evidencia) o análisis de tráfico.

Confidence Scores: Los valores de confianza (0.0 - 1.0) ayudan a SITIA a evaluar la calidad de las detecciones. Se recomienda incluir estos valores cuando estén disponibles en la fuente. Un valor null indica que el sistema fuente no proporciona confianza para ese atributo.

Tabla de propiedades y reglas

Propiedad	Tipo	Requerido	Validación / Reglas	Ejemplo
`specversion`	string	sí	Debe ser exactamente `"1.0"` (CloudEvents v1.0.x).	`"1.0"`
`id`	string	sí	Identificador único del evento. Recomendado UUID v4/v7. Unicidad por combinación `source`+`id`.	`"1118d68a-e245-4e6c-b768-64b085bd9e1f"`
`source`	string (URI-reference)	sí	Debe cumplir la forma URN definida más abajo. Debe estar registrado en el Registro de Productor.	`"urn:municipalidad-valdivia:camera:plaza-cam02"`
`type`	string	sí	Valor fijo para esta especificación.	`"sitia.ingestion.vehicle-detected.v1"`
`time`	string (RFC3339)	sí	Instante de creación del evento en el sistema fuente. Formato ISO 8601 / RFC3339. Puede diferir de `detectionTime` debido al procesamiento interno.	`"2025-08-06T03:22:00Z"`
`datacontenttype`	string	sí	Indica que `data` está serializado como JSON.	`"application/json"`
`subject`	string	no	Placa detectada normalizada (mayúsculas, sin espacios/guiones). Acelera el procesamiento al evitar acceso a `data`. Puede ser `null` si la fuente no la determina; preferir valor.	`"ABCJ12"`
`data.detectionTime`	string (RFC3339)	sí	Instante de detección. Debe incluir zona horaria (`Z` u offset ±hh:mm).	`"2025-08-05T23:22:00-04:00"`
`data.vehiclePlate`	string	condicional	Placa detectada. Obligatorio si se logra leer la placa. Puede ser `null` o string vacío si no se detecta placa, vehículo sin placa, o lectura fallida. Patrón recomendado: `[A-Z0-9]{4,10}` (sin espacios/guiones).	`"ABCJ12"`
`data.vehicleTypeBasic`	string	no	Clasificación general (p. ej., `car`, `motorcycle`, `truck`, `bus`, `van`, `suv`). Vocabulario recomendado, no restrictivo.	`"car"`
`data.vehicleTypeSpecific`	string	no	Subtipo más específico. Libre.	`"sedan"`
`data.vehicleColor`	string	no	Color estimado. Se recomienda vocabulario acotado (white, black, gray, silver, blue, red, green, yellow, brown, other).	`"white"`
`data.vehicleMake`	string	no	Marca del vehículo.	`"Toyota"`
`data.vehicleModel`	string	no	Modelo del vehículo.	`"Corolla"`
`data.latitude`	number	null	condicional	Latitud WGS84 (mín. 7 decimales). Obligatorio si el `source` es móvil o no está registrado con ubicación fija. Opcional si el `source` tiene ubicación fija en el registro. Rango [-90, 90].
`data.longitude`	number	null	condicional	Longitud WGS84 (mín. 7 decimales). Obligatorio si el `source` es móvil o no está registrado con ubicación fija. Opcional si el `source` tiene ubicación fija en el registro. Rango [-180, 180].
`data.vehicleOrientation`	string	no	Orientación relativa de captura (p. ej., `front`, `rear`, `left`, `right`, `unknown`).	`"front"`
`data.relativeMotion`	string	no	Movimiento relativo al sensor (p. ej., `Approaching`, `Departing`, `Static`).	`"Approaching"`
`data.contextImage`	string (base64)	no	Imagen de contexto/overview codificada en base64. Formato recomendado: JPEG.	`"data:image/jpeg;base64,/9j/4AA.."`
`data.vehiclePlateImage`	string (base64)	no	Recorte de placa codificado en base64. Formato recomendado: JPEG.	`"data:image/jpeg;base64,/9j/4A..."`
`data.plateConfidence`	number	no	Confianza de detección de placa (0.0 - 1.0). Indica qué tan seguro está el sistema de la lectura de la placa.	`0.95`
`data.vehicleTypeConfidence`	number	no	Confianza de clasificación de tipo vehicular (0.0 - 1.0). Aplica tanto para `vehicleTypeBasic` como `vehicleTypeSpecific`.	`0.87`
`data.vehicleColorConfidence`	number	no	Confianza de detección de color (0.0 - 1.0). Indica certeza del color estimado.	`0.72`
`data.vehicleMakeConfidence`	number	no	Confianza de detección de marca (0.0 - 1.0). Indica certeza de la marca identificada.	`0.89`
`data.vehicleModelConfidence`	number	no	Confianza de detección de modelo (0.0 - 1.0). Indica certeza del modelo identificado.	`0.83`

Definición de `source`

En esta especificación, el atributo source debe ser un URN que identifique de forma única y persistente a la fuente que emite el evento. Cada source debe estar pre-registrado en el Registro de Productor, excepto que sea una fuente móvil o virtual.

Forma canónica URN:

urn:<codigo-productor-datos>:<type>:<identifier>

owner (codigo-productor-datos): Código único asignado en el registro, en minúsculas y separado por guiones (a-z0-9-). No se permiten puntos u otros símbolos. Ej.: municipalidad-valdivia, autopista-centrica.
type: Catálogo de tipos base: camera, parking-gate, toll-gantry, cloud-processor, edge-node, vehicle-camera, mobile-device, sensor, x-*.
identifier: ID estable único en el ámbito del owner y type (permitidos: letras/dígitos/._:-). No puede contener espacios.

Tipos de Source Soportados

Tipo	Descripción	Ubicación	Ejemplo de Uso
`camera`	Cámara fija de teleprotección o LPR/ANPR	Fija	Cámaras municipales, sistemas de vigilancia urbana
`parking-gate`	Portal o barrera de estacionamiento	Fija	Control de acceso vehicular en edificios, centros comerciales
`toll-gantry`	Pórtico de peaje o control de tráfico	Fija	Autopistas, puentes, sistemas de cobro automático
`cloud-processor`	Procesador en la nube que analiza múltiples fuentes	Virtual	Sistemas de IA centralizados, analytics en tiempo real
`edge-node`	Nodo de procesamiento local en el borde	Fija	Servidores locales que procesan múltiples cámaras
`vehicle-camera`	Cámara instalada en vehículo móvil	Móvil	Patrulleros, vehículos de transporte público, flotas
`mobile-device`	Dispositivo móvil (smartphone, tablet)	Móvil	Aplicaciones de reportes ciudadanos, inspectores móviles
`sensor`	Sensor especializado (magnético, infrarrojo, etc.)	Fija	Detectores de presencia vehicular, sensores de tráfico
`x-*`	Tipos personalizados (extensión)	Variable	Tipos específicos no contemplados en el catálogo base

Para sources móviles (vehicle-camera, mobile-device), las coordenadas latitude y longitude son obligatorias en cada evento. Para sources fijos, las coordenadas son opcionales si la ubicación está registrada previamente.

Ejemplos válidos:

urn:municipalidad-valdivia:camera:plaza-sur-cam02
urn:autopista-centrica:toll-gantry:k85-sur-03
urn:sistema-x:vehicle-camera:bus-4321-front

Esquema (restricto a URN) sugerido para validación local:

{
  "type": "string",
  "pattern": "^urn:[a-z0-9-]+:(camera|parking-gate|toll-gantry|cloud-processor|edge-node|vehicle-camera|mobile-device|sensor|x-[a-z0-9-]+):[A-Za-z0-9._:-]+$"
}

Autenticación y seguridad

Este protocolo usa OAuth2 (Client Credentials) como método de autenticación primario, conforme a los mecanismos de seguridad.

Credenciales: client_id, client_secret, token_endpoint (provistos tras el registro de productor).
Cabecera HTTP:

Authorization: Bearer <token>

Nota: El uso de API Keys es una alternativa permitida solo si es acordada y emitida por SITIA para su integración.

Envío HTTP — unitario y en lote

Ambientes y autenticación: OAuth2 (Client Credentials) con cabecera Authorization: Bearer <token> y TLS 1.3. Consulte su token y allowlist de IP con el equipo SITIA.

Unitario

POST https://sandboxsapp.carabineros.cl/api/integration-test/events/vehicle-detected
Accept: application/cloudevents+json
Content-Type: application/cloudevents+json
Authorization: Bearer {token}

{ ...CloudEvent JSON como en el ejemplo mínimo... }

Lote (JSON Batch Format)

POST https://sandboxsapp.carabineros.cl/api/integration-test/events/vehicle-detected
Accept: application/cloudevents-batch+json
Content-Type: application/cloudevents-batch+json
Authorization: Bearer {token}

[
  { /* CloudEvent #1 */ },
  { /* CloudEvent #2 */ }
]

SITIA exige que cada elemento del lote sea un CloudEvent válido e independiente.

Referencias

CloudEvents JSON Format v1.0.2: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md
SDKs oficiales CloudEvents: https://github.com/cloudevents/spec/blob/main/cloudevents/SDK.md
Integración legada (referencia): /docs/integraciones/sitia-generica-legada
Registro de Productor: /docs/requerimientos/registro-productor

En esta página