API Pública v3
¡La API pública v3 ya está disponible! Aquí hay algunos enlaces y documentación útiles para comenzar con la nueva versión de nuestra API:
La API pública v2 todavía se puede usar en paralelo a la v3, pero tenga en cuenta que la v2 dejará de estar disponible a partir del 5 de enero de 2024. Asegúrese de haber migrado su integración a la v3 antes de esta fecha, ya que la v2 ya no funcionará. Por favor contáctenos con cualquier pregunta.
API Pública v2
Visión General
El resto de este documento describe la API pública de Tive v2.
La API de Tive proporciona una interfaz integral para administrar todos los aspectos de una cuenta de Tive. La API incluye métodos directos para leer y manipular el estado del sistema, así como para recibir notificaciones automáticas.
La API utiliza métodos REST/HTTP estándar.
Acceda a la API en la siguiente URL: https://api2.prod1.tive.co/docs
Las muestras de código están disponibles a pedido. Contáctenos para más detalles.
Seguridad y uso de API
La API de Tive utiliza una clave de API para la autenticación y la autorización. Los usuarios de la API deben pasar la clave de API para todos los métodos. La clave se pasa como un elemento de encabezado HTTP.
- Nombre del encabezado: "TiveApiKey"
Valor de encabezado: una clave de cadena proporcionada por Tive
Las operaciones comunes incluyen:
- POST: para crear nuevos objetos o invocar métodos de cambio de estado
- GET - para recuperar un solo objeto o una lista de objetos
- PUT - para actualizar el estado de un objeto
- DELETE - para eliminar un objeto
Tive usa el formato JSON (tipo de contenido - "application/json") tanto para la entrada en el cuerpo de la solicitud como para la salida.
Los valores devueltos se envuelven en un objeto de estado y se pueden recuperar desde el "resultado" de la propiedad JSON. A continuación se muestra un ejemplo de resultado de un método GET de cuenta.
{
"status": "OK",
"result": {
"id": 12345,
"name": "Tive",
"location": {
"street": "56 Roland Street",
"locality": "Boston",
"state": "Massachusetts",
"country": "US",
"zipCode": "02129"
}
}
}
Configuración API
Los principales objetos que se pueden manipular a través de la API de Tive son:
- Cuentas
- Usuarios
- Perfiles de alerta
- Dispositivos
- Envíos
A continuación, proporcionamos una breve descripción de cada uno de estos objetos. Consulte la documentación en línea de Tive para obtener más detalles.
Cuentas y Usuarios
Los métodos de la API de la cuenta proporcionan información general sobre la cuenta, como el nombre, la identificación y la ubicación de la cuenta.
Los métodos de API de usuario permiten la lectura y configuración de usuarios de cuentas. La información de contacto, como direcciones de correo electrónico y números de teléfono, que se almacena en el objeto del Usuario, se utilizan para enviar alertas de Tive a los usuarios (consulte Perfiles de alerta para obtener más detalles).
Perfiles de Alerta
Los perfiles de alerta le permiten realizar un seguimiento de los eventos de interés. Por ejemplo, puede configurar el sistema para que active un evento cuando el dispositivo experimente una temperatura alta o cuando llegue a un destino específico.
Los objetos de perfiles de alerta contienen dos secciones principales:
- El destino de los datos
- Asignados - un conjunto de usuarios a ser notificados.
- Disparadores
- Definición de las condiciones que desencadenarán un evento
Una vez configurado, se puede adjuntar un perfil de alerta a dispositivos u objetos de envío específicos. Luego monitoreará estos dispositivos y envíos para las condiciones específicas definidas dentro del Perfil de Alerta.
La API incluye un método llamado "muestra" que proporciona una lista de todos los activadores posibles y los detalles de cómo se configuran. A continuación se muestra un ejemplo que muestra un perfil de alerta que crea un disparador para eventos de choque. Para ver todas las muestras, puede usar el punto final /api/v2/alertsprofile/sample.
{
"id": 12345,
"name": "Monitor Shock Alerts",
"description": "Monitor shocks experienced by the device",
"profileType": "Device",
"assignees": [
"aaaaa-bbb-ccccc-ddddd"
],
"triggers": [
{
"id": 424,
"type": "Shock",
"name": null,
"description": null,
"isEnabled": true
}
}
Dispositivos y Envíos
Los dispositivos o “Trackers” son el principal elemento del sistema Tive que genera datos. La API del dispositivo proporciona métodos para:
- Obtener una lista de dispositivos e información sobre ellos
- Configurar el dispositivo (por ejemplo, habilitar/deshabilitar el GPS, configurar la frecuencia de transmisión de radio, etc.)
- Obtener el último estado del dispositivo
- Asociación de un perfil de alerta con un dispositivo para recibir notificaciones de alerta.
Los objetos de envío proporcionan un mecanismo para rastrear envíos reales al proporcionar el origen, el destino y la hora de un envío. Tive utiliza la información del envío para asociar eventos de alerta del dispositivo con eventos de envío específicos de la vida real, incluidas las alertas de llegada, salida y otras específicas del envío.
La API proporciona métodos para crear, eliminar, iniciar y completar envíos.
Envíos método GET
Tanto el método GET de envíos como el estado del método GET de envío realizan una consulta de búsqueda que se puede utilizar para filtrar los resultados.
Si está vacío, el método devolverá todos los objetos de envío (con limitación en el tamaño de página).
La consulta de búsqueda de envío tiene la siguiente estructura, con todos los campos opcionales.
{
States: [<shipment-state>],
ShipmentId: <shipment-id>
}
El valor del estado del envío puede ser Próximo, Activo o Completado.
Por ejemplo, para obtener envíos activos actuales:
{ States : ["Active"] }
Para obtener envíos activos y completados:
{ States : ["Active", "Completed"] }
Envíos método POST y PUT
El método PUT de envío se puede utilizar para envíos marítimos cuando se proporciona lo siguiente:
ContainerId es el formato de contenedor ISO 6346
Se debe especificar el transportista para el ContainerId; use "OTROS" si no los conoce. Póngase en contacto con el soporte para obtener una lista de todos los transportistas marítimos que apoyamos; la mayoría se proporcionan en Tive Platform al crear un nuevo envío.
Datos del Rastreador
La API de datos del rastreador le permite obtener los datos de todos los rastreadores que pertenecen a su cuenta, filtrados por nombre de rastreador y rango de tiempo.
Puede especificar uno de los dos tipos de formato de datos siguientes:
- Objeto de formato JSON, que contendrá dos secciones principales:
- Columnas: Tracker_name, Hora y lista de los sensores que especificó
- Datos: Lista de datos para los sensores seleccionados
- Formato CSV
- Contiene datos para los filtros especificados y sensores seleccionados
A continuación se muestran ejemplos que muestran los datos del rastreador en formato JSON y CSV.
Formato JSON:
{
"columns": [
"Tracker_Name",
"Time",
"Location",
"Lat",
"Lng",
"Temperature",
"Humidity",
"Pressure",
"Light",
"Motion"
],
"data": [
[
"VD0001",
"9/14/2018 2:49:02 PM",
"56 Roland Street, Boston, Massachusetts 02129, United States",
42.3983903,
-71.12880539999999,
-37.23,
50.03,
14.76,
2.14,
0
]
}
Formato CSV:
“Tracker_Name,Time,Location,Lat,Lng,Temperature,Humidity,Pressure,L
2:49:02 PM,\"56 Roland Street, Boston, Massachusetts
Comentarios
0 comentarios
Inicie sesión para dejar un comentario.