SYGNEX GUARD / API

Documentation de l’API

Le connecteur PHP effectue une requête serveur à serveur. Ne placez jamais les clés dans JavaScript ou dans le navigateur.

Avant la mise en production : renseignez config/local.php, importez install_guard.sql, créez l’administrateur et vérifiez l’envoi e-mail.

1. Installation

Créez le sous-domaine guard.sygnexproduction.com, activez HTTPS et faites pointer sa racine web directement vers les fichiers de Guard.
Importez install_guard.sql dans la base centrale qui contient déjà la table utilisateurs.
Renseignez config/local.php et définissez un jeton d’installation aléatoire d’au moins 40 caractères.
Ouvrez /admin/setup.php pour créer le premier administrateur, puis connectez-vous à /admin/index.php.
Créez un site dans le tableau de bord, copiez sa clé et son secret une seule fois et définissez ses destinataires autorisés.
Installez le connecteur PHP sur le serveur du site source. N’appelez jamais l’API depuis le JavaScript du navigateur.

2. Exemple PHP

Le connecteur est autonome et utilise les fonctionnalités HTTPS natives de PHP, sans bibliothèque tierce. Il reçoit une réponse JSON. Le formulaire doit transmettre les champs depuis le serveur.

<?php
require_once __DIR__ . '/client-sdk/sygnex-guard-connector.php';
$guard = new SygnexGuardConnector(
    'YOUR_API_KEY',
    'YOUR_API_SECRET',
    'https://guard.sygnexproduction.com/api/intercept.php',
    'www.your-site.example'
);
$result = $guard->submit([
    'nom_expediteur' => $_POST['nom'] ?? '',
    'email_expediteur' => $_POST['email'] ?? '',
    'email_destinataire' => 'contact@your-site.example',
    'sujet' => $_POST['sujet'] ?? 'Website message',
    'corps_message' => $_POST['message'] ?? '',
    'langue' => 'fr',
    'website' => $_POST['website'] ?? '', // honeypot: keep empty
]);
if (!$result['ok']) {
    // Handle service or quota errors; never expose API secrets.
}

Le champ website doit être caché et rester vide lorsqu’il est rempli par une personne.

3. Champs acceptés par l’API

Champ	Requis	Description
`api_key`	Oui	Identifiant API attribué au site.
`api_secret`	Oui	Secret transmis uniquement de serveur à serveur via HTTPS.
`site_domain`	Oui	Domaine déclaré dans le tableau de bord.
`nom_expediteur`	Oui	Nom de l’expéditeur (150 caractères maximum).
`email_expediteur`	Oui	Adresse e-mail de retour valide.
`email_destinataire`	Oui	Doit correspondre exactement à une adresse autorisée pour ce site.
`sujet`	Oui	255 caractères maximum.
`corps_message`	Oui	Texte du message (60 000 octets maximum).
`langue`	Non	fr, en, de, it, zh ou vi.
`website`	Non	Champ honeypot : doit rester vide.
`pieces_jointes`	Non	Tableau JSON name, mime et content_base64 ; formats et taille limités.

4. Réponses habituelles

200 sent — Expéditeur déjà autorisé ; message transmis.
202 verification_required — Validation humaine requise ; un e-mail de validation est envoyé.
202 received — Réponse volontairement neutre pour certains blocages anti-spam.
401 unauthorized — Clé API ou secret incorrect.
403 recipient_not_allowed — Destinataire non autorisé pour ce site.
429 rate_limited / monthly_quota_exceeded — Limite de débit ou quota mensuel atteint.
503 service_unavailable — Configuration, base de données ou envoi e-mail indisponible.

5. Limites opérationnelles importantes

L’application utilise la fonction native mail() de PHP. Le retour positif de cette fonction ne garantit pas l’arrivée en boîte principale. Vérifiez les conditions d’envoi de votre hébergeur et configurez SPF, DKIM et DMARC. Les contrôles MX/SPF/DMARC sont indicatifs et ne prouvent pas cryptographiquement l’identité d’un domaine. Le défi mathématique réduit le spam automatisé, mais ne constitue pas une protection infaillible.

Les pièces jointes sont encodées en base64 et doivent respecter les limites de config/local.php. Déclarez explicitement les destinataires autorisés pour chaque site ; Guard refuse les destinataires non déclarés.

6. Quotas et suivi de consommation

Au lancement, les valeurs de référence sont de 100 messages protégés par mois pour l’offre gratuite et 1 000 pour Premium. L’offre Entreprise utilise un quota personnalisé défini manuellement. Les quotas sont modifiables par l’administration. L’offre interne ignore le plafond commercial de messages, tout en restant soumise aux protections techniques et aux limites de ressources de l’hébergement.

Guard suit séparément les messages protégés et les e-mails sortants réellement acceptés par mail(). Des alertes sont prévues aux seuils de 70 %, 90 % et 100 %. Une fois le quota mensuel atteint, les nouvelles soumissions de l’offre concernée sont refusées jusqu’au renouvellement du mois ou à la modification du quota. Les capacités réelles d’envoi doivent être vérifiées avec l’hébergeur avant toute offre à gros volume.