如何通过 API 设置 SMM 面板余额自动充值

设置自动充值前需要准备什么

自动充值将 SMM 面板余额与支付服务或内部计费系统连接起来。服务会检查余额，在达到设定阈值时创建支付，并且仅在确认付款后才入账。要使其正常工作，需要面板 API 文档、支付 API 的访问权限、测试环境和生产环境的独立密钥，以及所有操作的日志。

在开发之前，请确认面板 API 是否能够返回余额、接收入账请求、显示充值历史并接收外部操作标识符。如果面板不支持通过 API 入账，自动化只能创建申请或向操作员发送通知。这种方案的缺点——资金仍然需要手动存入。

将余额检查与支付决策分开

余额检查最好作为单独任务按计划运行。它获取余额，将其与阈值比较，并将结果传递给充值处理器。不要在 API 响应的瞬间直接创建支付而不检查当前未完成的操作：并行任务可能会看到相同的低余额并创建多笔付款。

在新支付之前，处理器应检查是否存在状态为“已创建”、“等待付款”或“确认中”的操作。如果存在此类记录，则在核对完成之前不会启动新的尝试。顺序处理的缺点——当外部 API 响应时间较长时，充值可能会比多个并行请求时更晚开始。

选择阈值和充值金额逻辑

余额阈值的选择应为活跃订单、供应商队列和支付延迟留出余量。对于活动不均衡的渠道，仅依据平均支出是有风险的：在直播、投放广告或批量订单之后，扣款可能会急剧增加。另外设置一个临界水平，达到该水平时会收到通知，但不一定会自动创建支付。

充值金额可以是固定的，也可以根据所选期间的支出计算。固定金额更便于控制和核对。其缺点——在平静期，余额上可能会闲置多余资金，而在订单急剧增长时，一次充值可能不够。计算金额更灵活，但需要从统计数据中清除异常扣款和退款。

将财务限制与阈值分开设置

阈值只回答系统何时被允许启动充值流程的问题。限制回答另一个问题：系统有权扣款多少资金。设置单笔操作的最大金额、期间总限额以及入账后的允许余额。这些规则在创建支付之前检查，而不是在付款之后。

自动充值不得在没有单笔操作和期间限额的情况下扣款。如果计算金额高于允许值，最好将操作转入人工审核并发送通知。严格限额的缺点——在支出快速增长时，余额可能会在负责员工确认提高限额之前耗尽。

创建独立密钥并保护访问

对于自动充值脚本，使用具有最低权限的独立 API 密钥：读取余额、创建支付、检查状态以及为已确认操作入账。此类密钥不需要访问用户、服务设置、订单和提现。如果服务支持 IP 地址限制，仅允许来自集成服务器的请求。

密钥存储在环境变量或受保护的密钥存储中。不要将它们传入浏览器代码、日志、公共仓库和错误消息中。每个密钥都应有负责人和明确的更换流程。频繁轮换密钥的缺点——如果未在所有工作流程中更新新密钥，充值将会停止。

创建具有唯一标识符的支付

在调用支付 API 之前，为每笔充值分配一个内部标识符。将其保存在日志中，并作为幂等键或外部操作编号传递。在网络超时的情况下，可以使用相同的标识符重复同一请求：支付服务应返回已创建的操作，而不是再次扣款。

以下是请求的通用示例。请将字段名称和地址替换为特定提供商文档中的值。变量 PAYMENT_ID 存储预先创建的唯一 ID，CALLBACK_URL 指向 Webhook 处理器。

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

不要仅根据金额和创建时间来确定支付的唯一性。两笔相同的充值可能是合法的，而故障后的重复请求则不是。在自有数据库中保存外部 ID 的缺点——需要可靠地存储它，并且在操作取消后不得重复使用。

检查余额并保存操作状态

余额请求应在决定新充值之前以及成功入账之后执行。通用请求可能如下所示：curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY"。在响应中不仅保存金额，还要保存检查时间，以免根据过时数据做出决策。

