Documentation de L'api Ogust V2

Description

L'API Ogust est un Webservice qui permet aux clients d'interfacer leurs solutions au Logiciel Ogust. L'accès au Webservice nécessite une clé publique (ou clé web) et une clé de cryptage (ou clé privée).

Les technologies employées reposent sur des protocoles ouverts et répandus :

• HTTP / HTTPS (http://tools.ietf.org/html/rfc2617)
• JSON (http://tools.ietf.org/html/rfc4627, http://www.json.org)
• HMAC, SHA1 (http://tools.ietf.org/html/rfc2104)
• CURL (http://curl.haxx.se/, http://php.net/manual/fr/ref.curl.php)

Principe de fonctionnement

Dans cette Api, un certain nombre d'objets sont à disposition. Ces objets sont listés dans le menu à gauche de cette fenêtre et décrit plus bas. Pour chacun de ces objets, jusqu'à 4 méthodes peuvent être utilisées :

• get : Méthode de lecture. Cette méthode permettra de lire les informations d'un objet. Elle retournera la liste des paramètres définissant l'objet (clé : valeur)
• set : Méthode d'écriture. Cette méthode permettra de modifier les informations d'un objet ou de créer un nouvel objet. Elle retournera l'identifiant interne de l'objet créé ou mis à jour.
• rem : Méthode de suppression. Cette méthode permettra de supprimer un objet en lui passant en paramètre son identifiant interne.
• search : Méthode de recherche. Cette méthode permettra d'effectuer une recherche d'objet dans l'ensemble de la base de donnée.
  Cette méthode intègre une notion de pagination. En plus des paramètres de l'objet, elle pourra prendre en entrée 2 paramètres particuliers supplémentaires : nbperpage qui permet de définir combien de résultats doivent être retournés par appel (par défaut 20) et pagenum qui permet de définir quelle page retourner (par défaut 1).
  Cette méthode retournera un tableau d'objets en fonction des critères de recherche. En plus de ce tableau, elle renverra les informations de pagination dans un tableau qui aura comme clé pagination et qui contiendra 3 valeurs : nbperpage, pagenum et count (nombre total d'objets correspondants aux critères de recherche)

Mode de fonctionnement

Les appels à l'api devront se faire avec l'url https://api.ogust.com/api/v2/apiogust.php?method=NOM_DE_LA_METHODE où "NOM_DE_LA_METHODE" sera composé d'un préfixe (get, set, rem ou search) suivi du nom de l'objet (Customer, Employee, ...).
Le passage des paramètres devra se faire en POST (via curl par exemple. C'est en tout cas la méthode que nous recommandons et que nous présenterons dans nos exemples).
Pour tous les appels à une méthode, à l'exception de la méthode getToken, il faudra, en plus des autres paramètres, envoyer un paramètre avec comme clé token et comme valeur le numéro que vous aurez préalablement récupéré en appelant la méthode getToken
Toutes les méthodes renverront des données au format JSON.

La première chose a faire pour utiliser l'API est donc de récupérer un token. Pour cela il faudra utiliser la méthode getToken. Une fois récupéré, un token a une durée de vie de 10 minutes et peut être utilisé autant de fois que nécessaire durant ce laps de temps.
Voici un exemple de code permettant de récupérer un numéro de token en PHP

		Génération d'un token		$apiUrl = "https://api.ogust.com/api/v2/apiogust.php?method=";
$publicKey = '01234567890123456789'; // Clé publique que vous pouvez récupérer dans la fiche société de votre compte Ogust
$privateKey = '0123456789ABCDEF'; // Clé privée que vous pouvez récupérer dans la fiche société de votre compte Ogust
$payload = array(
	'key' => $publicKey,
	'request' => 'GET_TOKEN',
	'time' => gmdate('YmdHis').'.'.mt_rand(100000, 999999)
);
//Ces 3 paramètres doivent être triés par ordre alphabétique
ksort( $payload );
//Génération de la signature qui permettra de vérifier votre identité
$payload['api_signature'] = strtoupper( hash_hmac('sha1', implode('+', $payload), $privateKey, false) );

$curl = curl_init($apiUrl."getToken");
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $payload);
$curl_response = curl_exec($curl);
if ($curl_response === false) {
	$info = curl_getinfo($curl);
	curl_close($curl);
	die('error occured during curl exec. Additional info: ' . var_export($info));
}
curl_close($curl);
$result = json_decode($curl_response, true, 512, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_FORCE_OBJECT);
if('OK' != $result['status']){
	die('Requete pour récupérer numéro de token échouée : '.$result['message']);
}

$token = $result['token'];

Lancement de webhook (sur option)

Un webhook est un message automatisé envoyé d'un système à un autre lorsqu'un évènement se produit.

Vous pouvez utiliser des webhooks pour envoyer des données à partir de votre compte Ogust afin de mettre à jour une application tierce.

Notez que lors de la création d'un webhook, l'application destinataire doit accepter les demandes POST et disposer d'une API.

Dans votre compte Ogust (Administration/Société/API), vous pouvez suivant vos droits d'accès et votre version, définir l'URL de l'application destinataire des appels webhook ainsi que les éléments déclencheurs qui sont actuellement la création ou modification des objets suivants :

• Fiche client
• Fiche intervenant
• Fiche élève
• Fiche opportunité

Les informations envoyées sur l'URL auront la forme suivante :

		$payload = array(
	'action' => $action, // Soit CREATE ou UPDATE
    'type' => $type, // Soit CLIENT, INTERVENANT, ELEVE ou OPPORTUNITE
    'id' => $id, // Numéro interne de l'objet
    'time' => $date // Date de l'action
    );
    

Il vous appartient ensuite de récupérer les nouvelles données de la fiche créée ou modifiée en utilisant la méthode API adéquate.

Exemple d'appel à une méthode

Dans l'exemple suivant, nous allons aller chercher les informations concernant un client. Pour cela, nous allons utiliser la méthode getCustomer

		Récupération des informations d'un client		$payload = array(
	'token' => $token, // On passe le numéro de token récupéré précédement
	'id_customer' => '123456' // On passe l'identifiant interne du client
);
$curl = curl_init($apiUrl.'getCustomer');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($payload));
$curl_response = curl_exec($curl);
if ($curl_response === false) {
	$info = curl_getinfo($curl);
	curl_close($curl);
	die('error occured during curl exec. Additional info: ' . var_export($info));
}
curl_close($curl);
$result = json_decode($curl_response, true, 512, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_FORCE_OBJECT);
print_r($result);

Cet exemple donnerait comme résultat :

		Retour de la méthode getCustomer
Array
(
    [status] => OK
    [customer] => Array
        (
            [id_customer] => 123456
            [mode] => 0
            [code] =>
            [type] => C
            [title] => M.
            [last_name] => TOURNIS
            [maiden_name] =>
            [first_name] => Jean
            [language] => fr-FR
            [rms_number] => 12542
            [email] => jean.tournis@ogust.com
            [landline] =>
            [mobile_phone] => 0612345678
            [fax] =>
            [skype_id] =>
            [origin] => DI
            [method_of_payment] => 900977
            [door_code] =>
            [intercom_code] =>
            [accounting_account] =>
            [sector] => 1b*
            [date_of_birth] => 19431106
            [comment] =>
            [intra_community_VAT] =>
            [company_registration_number] =>
            [legal_status] =>
            [activity] => Autre
            [manager] => 2075
            [main_address] => Array
                (
                    [id_address] => 473249
                    [line] => RUE DE LA ROSE
                    [zip] => 67000
                    [city] => STRASBOURG
                    [country] => FR
                    [type] => Adrpri
                    [id_link] => 473248
                    [third_party] => C
                )

            [billing_address] => Array
                (
                )

            [secondary_address] => Array
                (
                    [0] => Array
                        (
                            [id_address] => 58557460
                            [line] => 55 TRINITY AVENUE
                            [zip] => GA 30303
                            [city] => ATLANTA
                            [country] => US
                            [type] => AdrSec
                            [id_link] => 473248
                            [third_party] => C
                        )

                )

        )

)

List : Un objet particulier

L'objet List est un objet particulier qui mérite quelques explications complémentaires. Comme vous pourrez le constater, dans les descriptions, certains paramètres n'acceptent que des valeurs contenues dans une liste (liste de valeurs). La méthode getList (qui est la seule utilisable avec cet objet) va vous permettre de récupérer ces listes de valeurs.
getList ne prend qu'un seul paramètre en plus du token : le paramètre key. La valeur de ce paramètre doit être égale à : NOM_DE_L'OBJET.NOM_DU_CHAMP. Ainsi, par exemple, pour récupérer la liste des modes de paiement utilisables pour les clients, ce paramètre vaudra customer.method_of_payment.

Recherche avancée avec la méthode search

Par défaut, lors que l'on passe une valeur sur laquelle filtrer dans un paramètre de la méthode search, le filtre est effectué via un équivalent du pattern LIKE de mysql. Ainsi, par exemple, si vous désirez lister tous les intervenants dont le nom commence par la lettre b, il faudra passer la valeur ''b%'' au paramètre last_name lors de l'appel à la méthode.
Afin de permettre d'affiner une recherche, nous avons ajouté la possibilité d'appliquer des opérateurs particuliers lors de la recherche. Pour appliquer un opérateur, la valeur du paramètre devrat être ''@OPERATEUR|valeur''.
Voici la liste des opérateurs autorisés :

• > : Supérieur à
• >= : Supérieur ou égal à
• < : Inférieur à
• <= : Inférieur ou égal à
• = / != : Egal à / Différent de
• between : Compris entre 2 valeurs. Cette opérateur est particulier car il doit contenir 2 valeurs. Il devra être utilisé comme cela : ''@between|valeur1|valeur2''
• in / !in : Compris / non compris dans une liste de valeurs. Cette opérateur est particulier car il peux contenir 1 à n valeurs. Il devra être utilisé comme cela : "@in|valeur1|valeur2|valeur3|...|valeurN

Dans la méthode Search, il est possible de filtrer sur la majorité des champs disponibles d'un objet et sur plusieurs d'entre eux au besoin. Si vous tentez d'effectuer un filtre sur un champs qui n'est pas disponible pour les filtres, un message d'erreur sera retourné.

Descriptif de tous les objets de l'API

La suite de la documentation présentera la liste des objets implémentés dans notre API. Une recherche est disponible dans le menu à gauche de cette page.