Introduction

Bienvenue sur la documentation de SIMAX Template API Action.

Il s'agit d'une mini architecture PHP qui permet de configurer rapidement des points d'entrée (url) pour des actions SIMAX.

Il suffit de spécifier les informations nécessaires dans le fichier de configuration config.php.

Pré-requis

• PHP >= 7.4
• Extension soap : nécessaire pour faire les appels à SIMAXOnline
• Apache mod_rewrite : permet de configurer plusieurs points d'entrée sans avoir à coper le système de fichier en différent endroit.

Limite de connexion au niveau du SIMAXOnline

Attention, le nombre d'ouvertures de session réussies est limité :

• Global (tout confondu) : 300 / min
• Par IP complète : 25 / min
• Par groupe d'IP (masque 255.255.255.0) : 100 / min
• Par association IP / Utilisateur SIMAX : 5 / min

Ces limites sont à prendre en compte dans le cadre d'un traitement automatique.

Sources

Un zip contenant le PHP ainsi qu'un fichier de configuration et un .htaccess d'exemple est disponible :

• SIMAXTemplateAPIAction.zip

Fichiers de configuration

Configuration des informations pour la connexion à SIMAXOnline

fichier de configuration minimal :

<?php
$noutonline = [
    /*-----------------------*/
    /* utilisateur qui execute l'action */
    'username' => 'superviseur',

    /*-----------------------*/
    /* mot de passe de l'utilisateur */
    'password' => '',
    /* adresse ip ou nom dns du SIMAXOnline (si vide, par défaut dans le client 127.0.0.1) */
    'host'     => '127.0.0.1',
    /* port du SIMAXOnline (si vide, par défaut dans le client : 8052)  */
    'port'     => 8052,

    /*-----------------------*/
    /* le uuid du SIMAXOnline  */
    'apiuuid' => '568ee55e-e2b6-4566-bfa8-82a3b05ff253',
];

La configuration des informations de connexion à SIMAXOnline est faite via le fichier noutonline.php. Ce fichier consiste en un tableau avec différentes clés.

Configuration du/des enpoint(s)

fichier de configuration minimal :

<?php
$config = [
    /* identifiant unique de l'action a executer */
    'idaction' => '',
 ];

La configuration du/des enpoint(s) est faite via le fichier config.php. Ce fichier consiste en un tableau avec différentes clés.

Les fichiers config.php.single_endpoint.dist et config.php.multiple_endpoints.dist sont fournis à titre d'exemple.

Ils correspondent à 2 cas d'usages : * config.php.single_endpoint.dist : l'url n'expose qu'une unique action possible, * config.php.multiple_endpoints.dist : l'url de base expose plusieurs actions possibles.

Cas particulier des endpoints multiples

Exemple de surcharge :

<?php
$config = [
    'apikey' => 'xxxxxxxx',
    ...
    'endpoints' => [
        [
            're' => '/^campagnemarketing\/desabonnement(?:\.php)?/',
            'username' => 'script', //utilise l'utilisateur script au lieu de superviseur
            'apikey' => '', //obligatoire pour faire sauter l'api key car on est sur url publique
        ],
    ]
 ];

Dans ce cas d'usage, si une clé n'existe pas dans la configuration du endpoint, mais qu'elle existe dans la racine de la configuration, c'est la valeur de cette dernière qui est utilisée.

Description des clés du fichier de configuration

Les clés possibles pour le fichier de configuration sont :

Informations de connexion

Toutes les clés de connexion peuvent être surchargées dans le fichier config.php

username (obligatoire)

<?php
$config = [
    'username' => 'superviseur',
    ...
 ];

Le pseudo de l'utilisateur SIMAX à utiliser.

password (obligatoire)

<?php
$config = [
    'password' => 'xxxx',
    ...
 ];

Le mot de passe de l'utilisateur SIMAX utilisé.

host (optionnel)

<?php
$config = [
    'host' => '127.0.0.1',
    ...
 ];

L'adresse IP ou nom dns du SIMAXOnline.

