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)
Questo ha risposto alla sua domanda? Grazie per il feedback Si è verificato un problema nell'invio del feedback. Riprova più tardi.