Como configurar a recarga automática de saldo no painel SMM via API

O que preparar antes de configurar a recarga automática

A recarga automática conecta o saldo do painel SMM a um serviço de pagamento ou a um sistema de cobrança interno. O serviço verifica o saldo restante, cria um pagamento quando o limite definido é atingido e credita os fundos somente após a confirmação do pagamento. Para funcionar, são necessários a documentação da API do painel, o acesso à API de pagamento, chaves separadas para o ambiente de teste e o de produção, além de um registro de todas as operações.

Antes do desenvolvimento, verifique se a API do painel consegue retornar o saldo, aceitar uma solicitação de crédito, exibir o histórico de recargas e receber um identificador externo da operação. Se o painel não suportar crédito via API, a automação só poderá criar uma solicitação ou enviar uma notificação ao operador. A desvantagem dessa opção é que o dinheiro ainda precisará ser depositado manualmente.

Separe a verificação de saldo da decisão de pagamento

É melhor executar a verificação de saldo como uma tarefa separada, agendada. Ela obtém o saldo, compara-o com o limite e passa o resultado ao manipulador de recarga. Não crie o pagamento no momento da resposta da API sem verificar as operações pendentes atuais: tarefas paralelas podem ver o mesmo saldo baixo e criar vários pagamentos.

Antes de um novo pagamento, o manipulador deve verificar se há alguma operação com status "criada", "aguardando pagamento" ou "em confirmação". Se existir esse registro, uma nova tentativa não é iniciada até a conclusão da conciliação. A desvantagem do processamento sequencial é que, com uma resposta demorada da API externa, a recarga pode começar mais tarde do que com várias solicitações paralelas.

Escolha o limite e a lógica do valor da recarga

O limite de saldo é escolhido com uma margem para pedidos ativos, fila nos fornecedores e atrasos de pagamento. Para um canal com atividade irregular, orientar-se apenas pelo gasto médio é arriscado: após uma live, o lançamento de anúncios ou um pedido em massa, as deduções podem crescer abruptamente. Define-se separadamente um nível crítico, no qual chega uma notificação, mas o pagamento não é necessariamente criado de forma automática.

O valor da recarga pode ser fixo ou calculado a partir do gasto em um período selecionado. O valor fixo é mais simples para controle e conciliação. Sua desvantagem é que, em um período calmo, pode haver fundos extras no saldo, e, em um crescimento abrupto de pedidos, uma única recarga pode não ser suficiente. O valor calculado é mais flexível, mas exige limpar as estatísticas de deduções anômalas e estornos.

Configure as restrições financeiras separadamente do limite

O limite responde apenas à pergunta de quando o sistema tem permissão para iniciar o processo de recarga. As restrições respondem a outra pergunta: quanto dinheiro ele pode debitar. Defina o valor máximo de uma operação, o limite total por período e o saldo permitido após o crédito. Essas regras são verificadas antes da criação do pagamento, não depois do pagamento.

A recarga automática não deve debitar fundos sem limite por operação e por período. Se o valor calculado for superior ao permitido, é melhor encaminhar a operação para verificação manual e enviar uma notificação. A desvantagem de limites rígidos é que, com um crescimento rápido das despesas, o saldo pode acabar antes que o funcionário responsável confirme o aumento do limite.

Crie chaves separadas e proteja o acesso

Para o script de recarga automática, use chaves de API separadas com permissões mínimas: leitura de saldo, criação de pagamento, verificação de status e crédito de uma operação confirmada. O acesso a usuários, configurações de serviços, pedidos e saque de fundos não é necessário para essa chave. Se o serviço suportar restrição por endereços IP, permita solicitações apenas a partir do servidor de integração.

As chaves são armazenadas em variáveis de ambiente ou em um cofre de segredos protegido. Não as transmita em código de navegador, logs, repositórios públicos ou mensagens de erro. Cada chave deve ter um responsável e um procedimento claro de substituição. A desvantagem da rotação frequente de chaves é que a recarga será interrompida se o novo segredo não for atualizado em todos os processos em execução.

Crie o pagamento com um identificador único

Cada recarga recebe um identificador interno antes da chamada à API de pagamento. Ele é salvo no registro e enviado como chave de idempotência ou número externo da operação. Em caso de timeout de rede, a mesma solicitação pode ser repetida com o mesmo identificador: o serviço de pagamento deve retornar a operação já criada, e não debitar o dinheiro novamente.

Abaixo está um exemplo genérico de solicitação. Substitua os nomes dos campos e os endereços pelos valores da documentação do provedor específico. A variável PAYMENT_ID contém um ID único criado previamente, e CALLBACK_URL aponta para o manipulador de webhooks.

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"}'

Não determine a unicidade do pagamento apenas pelo valor e pelo horário de criação. Duas recargas iguais podem ser legítimas, mas uma solicitação repetida após uma falha não é. A desvantagem do ID externo no próprio banco de dados é que ele precisa ser armazenado de forma confiável e não pode ser reutilizado após o cancelamento da operação.

Verifique o saldo e salve o estado da operação

