Integración de los KPI
Este artículo está dirigido al responsable técnico que gestiona la integración entre el sistema de la organización y Atobi.
Configuración de una conexión
Autenticación
Nuestra capa API utiliza estándares OAuth 2.0. Para los proveedores externos, generamos un token "secreto de cliente", que luego se utiliza para autorizar y aprobar las solicitudes de la plataforma del proveedor.
Este secreto de cliente se genera por separado para el entorno de pruebas y el entorno de producción (proporcionamos este secreto de cliente en el acuerdo de integración).
El secreto del cliente se utiliza para obtener el token de acceso, que se utiliza en cada solicitud para esa sesión.
Obtener el token de acceso
To get the access token, you must send a POST request to https://{{client_name}}.erapp.dk/oauth/token with this request body:
Encabezados
| Clave | Valor |
| Content-Type | application/x-www-urlencodedBody |
Encabezados
| Clave | Valor | Descripción |
| grant-type | client_credentials | Campo obligatorio |
| client_id | {{client_id}} | Proporcionado por Atobi, único |
| client_secret | {{client_secret}} | Proporcionado por Atobi, único por entorno. |
| scope | {{scope} | Campo opcional. |
Envío de datos KPI (ejemplo de datos de tipo numérico)
Now when we have the access token, we are ready to send KPI data to the platform. To do so, we have to create a POST request in JSON format to https://{{client_name}}.erapp.dk/api/external/{{api_version}}/kpi:
Encabezados
| Clave | Valor |
| Authorization | Bearer {{access_token}} |
| Accept | application/json |
| Content-Type | application/json |
Cuerpo
{
"type": "{{unique_integration_identifier}}",
"version": "1.0.0",
"context": "sales",
"data": [
{
"user_id": "123",
"location_id": "321",
"elements": [
{
"id": 1,
"kpi": "device_sales",
"object_type": "number",
"value": "100",
"units": "Devices sold",
"timestamp": "2019-09-10 13:09:23",
"date_from": "2019-09-10 13:09:23",
"date_to": "2019-09-10 13:09:23"
},
{
"id": 2,
"kpi": "bonuses",
"object_type": "number",
"value": "150.00",
"units": "Bonus earned",
"timestamp": "2019-09-10 13:09:23",
"date_from": "2019-09-10 13:09:23",
"date_to": "2019-09-10 13:09:23"
}
]
},
{
"user_id": "89",
"elements": [
{
"id": 3,
"kpi": "points",
"object_type": "number",
"value": "100",
"units": "Points",
"timestamp": "2019-09-10 13:09:23",
"date_from": "2019-09-10 13:09:23",
"date_to": "2019-09-10 13:09:23"
},
{
"id": 4,
"kpi": "profit",
"object_type": "number",
"value": "250.00",
"units": "Eur",
"timestamp": "2019-09-10 13:09:23",
"date_from": "2019-09-10 13:09:23",
"date_to": "2019-09-10 13:09:23"
}
]
},
{
"location_id": "3",
"elements": [
{
"id": 5,
"kpi": "points",
"object_type": "number",
"value": "100",
"units": "Points",
"timestamp": "2019-09-10 13:09:23",
"date_from": "2019-09-10 13:09:23",
"date_to": "2019-09-10 13:09:23"
},
{
"id": 6,
"kpi": "experience",
"object_type": "number",
"value": "150.00",
"units": "Experience",
"timestamp": "2019-09-10 13:09:23",
"date_from": "2019-09-10 13:09:23",
"date_to": "2019-09-10 13:09:23"
}
]
}
]
}
Campo "Tipo" (obligatorio)
Este campo se utiliza para distinciones específicas de integración de plataformas.
Campo "Versión" (obligatorio)
Este campo se utiliza para la versión de la integración para la compatibilidad con versiones anteriores.
Campo "Contexto" (obligatorio)
Este campo se utiliza para definir el contexto, que ayuda a agrupar los datos de los KPI relacionados. Cada KPI único debe tener un nombre de contexto único.
Campos "User_id" y "Location_id"
Conectamos los datos de ventas a través de usuarios o ubicaciones (departamentos/tiendas/países/etc.).). Al enviar los datos de KPI, es obligatorio proporcionar user_id o location_id (puede proporcionar ambos si corresponde).
Campo "Datos" (obligatorio)
Este campo es obligatorio, pero el contenido depende de la plataforma y del contexto. El formato del objeto dentro de los datos se describe cuando se utiliza un "object_type" específico. Consulte la sección "Tipos compatibles" para obtener más información.
Datos recibidos ("ACK")
Si la transferencia de datos se realizó correctamente, el código de respuesta del servidor debe ser 2XX con estado en el cuerpo de JSON.
Datos no recibidos
Si el código de respuesta del servidor no está en la categoría 2XX - debe marcar la transferencia como fallida.
Estrangulamiento de la API
Por defecto, tenemos un límite de 180 solicitudes/1 minuto. Esto se puede ajustar.
Variables del documento
| Variable | Tipo | Descripción |
| {{client_id}} | cadena | ID único proporcionado por Atobi. |
| {{client_secret}} | cadena | Token secreto único proporcionado por Atobi. |
| {{scope} | cadena | Descriptor de alcance (opcional). |
| {{client_name}} | cadena | Nombre de cliente único. |
| {{access_token}} | cadena | Token de acceso, que se genera con el secreto del cliente. |
| {{api_version}} | cadena | Versión de la API (para la compatibilidad con versiones anteriores). |
| {{unique_integration_identifier}} | cadena | Identificador específico de integración. Esto lo proporciona Atobi. |
Tipos compatibles
Tipo de número
Define que el valor proporcionado es un número.
Formatos numéricos admitidos
- enteros
- float
- real
- doble
{ "id": 1,
"kpi": "points",
"object_type": "number",
"value": "100",
"units": "Points",
"timestamp": "2019-09-10 13:09:23",
"date_from": "2019-09-10 13:09:23",
"date_to": "2019-09-10 13:09:23",
},
Desglose de objetos
| Clave | Requerido | Descripción |
| id | true | ID de objeto interno proporcionado desde la plataforma. |
| kpi | true | Identificador KPI usado para agrupar. |
| tipo_de_objeto | true | Especifica el tipo de información. |
| value | true | El valor real para el KPI, tipo de objeto, arrojará el valor en un formato específico. |
| units | optional | Campo personalizado para las unidades utilizadas junto con el valor, por ejemplo: %, Eur, Points, etc. |
| timestamp | true | Formato de fecha: "Y-m-d H:i:s" (debe ser UNIX) |
| data_from | optional | Formato de fecha: "Y-m-d H:i:s" (debe ser UNIX) |
| data_to | optional | Formato de fecha: "Y-m-d H:i:s" (debe ser UNIX) |