Crear o actualizar información del día

🔒

Requiere proveedor custom

Este endpoint sirve para que tu empresa envíe a Airbag los eventos de seguridad de su propio sistema de telemetría.

Para usarlo, tanto la empresa como cada conductor deben estar configurados con el proveedor custom. Si la empresa no lo está, la API responde 400 con el mensaje "Company does not have the necessary configuration."; si un conductor no lo está, el registro se rechaza con el motivo "User has invalid provider (...)". Para activar esta configuración, contacta a tu ejecutivo de Airbag.

[ POST ]

Esta ruta permite crear un documento donde se recopile la cantidad de eventos de seguridad ocurridos por día. También guarda la distancia y la duración que registró el conductor en ese día y, si tu plataforma lo calcula, su puntaje de seguridad.

https://sync.airbagtech.io/provider-data

Campos

El cuerpo es un array de registros (mínimo 1, máximo 50). Cada registro tiene los siguientes campos:

Nombre	Tipo	Requerido	Descripción
driverId	String	Sí	ID del conductor. Acepta el ID que tu empresa usó al crear el conductor o el `airbagId` que devuelve la API.
distance	Number	Sí	Distancia recorrida por el conductor en el día (en kilómetros). Mayor o igual a 0; puede incluir decimales.
duration	Number	Sí	Tiempo de conducción del día en horas. Mayor o igual a 0; puede incluir decimales.
score	Number	No	Puntuación de seguridad del conductor según tu sistema (generalmente de 0 a 100). Mayor o igual a 0. Si no se envía, se guarda como `null`.
date	String	Sí	Fecha del registro en formato `YYYY-MM-DD`. Ejemplo: `"2025-10-19"`.
securityEvents	Array	Sí	Lista de eventos de seguridad del día. Es obligatoria, pero puede ir vacía (`[]`) para indicar que el conductor no tuvo eventos ese día.
event	String	Sí	Tipo de evento de seguridad. Debe ser uno de los eventos válidos.
count	Number	Sí	Cantidad de veces que ocurrió este evento en el día. Mayor o igual a 0.

Eventos válidos

El campo event acepta únicamente estos 29 valores. Cualquier otro valor rechaza el registro con un error 400 cuyo motivo empieza con "Security event error".

29 tipos de evento

Velocidad y señales

Eventos relacionados con la velocidad y el respeto a las señales de tránsito.

speedingExceso de velocidad
ran_red_lightSemáforo ignorado
did_not_yieldNo cedió paso
rolling_stopAlto incompleto

Maniobras bruscas

Fuerzas detectadas por el acelerómetro en maniobras agresivas.

accelerationAceleración brusca
brakingFrenado brusco
corneringCurva brusca
yaw_controlCorrección de curva

Distracción

Pérdida de atención del conductor al volante.

phone_distractionDistracción por teléfono
mobile_usageUso del celular
distractionConducción distraída
drowsySomnolencia
late_responseReacción tardía
eating_drinkingComiendo/bebiendo
smokingFumando

Proximidad y colisión

Distancia de seguimiento y riesgo de impacto con otros vehículos.

near_collisionCasi choque
crashChoque
forward_collision_warningAlerta de choque
tailgatingConducción pegada
following_distanceDistancia de seguimiento

Carril

Desviaciones respecto al carril.

lane_departureInvasión de carril

Seguridad del vehículo

Condiciones del vehículo y del equipo de seguridad.

no_seatbeltSin cinturón de seguridad
obstructed_cameraCámara obstruida
rollover_protectionRiesgo de volcadura

Estilo de manejo

Patrones de conducción, deseables o de riesgo.

aggressive_drivingConducción agresiva
unsafe_maneuverManiobra insegura
unsafe_parkingEstacionamiento inseguro
defensive_drivingConducción defensiva

General

Indicador global del día.

overallEvaluación general

Headers

Content-Type	Authorization
application/json	apikey `{{API_KEY}}`

Body

[
  {
    "driverId": "5678",
    "distance": 150.5,
    "duration": 3.5,
    "score": 95,
    "date": "2025-10-19",
    "securityEvents": [
      {
        "event": "braking",
        "count": 11
      },
      {
        "event": "speeding",
        "count": 2
      }
    ]
  },
  {
    "driverId": "1234",
    "distance": 200,
    "duration": 4.25,
    "date": "2025-10-19",
    "securityEvents": []
  }
]

