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.
• SIMAXOnline : >= 2450

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.

Gestion des Boîtes de dialogue, des ouvertures de fiche et des demandes de paramètres

Boîtes de dialogue

Sortie avec un json retourné par l'automatisme

{
    "status": "ok",
    "result": {
        "comments": {
            "parametrage": "localhost / validator",
            "record_without_error": "force l'ouverture d'une fiche sans erreur",
            "required_column": "force une fiche avec une colonne obligatoire non remplie",
            "required_parameter": "force une demande de paramètre",
            "parameter_validation": "demande de paramètre sans erreur",
            "error_on_save": "Erreur à l'enregistrement",
            "message_box": "Affiche une message box intermédiaire yes-no ou ok"
        },
        "error_on_save": 1,
        "record_without_error": "0",
        "required_column": "0",
        "required_parameter": "0",
        "parameter_validation": "0",
        "message_box": "0"
    }
}

Erreur avec le message de la boîte de dialogue (version antérieure à la 2511.01 ou avec force_exception_on_message_box=1)

{
  "status": "error",
  "error": 101,
  "msg": "Pas de contrat cadre"
}

La gestion des boîtes de dialogue avec juste le bouton OK est particulière (généralement message de compte rendu et les messages de confirmation de type OK des automatismes). Les autres types de boîtes de dialogue provoquent une erreur et un arrêt du workflow.

Si le message de la boîte de dialogue est un objet ou tableau JSON valide, alors le json est retourné dans le retour de l'appel et la boite de dialogue est validée automatiquement.

Dans le cas du message qui n'est pas un objet ou tableau JSON Valide, la gestion a changée à partir de la version 2511.01.

Dans les anciennes version, si le message de la boîte de dialogue n'est pas un JSON valide, le script sort avec une erreur 500 avec le message de la boîte de dialogue en message et le workflow n'est pas complété.

À partir de la version 2511.01, on valide la boîte de dialogue automatiquement pour ne pas bloquer le workflow.

À partir de la version 2544.01, l'option force_exception_on_message_box est disponible pour configurer le comportement à adopter pour les boîtes de dialogue.

Demande de paramètre et ouverture de fiche

S'il s'agit d'une ouverture demandée par le paramétrage juste pour vérification des données sans controle d'état de champ, d'action ou de données obligatoires non remplies, alors le script essaye de valider la fiche automatiquement. Autrement, le script sort en erreur et le workflow est stoppé.

Si la validation échoue, alors le script sort en erreur et le workflow est stoppé.

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 / password ou token (obligatoire)

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

//ou 
$config = [
    'token' => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    ...
 ];

Pour la connexion, vous pouvez utiliser un couple identifiant/mot de passe (pour l'utilisateur SIMAX) ou, depuis la version 2544.01, un token généré dans SIMAX avec la fonction GénèreAuthToken.

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')

force_exception_on_message_box (optionnel)

Réglage du comportement pour les boîtes de dialogue (de type OK) dont le message n'est pas un objet ou tableau JSON Valide.

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.