为每笔操作保留一条记录，包含内部 ID、提供商处的支付 ID、金额、货币、创建时间、状态、API 响应和错误原因。合适的状态链：“已创建”、“等待付款”、“已付款”、“入账中”、“已入账”、“已取消”、“需要检查”。

仅对已确认且尚未处理的付款允许向面板入账。不要在没有历史记录的情况下改写状态：在争议时应该能够看到发送了什么请求以及为什么操作被更改。详细日志的缺点——它可能包含敏感数据，因此对其访问应加以限制。

接收 Webhook 并核对支付状态

支付成功页面和用户重定向并不能确认资金到账。确认依据是来自支付服务的 Webhook 或通过其 API 重新检查状态。收到 Webhook 时，检查签名、发送时间、支付 ID、外部 ID、金额和货币。只有在此之后才将操作转为已确认付款状态。

在检查 Webhook 之后，最好向提供商请求当前的支付状态。例如：curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY"。将状态与日志数据核对，然后使用相同的内部 ID 向 SMM 面板发送入账请求。

重复的 Webhook 不应创建第二次入账。处理器通过外部 ID 找到操作，看到“已入账”状态，并在不执行新操作的情况下返回成功响应。Webhook 的缺点——如果处理器不可用，它们可能会延迟或无法到达。

处理超时、重试和挂起的支付

在创建支付后发生超时时，不要使用不同的 ID 发送新请求。首先通过内部标识符找到操作，或使用相同的幂等键重复请求。如果提供商已接受原始请求，它将返回现有支付。这在连接中断时防止重复扣款。

如果 Webhook 在设定时间内未到达，后台任务通过 API 请求支付状态。重复检查以递增的间隔和有限的尝试次数进行，以免使 API 和日志过载。长时间处于等待状态的操作转入人工审核，而不是在没有核对的情况下视为已取消。

对于网络临时错误或 API 不可用的响应，允许重试。对于付款被拒、金额错误、Webhook 签名无效或超出限额的情况，不应自动重复请求。重试的缺点——它们使状态逻辑复杂化，并且在提供商发生大规模故障时可能产生额外负载。

将已确认的支付入账到 SMM 面板

在入账之前，处理器再次检查：金额不超过限额、货币匹配、操作未被取消且其状态尚未为“已入账”。请求中传递金额和支付的外部标识符。如果面板 API 支持幂等键，请使用相同的内部操作 ID。

请求的通用形式：curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

在面板响应后，再次请求余额并将结果保存在日志中。如果资金已从支付服务扣除，但面板 API 返回错误，不要创建新支付。操作保持“需要检查”状态，直到重新尝试入账或人工核对。这种谨慎方案的缺点——余额可能暂时无法自动充值。

添加通知、开关和启动检查

通知用于异常情况：余额低于临界水平、支付被拒、未收到 Webhook、超出限额、API 不可用或操作需要人工审核。消息中只需指明内部 ID、状态和原因。不要在其中包含 API 密钥、Webhook 签名和支付凭证。

保留一个独立的自动充值开关，而不删除集成。在更换供应商、技术维护、怀疑出错或支出急剧变化时需要它。开关的缺点显而易见：如果在维护后未重新开启，余额可能会在活跃订单期间耗尽。

启用自动充值前的检查清单

• 在存在未完成操作时，余额检查不会创建支付。
• 为每笔支付创建唯一的内部 ID 和幂等键。
• 已设置单笔操作和所选期间的限额。
• Webhook 按签名、金额、货币和标识符进行检查。
• 在缺少 Webhook 时，通过 API 启动状态重新核对。
• 超时不会导致在检查第一笔支付之前创建第二笔支付。
• 向面板入账仅执行一次并记录在日志中。
• 测试模式已在成功、拒绝、重复 Webhook 和 API 不可用的情况下验证。