SYGNEX GUARD / API

Documentazione API

Il connettore PHP effettua una richiesta server-to-server. Non inserire mai le chiavi in JavaScript o nel browser.

Prima della produzione: configura config/local.php, importa install_guard.sql, crea l’amministratore e verifica l’invio delle e-mail.

1. Installazione

Create il sottodominio guard.sygnexproduction.com, attivate HTTPS e impostate la radice web direttamente sulla cartella dei file Guard.
Importate install_guard.sql nel database centrale che contiene già la tabella utilisateurs.
Configurate config/local.php e impostate un token di installazione casuale di almeno 40 caratteri.
Aprite /admin/setup.php per creare il primo amministratore, poi accedete a /admin/index.php.
Create un sito nella dashboard, copiate una sola volta la chiave e il segreto API e definite i destinatari autorizzati.
Installate il connettore PHP sul server del sito sorgente. Non chiamate mai l’API dal JavaScript del browser.

2. Esempio PHP

Il connettore è autonomo e usa le funzionalità HTTPS native di PHP, senza librerie di terze parti. Riceve una risposta JSON. Il modulo deve inviare i campi dal server.

<?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.
}

Il campo website deve essere nascosto e rimanere vuoto quando viene compilato da una persona.

3. Campi accettati dall’API

Campo	Obbligatorio	Descrizione
`api_key`	Sì	Identificativo API assegnato al sito.
`api_secret`	Sì	Segreto trasmesso solo da server a server tramite HTTPS.
`site_domain`	Sì	Dominio registrato nella dashboard.
`nom_expediteur`	Sì	Nome del mittente (massimo 150 caratteri).
`email_expediteur`	Sì	Indirizzo e-mail di risposta valido.
`email_destinataire`	Sì	Deve corrispondere esattamente a un indirizzo autorizzato per questo sito.
`sujet`	Sì	Massimo 255 caratteri.
`corps_message`	Sì	Testo del messaggio (massimo 60.000 byte).
`langue`	No	fr, en, de, it, zh o vi.
`website`	No	Campo honeypot: deve rimanere vuoto.
`pieces_jointes`	No	Array JSON con name, mime e content_base64; formati e dimensioni limitati.

4. Risposte comuni

200 sent — Mittente già autorizzato; messaggio consegnato.
202 verification_required — È richiesta una verifica umana; viene inviata un’e-mail di verifica.
202 received — Risposta volutamente neutra per alcuni blocchi antispam.
401 unauthorized — Chiave API o segreto non corretti.
403 recipient_not_allowed — Destinatario non autorizzato per questo sito.
429 rate_limited / monthly_quota_exceeded — Limite di frequenza o quota mensile raggiunti.
503 service_unavailable — Configurazione, database o invio e-mail non disponibili.

5. Limiti operativi importanti

L’applicazione usa la funzione nativa mail() di PHP. Un risultato positivo non garantisce la consegna nella posta in arrivo. Verificate le condizioni di invio del provider e configurate SPF, DKIM e DMARC. I controlli MX/SPF/DMARC sono indicativi e non provano crittograficamente l’identità del dominio. Il calcolo riduce lo spam automatizzato, ma non è una protezione infallibile.

Gli allegati sono codificati in base64 e devono rispettare i limiti in config/local.php. Configurate esplicitamente i destinatari autorizzati per ogni sito; i destinatari non dichiarati vengono rifiutati.

6. Quote e monitoraggio dei consumi

I valori iniziali di riferimento sono 100 messaggi protetti al mese per il piano gratuito e 1.000 per Premium. Il piano Azienda prevede una quota personalizzata impostata manualmente. Gli amministratori possono modificare le quote. Il piano interno ignora il limite commerciale dei messaggi, ma resta soggetto alle protezioni tecniche e alle risorse dell’hosting.

Guard monitora separatamente i messaggi protetti e le e-mail in uscita effettivamente accettate da mail(). Sono previste avvertenze al 70%, 90% e 100%. Raggiunta la quota mensile, le nuove richieste vengono rifiutate fino al rinnovo mensile o alla modifica della quota. Verificate la capacità di invio con il provider prima di offrire volumi elevati.