Peut-être absent, vide ou null, dans ce cas vaut 127.0.0.1.

port (optionnel)

<?php
$config = [
    'host' => 8052,
    ...
 ];

Numéro de port du SIMAXOnline.

Peut-être absent, vide ou null, dans ce cas vaut 8052.

apiuuid (optionnel)

<?php
$config = [
    'apiuuid' => '568ee55e-e2b6-4566-bfa8-82a3b05ff253',
    ...
 ];

Identifiant de l'application utilisée pour la vérification des accès aux webservices comme configuré dans le site d'administration du SIMAXOnline (section WebService > Application SOAP/REST).

Peut-être absent, vide ou null, dans ce cas, aucune clé n'est envoyé à SIMAXOnline.

Configuration des endpoints

Clés utiles pour la configuration du/des endpoint(s).

with_log (optionnel)

<?php
$config = [
    'with_log' => true,
    ...
 ];

Exceptionnellement, cette clé n'est pas être surchargée.

Cette clé permet d'activer un historique automatique. Pour que ce dernier puisse fonctionner, il faut importer le SMX Default Action for API Template.smx présent de zip et donner les droits sur le module API Template aux utilisateurs qui font les actions.

L'historique des appels est généré dans le formulaire Historique appel API Template SIMAX.

Peut-être absent, dans ce cas vaut false.

apikey (optionnel)

<?php
$config = [
    'apikey' => 'xxxx-yyyy-zzzz',
    // ou
    'apikey' => function($debug){
        //tester des trucs à partir de $_GET et $_POST
        return true;
    },
    ...
 ];

Système de sécurité du point d'entrée.

Peut-être absent, vide ou null, dans ce cas aucune vérification par rapport à la requête n'est effectuée.

Dans la forme la plus simple, une chaîne dont la valeur doit correspondre à la valeur de l'entête HTTP x-api-key de la requête.

Ce paramètre accepte aussi une fonction en paramètre function($debug) pour une vérification de sécurité différente.

Voir plus bas pour la description des paramètres de la fonction.

idaction (obligatoire)

<?php
$config = [
    'idaction' => '1234785124131',
    ...
 ];

L'identifiant base 10 de l'action SIMAX à lancer.

Ce dernier peut-être récupérer depuis l'action dans SIMAX, clic droit copier l'identifiant unique sur le bandeau de titre de l'action en mode superviseur.

typeaction (optionnel)

<?php
$config = [
    'typeaction' => 'decl',
    ...
 ];

Type d'action SIMAX. Les valeurs suivantes sont acceptées :

• decl (par défaut): l'action est un déclenchement d'automatisme
• aff : l'action est une consultation/affichage

Peut-être absent, vide ou null, dans ce cas vaut decl.

params (optionnel)

<?php
//à calculer en fonction de $_GET, $_POST, $_FILES et php://input
$config = [
    'params' => [
        'idparam1' => $_GET['param1'],
    ],
    //ou
    'params' => function($client, $mode_debug, $debug) { 
        return [
            'idparam1' => $_POST['param1'],
        ]; 
    }
    ...
 ];

Les paramètres de l'action.

Peut-être absent, vide ou null, dans ce cas vaut [].

La fonction function($client, $mode_debug, $debug) permet de faire un calcul complexe des paramètres en fonction de la requête.

Voir plus bas pour la description des paramètres de la fonction.

Pour récupérer le body d'un POST : @file_get_contents('php://input')

transforme_retour (optionnel)

<?php
$config = [
    'transforme_retour' => function($ret) { 
        return json_decode((string)$ret->id_35523345582676->id_213013379439119->id_212385824601317); 
    }
    ...
 ];

Peut-être absent ou null.

Fonction function($ret) pour transformer le retour retourné par SIMAXOnline de manière à le faire correspondre au format attendu par le requérant. Doit retourner une valeur qui peut être encodée en JSON.

En mode aff, $ret est de type \SimpleXMLElement, et le contenu dépend du paramétrage.

En mode decl, $ret dépend du message de compte rendu de l'automatisme.

