SYGNEX GUARD / API

API 文档

PHP 连接器通过服务器到服务器的请求工作。切勿将密钥放入 JavaScript 或浏览器。

上线前：配置 config/local.php，导入 install_guard.sql，创建管理员并测试邮件发送。

1. 安装

创建 guard.sygnexproduction.com 子域名，启用 HTTPS，并将网站根目录直接指向 Guard 文件所在目录。
将 install_guard.sql 导入已包含 utilisateurs 表的中央数据库。
配置 config/local.php，并设置至少 40 个字符的随机安装令牌。
打开 /admin/setup.php 创建首位管理员，然后登录 /admin/index.php。
在管理面板中创建站点，只显示一次并保存 API 密钥和密钥秘密，然后设置允许的收件人。
在源网站服务器上安装 PHP 连接器。切勿从浏览器 JavaScript 调用 API。

2. PHP 示例

该连接器独立运行，使用 PHP 原生 HTTPS 功能，不依赖第三方库，并返回 JSON 响应。表单字段必须由服务器提交。

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

website 字段必须隐藏，并且由真人填写时保持为空。

3. API 接受的字段

字段	必填	说明
`api_key`	是	分配给该站点的 API 标识。
`api_secret`	是	仅通过 HTTPS 在服务器之间传输的秘密。
`site_domain`	是	在管理面板中登记的域名。
`nom_expediteur`	是	发件人姓名（最多 150 个字符）。
`email_expediteur`	是	有效的回复电子邮件地址。
`email_destinataire`	是	必须与该站点获准的收件人地址完全一致。
`sujet`	是	最多 255 个字符。
`corps_message`	是	消息正文（最多 60,000 字节）。
`langue`	否	fr、en、de、it、zh 或 vi。
`website`	否	蜜罐字段，必须保持为空。
`pieces_jointes`	否	JSON 数组，包含 name、mime 和 content_base64；格式和大小受限。

4. 常见响应

200 sent — 发件人已获授权；消息已发送。
202 verification_required — 需要人工验证；系统会发送验证邮件。
202 received — 针对某些反垃圾拦截返回有意保持中性的响应。
401 unauthorized — API 密钥或秘密不正确。
403 recipient_not_allowed — 该站点不允许此收件人。
429 rate_limited / monthly_quota_exceeded — 达到请求速率限制或月度配额。
503 service_unavailable — 配置、数据库或邮件发送服务不可用。

5. 重要运行限制

应用使用 PHP 原生 mail() 函数。函数返回成功并不保证邮件进入收件箱。请确认主机服务商的发信政策，并配置 SPF、DKIM 和 DMARC。MX/SPF/DMARC 检查仅供参考，不能以密码学方式证明域名身份。数学挑战可减少自动垃圾信息，但不是绝对可靠的防护。

附件以 base64 编码，并须遵守 config/local.php 中的大小限制。请为每个站点明确配置允许的收件人；未声明的收件人会被拒绝。

6. 配额与用量跟踪

初始参考值为免费套餐每月 100 条受保护消息，Premium 套餐每月 1,000 条。企业套餐使用管理员手动设置的自定义配额。管理员可以调整配额。内部套餐不受商业消息数量上限限制，但仍受技术防护和主机资源限制。

Guard 分别统计受保护消息和 mail() 实际接受的外发邮件。系统计划在 70%、90% 和 100% 时发出提醒。达到月度配额后，该套餐的新提交会被拒绝，直到下个月或管理员调整配额。提供大流量套餐前，请先与主机服务商确认实际发信能力。