En el ejemplo, el segundo registro no envía score (se guarda como null) y envía securityEvents vacío porque el conductor no tuvo eventos ese día.

Ejemplo

curl --location 'https://sync.airbagtech.io/provider-data' \
--header 'Content-Type: application/json' \
--header 'Authorization: apikey {{API_KEY}}' \
--data '[
  {
    "driverId": "5678",
    "distance": 150.5,
    "duration": 3.5,
    "score": 95,
    "date": "2025-10-19",
    "securityEvents": [
      {
        "event": "braking",
        "count": 11
      },
      {
        "event": "speeding",
        "count": 2
      }
    ]
  },
  {
    "driverId": "1234",
    "distance": 200,
    "duration": 4.25,
    "date": "2025-10-19",
    "securityEvents": []
  }
]'

Respuesta exitosa

Código 201 Created.

{
  "status": true,
  "message": "Data received and processed successfully.",
  "recordsCreated": 2
}

recordsCreated cuenta sólo los registros nuevos. Si ya existía un registro del mismo conductor y la misma fecha, se reemplaza con el que acabas de enviar y no suma al contador. Por ejemplo, si envías 3 registros y uno de ellos corresponde a un día que ya habías enviado, la respuesta será "recordsCreated": 2. Si reenvías exactamente los mismos días, la respuesta será "recordsCreated": 0.

Respuestas con error

400 — Validación

Se devuelve cuando la empresa no tiene la configuración necesaria, cuando el cuerpo no es un array válido (vacío o con más de 50 registros) o cuando uno o más registros no son válidos. Si un solo registro es inválido no se guarda ninguno: corrige los registros indicados en details y reenvía la petición completa.

{
  "error": "VALIDATION_FAILED",
  "message": "One or more records are invalid. Review details to correct and retry.",
  "details": [
    {
      "index": 0,
      "driverId": "5678",
      "date": "2025-10-19",
      "reason": "duration: Duration can't be blank"
    },
    {
      "index": 1,
      "driverId": "9999",
      "date": "2025-10-19",
      "reason": "User not found."
    }
  ]
}

Si el error es de la configuración de la empresa o del tamaño del array, details va vacío y el motivo está en message:

{
  "error": "VALIDATION_FAILED",
  "message": "Company does not have the necessary configuration.",
  "details": []
}

Campo	Tipo	Descripción
error	String	Siempre `"VALIDATION_FAILED"`.
message	String	Descripción general del error.
details	Array	Un elemento por registro inválido, ordenados por `index`. Va vacío cuando el error no es de un registro (configuración de la empresa o tamaño del array).
index	Number	Posición del registro en el array enviado (empieza en 0).
driverId	String	`driverId` del registro, o `"unknown"` si no se envió.
date	String	`date` del registro, o `"unknown"` si no se envió.
reason	String	Motivo del rechazo. Por ejemplo: un campo faltante o inválido, `"date: Invalid date format"`, `"Security event error: ..."`, `"User not found."` o `"User has invalid provider (...)"`.

401 — No autorizado

{
  "status": false,
  "error": "You are not authorized to perform this action",
  "errorId": "-1"
}

500 — Error interno

{
  "status": false,
  "message": "Error: Request could not be processed",
  "errorId": "a1b2c3d4e5f6"
}

errorId identifica el error en nuestros registros; inclúyelo si contactas a soporte. Si la petición falla con 500, no se guarda ningún registro.

Notas importantes

El endpoint acepta un array de registros, lo que permite enviar información de múltiples conductores en una sola petición. Debes enviar mínimo 1 y máximo 50 registros por llamada; si envías más de 50, la API responde con un error 400.
Los campos distance y duration son obligatorios. El campo score es opcional.
Si un conductor no tuvo eventos de seguridad en el día, envía securityEvents como un array vacío ([]). El campo no se puede omitir.
Los eventos de seguridad deben ser alguno de los eventos válidos.
La fecha debe estar en formato YYYY-MM-DD.
Si ya existe información del mismo conductor para la fecha enviada, nuestro sistema la reemplaza por completo con la nueva. Si en el reenvío no incluyes score, el puntaje anterior se borra (queda en null).

Campos​

Eventos válidos​

Headers​

Body​

Ejemplo​

Respuesta exitosa​

Respuestas con error​

400 — Validación​

401 — No autorizado​

500 — Error interno​

Notas importantes​