Voir plus bas pour la description des paramètres de la fonction.

envoi_retour (optionnel)

<?php
$config = [
    'envoi_retour' => function($rep) { 
        $url='./toto.html';
        header('location: '.$url); 
    }
    ...
 ];

Peut-être absent ou null.

Fonction function($rep) pour gérer le retour de manière plus globale, ie ne pas renvoyer du JSON ; par exemple faire une redirection.

Voir plus bas pour la description des paramètres de la fonction.

on_cnx_exception (optionnel)

<?php
$config = [
    'on_cnx_exception' => function($rep, $e) { 
        return false; 
    },
    ...
 ];

Peut-être absent ou null.

Fonction function($rep, $e) pour surcharger le comportement par défaut sur erreur à la connexion.

Si la fonction renvoit true, alors c'est la fonction qui fait l'affichage, false alors la fonction ne fait que modifier l'objet $rep.

Voir plus bas pour la description des paramètres de la fonction.

on_action_exception (optionnel)

<?php
$config = [
    'on_action_exception' => function($rep, $e) { 
        return false; 
    },
    ...
 ];

Peut-être absent ou null.

Fonction function($rep, $e) pour surcharger le comportement par défaut sur erreur lors de l'action.

Si la fonction renvoi true, alors c'est la fonction qui fait l'affichage, si la fonction renvoi false, alors la fonction ne fait que modifier l'objet $rep.

Voir plus bas pour la description des paramètres de la fonction.

404 (optionnel)

<?php
$config = [
    '404'      => __DIR__.'/404.html',
    /* ou */
    '404'      => function(){ 

    },
    ...
 ];

Utile dans le cas de multiples points d'entrées. Permet de personnaliser le retour quand l'url ne correspond à aucune expression régulière.

Multiples points d'entrées

Pour configurer plusieurs points d'entrée sur la même configuration (ie: le même chemin de base), il faut activer le module Rewrite d'Apache et créer un .htaccess qui va bien.

Pour utiliser multiple point d'entrée :

<IfModule mod_rewrite.c>
    RewriteEngine Off
    RewriteBase /custom-api
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^(.*)$ ./index.php?$1 [QSA,L]
</IfModule>

Pensez à remplacer /custom-api par le bon nom de chemin.

Le zip contient un .htaccess.dist d'exemple.

Il faut le renommer en .htaccess

Et configurer les points d'entrée dans la clé endpoints

endpoints (optionnel)

<?php
$config = [
     'endpoints' => [
        [
            're' => '/^bundle\/prod(?:\.php)?$/',
            'idaction' => '219331022079373',
            'typeaction' => 'aff',
            'transforme_retour' => function($matches, $ret) { return json_decode((string)$ret->id_35523345582676->id_213013379439119->id_212385824601317); },
        ],
        ...
    ]
    ...
 ];

Tableau de tableau de configuration avec les mêmes clés que la configuration globale, avec en plus une nouvelle clé : re.

Si dans la déclaration d'un point d'entrée, une clé manque, alors c'est la clé générale qui est prise en compte si elle existe ; attention donc à surcharger si vous enlever/changer le comportement global.

La signature des functions est légèrement différente, les fonctions prennent le paramètres $matches en premier paramètre en plus des paramètres normaux.

re (obligatoire)

<?php
$config = [
     'endpoints' => [
        [
            're' => '/^bundle\/prod(?:\.php)?$/',
            ...
        ],
        ...
    ]
    ...
 ];

Il s'agit de l'expression régulière qui permet différentier les points d'entrée.

Dans l'exemple, les urls suivantes sont acceptées :

• https://masociete.fr/custom-api/bundle/prod.php
• https://masociete.fr/custom-api/bundle/prod

Descriptions des paramètres des fonctions

$debug

Instance de la classe NOUT\DebugTrace.

Les méthodes suivantes sont disponibles :

• startTrace
• endTrace
• writeTrace($trace) : $trace chaine à écrire dans le log

L'écriture dans le log ne se fait quand mode debug.

$mode_debug

booléen qui indique si on est en mode debug ou pas

