Integrazione KPI

Questo articolo è destinato al responsabile tecnico che si occupa dell'integrazione tra il sistema dell'organizzazione e Atobi.

Impostazione di una connessione

Autenticazione

Il nostro livello API utilizza gli standard OAuth 2.0. Per i fornitori di terze parti, generiamo un token "client secret", che viene poi utilizzato per autorizzare e approvare le richieste dalla piattaforma del fornitore.

Questo segreto del cliente viene generato separatamente per l'ambiente di test e per l'ambiente di produzione (forniamo questo segreto del cliente al momento dell'accordo di integrazione).

Il segreto del cliente viene quindi utilizzato per ottenere il token di accesso, che viene utilizzato in ogni richiesta per quella sessione.

Ottenere il token di accesso

To get the access token, you must send a POST request to https://{{client_name}}.erapp.dk/oauth/token with this request body:

Intestazioni

Chiave	Valore
Tipo di contenuto	applicazione/x-www-urlencodedBody

Intestazioni

Chiave	Valore	Descrizione
tipo di sovvenzione	credenziali_cliente	Campo obbligatorio
ID cliente	{{client_id}}	Fornito da Atobi, unico per ambiente.
segreto del cliente	{{client_secret}}	Fornito da Atobi, unico per ambiente.
ambito di applicazione	{{scopio}}	Campo opzionale.

IMPORTANTE: La risposta del server restituirà il token di accesso.

Invio di dati KPI (esempio di dati NumberType)

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:

Intestazioni

Chiave	Valore
Autorizzazione	Portatore {{access_token}}
Accettare	applicazione/json
Tipo di contenuto	applicazione/json

IMPORTANTE: tutte le date e i timestamp presenti nei dati devono essere forniti in formato DATETIME e devono essere forniti in Unix Epoch. Il filtraggio dei KPI nell'applicazione dipende fortemente dall'ora Unix Epoch.

Corpo

{
  "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"
        }
      ]
    }
  ]
}

IMPORTANTE: il corpo della richiesta deve essere in JSON valido.

IMPORTANTE: vedere la sezione Tipo di numero per la suddivisione delle colonne.

Campo "Tipo" (obbligatorio)

Questo campo viene utilizzato per distinguere le piattaforme specifiche di integrazione.

Campo "Versione" (obbligatorio)

Questo campo viene utilizzato per la versione dell'integrazione ai fini della retrocompatibilità.

Campo "Contesto" (obbligatorio)

Questo campo viene utilizzato per definire il contesto, che aiuta a raggruppare i dati KPI correlati. Ogni KPI unico deve avere un nome di contesto unico.

Campi "User_id" e "Location_id"

Colleghiamo i dati di vendita attraverso gli utenti o le sedi (reparti/negozi/paesi/ecc.). Quando si inviano i dati KPI, è obbligatorio fornire user_id o location_id (è possibile fornirli entrambi, se necessario).

Campo "Dati" (obbligatorio)

Questo campo è obbligatorio, ma il contenuto dipende dalla piattaforma e dal contesto. Il formato dell'oggetto all'interno dei dati è descritto quando è in uso uno specifico "tipo_di_oggetto". Per ulteriori informazioni, vedere la sezione "Tipi supportati".

Dati ricevuti ("ACK")

Se il trasferimento dei dati ha avuto successo, il codice di risposta del server dovrebbe essere 2XX con lo stato nel corpo JSON.

Dati non ricevuti

Se il codice di risposta del server non rientra nella categoria 2XX, il trasferimento deve essere contrassegnato come non riuscito.

Strozzatura API

Il limite predefinito è di 180 richieste/1 minuto. Questo limite può essere modificato.

Variabili del documento

Variabile	Tipo	Descrizione
{{client_id}}	stringa	ID univoco fornito da Atobi.
{{client_secret}}	stringa	Token segreto unico fornito da Atobi.
{{scopio}}	stringa	Descrittore dell'ambito (opzionale).
{{nome_cliente}}	stringa	Nome univoco del cliente.
{{access_token}}	stringa	Token di accesso, generato con il segreto del cliente.
{{api_version}}	stringa	Versione API (per la retrocompatibilità).
{{unique_integration_identifier}}	stringa	Identificatore di integrazione specifico. Viene fornito da Atobi.

Tipi supportati

Numero Tipo

Definisce che il valore fornito è un numero.

Formati numerici supportati

intero
galleggiante
reale
doppio

{	"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",
},

Ripartizione degli oggetti

Chiave	Richiesto	Descrizione
id	vero	ID interno dell'oggetto fornito dalla piattaforma.
kpi	vero	Identificatore KPI utilizzato per il raggruppamento.
tipo_oggetto	vero	Specifica il tipo di informazioni.
valore	vero	Il valore effettivo per il KPI, il tipo di oggetto, restituirà il valore in un formato specifico.
unità	opzionale	Campo personalizzato per le unità di misura utilizzate accanto al valore, ad esempio: %, Eur, Punti, ecc.
timestamp	vero	Formato della data: "Y-m-d H:i:s" (deve essere l'ora UNIX)
dati_da	opzionale	Formato della data: "Y-m-d H:i:s" (deve essere l'ora UNIX)
dati_a	opzionale	Formato della data: "Y-m-d H:i:s" (deve essere l'ora UNIX)