Utilizzo

Funzionamento

Gli scambi di dati vengono effettuati chiamando l'URL /json con il metodo POST. Durante la chiamata, la domanda, in formato JSON, viene trasmessa al server WEB che restituisce le informazioni richieste in formato JSON. Attualmente non esiste un'implementazione di callback.

Il server WEB utilizza la tecnologia CORS (Cross-origin resource sharing) con il parametro Access-Control-Allow-Origin: * permettendo a tutti i siti di leggere i dati JSON purché autenticati a livello di server WEB

Esempio (funziona sul nostro sito di test): 

var IdentificationJson = {
    "status":0,
    "idErreur":0,
    "idSite": "AuthentificationBaseTest",
    "type":1,
    "email":"test1@heitzsystem.com",
    "code":"1",
    "idSession":0,
    "idClient":0
};

function SendIdentification(){
    $.ajax({
        type: "POST",
        dataType: "json",
        url: 'http://heitz.no-ip.com/json',
        data: IdentificationJson,
        dataType: "json",
        success:function(data){
        console.log(data);
        }
    });
}

Nomi dei parametr

Secondo lo standard JSON-RPC (6.5. Sensibilità alle maiuscole e ai nomi dei parametri), i nomi dei parametri sono sensibili alle maiuscole e minuscole. Per esempio, il parametro idSite è diverso dal parametro IDSITE quindi bisogna fare attenzione a come viene generato il file JSON.

Nei file scambiati è stata fatta la seguente scelta: la prima parola è completamente in minuscolo e le seguenti parole hanno una lettera maiuscola solo sul primo carattere. Inoltre, i parametri non hanno un accento. Esempio: idSite, type, idClient, first name,.....

Dopo diverse richieste la lingua dei parametri è diventata l'inglese, per cui alcune funzioni avranno parametri in francese (vecchi parametri) e inglese (nuovi parametri). Tutte le nuove funzioni sono completamente in inglese.

Tipo di campi

<Chaine[Longueur]>: : stringa di caratteri incorniciata da". Se il parametro [length] è specificato, la stringa sarà troncata a questa lunghezza una volta inserita nella base. Forse no. I dati sono inviati in UTF8.

<Entier>: intero. Non può essere NULL.

<Décimal>: numero decimale. Non può essere NULL

<Date courte>: data in formato gg-mm-aaaaaaa incorniciata da". Forse no.

<Date complète>: data in formato gd-mm-yyyyyyyyyy hh🇲🇲ss incorniciato da". Forse no.

<True/False>: Valore booleano. Non può essere NULL.

Intestazione

Quando si inviano (domanda) o ricevono (rispondono) dati, viene inviata un'intestazione comune.

Intestazione

{
    "idSite":<Chaine>,      stringa di identificazione del sitoper accedere ai file JSON.
    "idSession":<Chaine>,   , ID sessione corrente (GUID).
    "idClient":<Entier>,    ID cliente.
    "type":<Entier>,        Tipo di dati richiesti/invio.
    "nombreLigne":<Entier>  (opzionale) Numero di righe da restituire.

    <Altri parametri di interrogazione se necessario>

}

Rispondi all'intestazione OK

{
"status":"ok",          indica che la risposta è corretta.
"idErreur":0,
"idSite":null,          Stored per compatibilità sarà presto cancellato. 
"idSession":<Chaine>,   ID sessione corrente (GUID).
"idClient":<Entier>,    ID cliente. 
"type":<Entier>,        Tipo di dati richiesti/invio.

<Altri parametri di risposta se necessario>

}

Intestazione di risposta ERROR

{       
"status":"ko",          Indica che si è verificato un errore..
"idErreur":<Entier>,    ID dell'errore riscontrato. (Vedi fine della documentazione).
"idSite":null,          Stored per compatibilità sarà presto cancellato. 
"idSession":<Chaine>,   ID sessione corrente (GUID)
"idClient":<Entier>,    ID cliente.
"type":<Entier>         Tipo di dati richiesti/invio.
}

Compatibilità con la versione precedente

Per mantenere la compatibilità con la versione precedente, le funzioni comuni possono essere chiamate sia con la vecchia numerazione (da 1 a 502) o con la nuova numerazione, cioè aggiungendo 20000 alla vecchia numerazione

Si consiglia di utilizzare la nuova numerazione per sviluppi futuri o per aggiornare le chiamate.

Gestione delle sessioni

Le sessioni possono essere permanenti, un client può avere diverse sessioni (telefono, tablet, computer, computer,....).

La sequenza delle chiamate deve essere la seguente:

Funzione 21009: Convalida della sessione. Il parametro IDSESSION contiene il valore della vecchia sessione se ne avete una, altrimenti usate direttamente la funzione di identificazione.

Se la funzione forward OK se la sessione è stata trovata e le impostazioni del client sono state caricate

Se la funzione di ritorno di KO (Errore #116), la sessione non è stata trovata ed è necessario utilizzare la IDSESSIONE fornita nella risposta per identificare il client.

Funzione 20001: Identificazione in caso di mancata convalida.

Il funzionamento è lo stesso per le altre funzioni.

Funzione 20402: Disconnessione. Questa funzione non è obbligatoria, ma se la si utilizza si cancellerà la sessione registrata e il client dovrà effettuare nuovamente il login la prossima volta che si connette.