$client

Instance du client, la classe exacte dépend du type de l'action.

Aucune méthode publique n'est vraiment disponible. À manipuler avec précaution.

$ret

Paramètre de transforme_retour.

action de type déclenchement d'automatisme

Il s'agit du contenu du compte rendu de l'automatisme. Le contenu attendu doit être du JSON.

$ret est un objet PHP correspondant au json.

action de type affichage

$ret est un \SimpleXMLElement qui décrit la fiche affichée.

$rep

Paramètre de envoi_retour, on_cnx_exception, on_action_exception.

Objet PHP

• vide lors de on_action_exception et on_action_exception
• avec le status et result dans envoi_retour

$matches

Pour les fonctions des points d'entrée avec expression régulière.

Contient le résultat des captures de l'expression régulière.

Mode debug

Pour activer le mode debug, il faut soit :

• modifier index.php et changer la valeur de DEBUG_MODE en true,
• créer le fichier active_debug.txt, ce dernier peu être vide.

Attention, le mode debug ne doit pas être actif en permanence.

Codes d'erreur spécifiques

Quelques exemples

vérification par signature (webhook woocommerce) : apikey

<?php
function($matches, $debug){

    $headers = getallheaders();
    $computed=null;
    $signature=$headers['X-Wc-Webhook-Signature'] ?? false;
    if ($signature)
    {
        $secret = "qlmdfoprtksd,qlsfazthksdlmskdqjrgiu645f3qsdf13qf1";

        $computed = base64_encode(hash_hmac('sha256', @file_get_contents('php://input'), $secret, true));

        /** @var \NOUT\DebugTrace $debug */
        $debug->writeTrace(print_r(['signature'=>$signature, 'computed'=>$computed], true));

        if ($computed == $signature){
            return true;
        }
    }

    $debug->writeTrace(!$signature ? 'pas de signature présente' : 'signature non equal');
    $debug->endTrace();

    http_response_code (200);
    $rep    = new \stdClass();
    $rep->status = 'error';
    $rep->error = 3;
    $rep->msg = 'not allowed';

    if ($debug->isActive()){
        $rep->debug = new \stdClass();
        $rep->debug->headers = $headers;
        $rep->debug->headers_found = $signature;
        $rep->debug->computed = $computed;
    }
    return false;
}

Exemple pour vérifier la signature d'un webhook woocommerce.

Le SMX qui correspond à l'action de la description du endpoint dans le fichier d'exemple config.php.multiple_endpoints.dist est présent dans le zip (webhook woocommerce.smx).

Affichage d'html sur erreur à la connexion : on_cnx_exception

<?php
function($rep, $e){
    $html_err_cnx=<<<EOM
<html>
<head>
<title>Debut saisie Err</title>
<link rel="stylesheet" href="https://pro.fontawesome.com/releases/v5.10.0/css/all.css" integrity="sha384-AYmEC3Yw5cVb3ZcuHtOA93w35dYTsvhLPVnYs9eStHfGJvOvKxVfELGroGkvsg+p" crossorigin="anonymous"/>
</head>
<body style="color: #dc3545;">
<i class="fas fa-exclamation-triangle fa-10x"></i>
<h2>Impossible de se connecter. Demander à quelqu'un d'autre de se déconnecter ou réessayer plus tard.</h2>
</body>
</html>
EOM;

    echo $html_err_cnx;
    return true;
}

Pour afficher un html sur l'erreur à la connexion, on génère le html à la volée et on l'affiche en retournant true pour cours-circuiter le retour par défaut de l'api.

Point d'entrée pour une action de déclenchement d'automatisme avec un unique paramètre qui prend le contenu de la requête POST

<?php
     //demande de creation de commande
[
    're' => '/^command\/create(?:\.php)?$/',
    'idaction' => '222638553247369', 
    'params' => function($matches, $client, $mode_debug, $debug){
        return [
            '219112414026221' => @file_get_contents('php://input'), //json
        ];
    },
],

L'url est <url de base>/command/create pour un POST donc le contenu est un JSON.