Laravel — INODESK

LaravelUne balise Blade pour le widget, un appel HTTP pour les demandes ouvertes depuis votre application métier. Rien d'autre à installer.Prérequis : le site est créé dans CONTROL et ses domaines sont déclarés. Voir le README.1. Configuration

php

// config/services.php

'inodesk' => [
    // Clé PUBLIQUE : elle vit dans le HTML, c'est sa raison d'être.
    'public_key' => env('INODESK_PUBLIC_KEY'),
    // Clé SECRÈTE : serveur uniquement. Ne jamais l'exposer à une vue Blade.
    'secret'     => env('INODESK_SECRET_KEY'),
    'endpoint'   => env('INODESK_ENDPOINT', &#39;https://messagerie.inovertix.com/api/inodesk'),
    'widget'     => env('INODESK_WIDGET_URL', &#39;https://messagerie.inovertix.com/inodesk.js'),
],

dotenv

# .env
INODESK_PUBLIC_KEY=INODSK_PUB_votre_cle_publique
INODESK_SECRET_KEY=INODSK_SEC_votre_cle_secrete
INODESK_ENDPOINT=https://messagerie.inovertix.com/api/inodesk
INODESK_WIDGET_URL=https://messagerie.inovertix.com/inodesk.js

Attention

config('services.inodesk.secret') ne doit jamais apparaître dans une vue. Une clé secrète dans une page finit dans le cache du navigateur, dans les proxys, et chez le premier visiteur qui ouvre le code source.

2. Le widget

blade

{{-- resources/views/layouts/app.blade.php, juste avant </body> --}}

@if (config('services.inodesk.public_key'))
    <script src="{{ config('services.inodesk.widget') }}"
            data-site="{{ config('services.inodesk.public_key') }}"
            data-endpoint="{{ config('services.inodesk.endpoint') }}"
            defer></script>
@endif

Le @if n'est pas de la coquetterie : en préproduction ou en local, la clé est souvent absente. Sans lui, la balise serait rendue avec data-site="" et le widget enverrait une requête vouée à échouer à chaque page.Ouvrir le widget depuis un bouton à vous

blade

<button type="button" onclick="window.inodesk && window.inodesk('open', 'support')">
    Nous contacter
</button>

Formulaire intégré dans une page

blade

<div id="contact-form" data-inodesk-form="contact"></div>

Le widget remplit lui-même le conteneur avec le formulaire déclaré dans CONTROL, dans son propre shadow DOM. Aucune définition de formulaire à maintenir de votre côté.3. Ouvrir une demande depuis votre serveurCas typique : un paiement échoue, une livraison est en retard, un utilisateur signale un problème depuis son espace connecté. Vous avez déjà le contexte — ne le faites pas ressaisir.

php

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

/**
 * Ouverture d'une demande INODESK depuis l'application.
 *
 * DEUX RÈGLES qui expliquent tout le code ci-dessous :
 *
 *   1. TIMEOUT COURT. Ouvrir une demande accompagne une action de l'utilisateur ; ça
 *      ne doit jamais la faire attendre. Quatre secondes au total, une pour établir
 *      la connexion.
 *
 *   2. ÉCHEC NON BLOQUANT. Si CONTROL est indisponible, l'utilisateur ne doit pas en
 *      subir les conséquences : on journalise et on rend la main. Une demande perdue
 *      est un incident ; une commande perdue parce que le service client était
 *      injoignable en est un autre, bien plus cher.
 */
class InoDeskClient
{
    /**
     * @param  array{name?: string, email?: string, phone?: string, city?: string}  $contact
     * @return array{reference: string, track_url: string}|null
     */
    public function ouvrirDemande(
        string $sujet,
        string $message,
        array $contact,
        string $priorite = 'normale',
    ): ?array {
        $endpoint = config('services.inodesk.endpoint');
        $secret = config('services.inodesk.secret');

        if (blank($endpoint) || blank($secret)) {
            Log::warning('INODESK non configuré : demande non transmise.');

            return null;
        }

        try {
            $response = Http::withToken($secret)
                ->connectTimeout(1)
                ->timeout(4)
                ->acceptJson()
                ->asJson()
                ->post("{$endpoint}/tickets", [
                    'subject'  => $sujet,
                    'message'  => $message,
                    'contact'  => $contact,
                    'priority' => $priorite,
                ]);
        } catch (\Throwable $e) {
            Log::warning('INODESK injoignable : '.$e->getMessage());

            return null;
        }

        if ($response->failed()) {
            // Le corps porte {statusCode, name, message} : `name` suffit au diagnostic
            // et n'expose aucune donnée personnelle dans les journaux.
            Log::warning('INODESK a refusé la demande : '.$response->json('name'));

            return null;
        }

        return [
            'reference' => (string) $response->json('reference'),
            // `track_url` n'est renvoyé QU'À la clé secrète. Vous pouvez l'afficher à
            // l'utilisateur CONCERNÉ ; ne le stockez pas dans un endroit partagé.
            'track_url' => (string) $response->json('track_url'),
        ];
    }
}

Utilisation

php

$demande = app(InoDeskClient::class)->ouvrirDemande(
    sujet: "Commande {$commande->reference} non reçue",
    message: "Le client signale un retard de livraison depuis son espace.",
    contact: [
        'name'  => $commande->client_nom,
        'email' => $commande->client_email,
        'phone' => $commande->client_telephone,
        'city'  => $commande->ville,
    ],
    priorite: 'haute',
);

if ($demande !== null) {
    session()->flash('info', "Votre demande {$demande['reference']} est enregistrée.");
}

En file d'attente (recommandé pour les volumes)

php

// app/Jobs/OuvrirDemandeInoDesk.php
public function handle(InoDeskClient $client): void
{
    $client->ouvrirDemande($this->sujet, $this->message, $this->contact);
}

La file rend l'échec rejouable : un CONTROL indisponible cinq minutes ne fait perdre aucune demande, elle repart au prochain essai.4. Envoyer une soumission de formulaire (plutôt qu'une demande)Si vous avez déjà un formulaire Laravel et voulez que son contenu arrive dans INODESK comme n'importe quelle soumission — champ par champ, avec le formulaire déclaré dans CONTROL :

php

Http::withToken(config('services.inodesk.secret'))
    ->timeout(4)
    ->post(config('services.inodesk.endpoint').'/submissions', [
        'form_slug' => 'contact',
        'data' => [
            'name'    => $request->input('nom'),
            'email'   => $request->input('email'),
            'phone'   => $request->input('telephone'),
            'message' => $request->input('message'),
        ],
        'source_url' => $request->url(),
    ]);

La réponse est 202 dans tous les cas exploitables, y compris quand la soumission est classée en spam. Les suspectes sont rangées dans le dossier « Spam » de l'inbox et restaurables d'un clic — jamais refusées.5. Avis et suivi de commandeLe mur d'avisLe plus simple, une balise dans une vue :

blade

<div data-inodesk-reviews
     data-site="{{ config('services.inodesk.public_key') }}"
     data-endpoint="{{ config('services.inodesk.endpoint') }}"
     data-mode="wall"></div>

<script src="{{ str_replace('inodesk.js', 'inodesk-reviews.js', config('services.inodesk.widget')) }}"
        defer></script>

Fichier séparé du widget (~4 Ko) : une page « Ils nous ont fait confiance » n'a aucune raison de télécharger le panneau de contact complet. data-mode="badge" n'affiche que la note, data-limit="6" borne le nombre d'avis. Zéro avis publié → le bloc n'affiche rien.Seuls les avis publiés dans CONTROL apparaissent. La modération est obligatoire : rien ne se publie sans une action humaine, quelle que soit la note.Si vous voulez être référencé sur vos avisAlors le mur doit être rendu côté serveur, JSON-LD compris. Un balisage injecté en JavaScript est lu de façon inégale par les moteurs — c'est précisément pourquoi inodesk-reviews.js n'en pose aucun.

php

// Clé PUBLIQUE : cet endpoint ne rend que du contenu déjà public.
$data = Cache::remember('inodesk.reviews', 300, function () {
    $res = Http::timeout(5)->get(config('services.inodesk.endpoint').'/reviews', [
        'k' => config('services.inodesk.public_key'),
    ]);

    // null en cas d'échec : la page s'affiche sans balisage plutôt que de planter.
    return $res->successful() ? $res->json() : null;
});

Le service complet (classe, JSON-LD, vue Blade) est dans avis-seo.md. Respectez le Cache-Control: max-age=300 de l'API : un mur d'avis n'a pas besoin d'être frais à la seconde.

La solution sans travail : lier /care/{votre-site}/avis, déjà brandée, balisée et indexable.

Suivi de commande depuis votre propre formulaire

php

$res = Http::timeout(5)->post(
    config('services.inodesk.endpoint').'/order-lookup?k='.config('services.inodesk.public_key'),
    ['order_number' => $request->input('numero'), 'phone' => $request->input('telephone')],
);

if (! $res->successful()) {
    // ⚠️ Le message du serveur, TEL QUEL. Il est identique pour toutes les causes
    // d'échec — numéro inconnu, téléphone faux, IP verrouillée. Le préciser
    // transformerait cette route en confirmateur de commandes.
    return back()->withErrors(['numero' => $res->json('message')]);
}

$order = $res->json('order'); // number, status, status_label, placed_at, total, currency, city

Deux réflexes :

Ne pas enrichir le message d'échec ni distinguer les causes.

Ne pas ajouter de latence conditionnelle. Le serveur applique déjà un plancher de temps de réponse ; un sleep() côté application le réduirait à néant.

DevisRien à intégrer : le pipeline vit dans CONTROL. Une soumission d'un formulaire de type devis crée le devis, l'équipe l'édite et l'envoie, et le client décide sur /q/{token}. Votre site n'a qu'à laisser passer la demande — par le widget, par le portail, ou par POST /submissions comme ci-dessus.Checklist de recette

curl -sS "$INODESK_ENDPOINT/ping?k=$INODESK_PUBLIC_KEY" répond {"ok":true,…}.

La bulle s'affiche sur le front, aux couleurs configurées dans CONTROL.

grep -r "INODSK_SEC_" public/ et le HTML rendu ne renvoient rien.

Une soumission de test arrive dans l'inbox avec son numéro.

Le contact reçoit son accusé de réception et son lien de suivi.

Test d'indisponibilité : arrêter CONTROL, refaire le parcours métier — il doit se dérouler normalement, avec seulement une ligne dans les journaux.

php artisan config:cache puis rechargement : la clé est toujours lue.

Sur téléphone : panneau plein écran, formulaire utilisable.

data-inodesk-reviews affiche la note dès qu'un avis est publié, et rien avant.

Si le SEO est visé : le HTML source contient le application/ld+json, et la note balisée est celle affichée.

Le cache d'avis (Cache::remember, 300 s) expire bien, et la page reste lisible quand CONTROL est arrêté.

Suivi de commande : un couple faux renvoie exactement le même message et le même délai qu'un numéro inconnu.

Dépannage

Symptôme	Cause la plus fréquente
Bulle absente	`INODESK_PUBLIC_KEY` vide → le `@if` du gabarit n'a rien rendu
`/config` en 403 `origin_not_allowed`	Le domaine exact n'est pas déclaré (schéma, `www`, port)
`401 secret_key_in_url`	Une clé secrète a été passée en `?k=` : utiliser `Http::withToken()`
`403 secret_key_required`	Route serveur appelée avec la clé publique
`422 unknown_form`	`form_slug` inconnu ou formulaire désactivé
Rien ne part après un déploiement	`php artisan config:clear` : l'ancienne config était en cache
Latence sur une page métier	Le timeout est trop long, ou l'appel n'est pas en file d'attente
Mur d'avis vide	Aucun avis publié (modération obligatoire), ou collecte fermée sur le site
Étoiles absentes des résultats Google	Balisage posé en JavaScript : le rendre côté serveur (avis-seo.md)
Le mur d'avis ne se met plus à jour	`Cache::remember` sans expiration, ou cache d'application non vidé
Suivi de commande toujours en échec	Le téléphone doit être celui de la commande ; après une dizaine d'essais ratés, l'IP est écartée une trentaine de minutes — avec le même message

Les codes d'erreur complets sont dans le tableau du README.