A solicitação de saldo deve ser executada antes da decisão sobre uma nova recarga e após o crédito bem-sucedido. Uma solicitação genérica pode ser assim: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". Na resposta, salve não apenas o valor, mas também o horário da verificação, para não tomar decisões com base em dados desatualizados.

Para cada operação, mantenha um registro com o ID interno, o ID do pagamento no provedor, o valor, a moeda, o horário de criação, o status, as respostas da API e o motivo do erro. Uma sequência de estados adequada: "criada", "aguardando pagamento", "paga", "em crédito", "creditada", "cancelada", "requer verificação".

O crédito no painel é permitido apenas para um pagamento confirmado e ainda não processado. Não reescreva status sem histórico: em caso de disputa, deve ser possível ver qual solicitação foi enviada e por que a operação foi alterada. A desvantagem de um registro detalhado é que ele pode conter dados sensíveis, por isso o acesso a ele é restrito.

Receba o webhook e confira o status do pagamento

A página de pagamento bem-sucedido e o redirecionamento do usuário não confirmam a entrada do dinheiro. A confirmação é o webhook do serviço de pagamento ou uma nova verificação de status por meio de sua API. Ao receber o webhook, verifique a assinatura, o horário de envio, o ID do pagamento, o ID externo, o valor e a moeda. Somente depois disso, altere a operação para o estado de pagamento confirmado.

Após verificar o webhook, é útil solicitar o status atual do pagamento ao provedor. Por exemplo: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". Confira o status com os dados do registro e, em seguida, envie a solicitação de crédito ao painel SMM com o mesmo ID interno.

Um webhook repetido não deve criar um segundo crédito. O manipulador encontra a operação pelo ID externo, vê o status "creditada" e retorna uma resposta de sucesso sem novas ações. A desvantagem dos webhooks é que eles podem atrasar ou não chegar se o manipulador estiver indisponível.

Trate timeouts, retentativas e pagamentos travados

Em caso de timeout após a criação do pagamento, não envie uma nova solicitação com outro ID. Primeiro, encontre a operação pelo identificador interno ou repita a solicitação com a mesma chave de idempotência. Se o provedor aceitou a solicitação original, ele retornará o pagamento existente. Isso protege contra débito duplo em caso de queda de conexão.

Se o webhook não chegar dentro do tempo definido, uma tarefa em segundo plano solicita o status do pagamento via API. As verificações repetidas são feitas com pausa crescente e número limitado de tentativas, para não sobrecarregar a API e o registro. Uma operação que permanece aguardando por muito tempo é encaminhada para verificação manual, e não considerada cancelada sem conciliação.

Em respostas de erro temporário de rede ou indisponibilidade da API, as retentativas são permitidas. Em caso de recusa de pagamento, valor incorreto, assinatura de webhook inválida ou excesso de limite, não vale a pena repetir a solicitação automaticamente. A desvantagem das retentativas é que elas complicam a lógica de estados e podem criar carga extra em caso de falha em massa no provedor.

Credite o pagamento confirmado no painel SMM

Antes do crédito, o manipulador verifica mais uma vez: o valor não excede o limite, a moeda coincide, a operação não foi cancelada e seu status ainda não é "creditada". A solicitação inclui o valor e o identificador externo do pagamento. Se a API do painel suportar chave de idempotência, use o mesmo ID interno da operação.

Forma genérica da solicitação: 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"}'

Após a resposta do painel, solicite o saldo novamente e salve o resultado no registro. Se o dinheiro foi debitado no serviço de pagamento, mas a API do painel retornou erro, não crie um novo pagamento. A operação permanece no status "requer verificação" até uma nova tentativa de crédito ou conciliação manual. A desvantagem desse esquema cauteloso é que o saldo pode temporariamente não ser recarregado automaticamente.

Adicione notificações, interruptor e verificação de inicialização

As notificações são necessárias para desvios: o saldo caiu abaixo do nível crítico, o pagamento foi recusado, o webhook não foi recebido, o limite foi excedido, a API está indisponível ou a operação requer verificação manual. Na mensagem, basta indicar o ID interno, o status e o motivo. Não inclua nela chaves de API, assinaturas de webhooks e dados de pagamento.

Deixe um interruptor separado para a recarga automática sem remover a integração. Ele é necessário ao trocar de provedor, em manutenção técnica, em caso de suspeita de erro ou de mudança abrupta nas despesas. A desvantagem do interruptor é óbvia: se ele não for reativado após a manutenção, o saldo pode acabar durante pedidos ativos.

Checklist antes de ativar a recarga automática

• A verificação de saldo não cria pagamento enquanto houver uma operação pendente.
• Para cada pagamento, é criado um ID interno único e uma chave de idempotência.
• Os limites para uma operação e para o período selecionado estão configurados.
• Os webhooks são verificados por assinatura, valor, moeda e identificador.
• Na ausência de webhook, é iniciada uma nova conciliação de status via API.
• O timeout não leva à criação de um segundo pagamento antes da verificação do primeiro.
• O crédito no painel é executado uma única vez e registrado no log.
• O modo de teste foi verificado em caso de sucesso, recusa, webhook duplicado e indisponibilidade da API.