Cómo configurar la recarga automática del saldo en el panel SMM mediante API

Qué preparar antes de configurar la recarga automática

La recarga automática vincula el saldo del panel SMM con un servicio de pago o un sistema de facturación interno. El servicio comprueba el saldo restante, crea un pago al alcanzar el umbral definido y abona los fondos solo tras la confirmación del pago. Para funcionar se necesita la documentación de la API del panel, acceso a la API de pago, claves separadas para el entorno de pruebas y el de producción, así como un registro de todas las operaciones.

Antes del desarrollo, compruebe si la API del panel puede devolver el saldo, aceptar una solicitud de abono, mostrar el historial de recargas y aceptar un identificador externo de la operación. Si el panel no admite el abono mediante API, la automatización solo podrá crear una solicitud o enviar una notificación al operador. La desventaja de esta variante es que el dinero seguirá teniendo que ingresarse manualmente.

Separe la comprobación del saldo y la decisión del pago

Es mejor ejecutar la comprobación del saldo restante como una tarea programada independiente. Esta obtiene el saldo, lo compara con el umbral y pasa el resultado al gestor de recargas. No cree el pago justo en el momento de la respuesta de la API sin comprobar las operaciones pendientes actuales: las tareas paralelas pueden ver el mismo saldo bajo y crear varios pagos.

Antes de un nuevo pago, el gestor debe comprobar si existe alguna operación con estado «creada», «pendiente de pago» o «confirmándose». Si existe tal registro, no se inicia un nuevo intento hasta que finalice la conciliación. La desventaja del procesamiento secuencial es que, ante una respuesta lenta de la API externa, la recarga puede comenzar más tarde que con varias solicitudes paralelas.

Elija el umbral y la lógica del importe de la recarga

El umbral de saldo se elige con un margen para los pedidos activos, la cola de los proveedores y los retrasos de los pagos. Para un canal con actividad irregular, guiarse solo por el gasto medio es arriesgado: tras un stream, el lanzamiento de publicidad o un pedido masivo, los cargos pueden aumentar bruscamente. Se define por separado un nivel crítico en el que llega una notificación, pero no necesariamente se crea un pago automáticamente.

El importe de la recarga puede ser fijo o calcularse a partir del gasto de un periodo determinado. El importe fijo es más sencillo de controlar y conciliar. Su desventaja es que, en un periodo tranquilo, puede haber fondos sobrantes en el saldo, y ante un aumento brusco de pedidos puede que una sola recarga no sea suficiente. El importe calculado es más flexible, pero requiere limpiar las estadísticas de cargos anómalos y devoluciones.

Configure las restricciones financieras por separado del umbral

El umbral solo responde a la pregunta de cuándo se permite al sistema iniciar el proceso de recarga. Las restricciones responden a otra pregunta: cuántos fondos puede cargar. Defina el importe máximo de una operación, el límite total por periodo y el saldo admisible tras el abono. Estas reglas se comprueban antes de crear el pago, no después de pagarlo.

La recarga automática no debe cargar fondos sin un límite por operación y por periodo. Si el importe calculado supera el permitido, es mejor pasar la operación a verificación manual y enviar una notificación. La desventaja de los límites estrictos es que, ante un rápido aumento de los gastos, el saldo puede agotarse antes de que el empleado responsable confirme el aumento del límite.

Cree claves separadas y proteja el acceso

Para el script de recarga automática utilice claves de API separadas con permisos mínimos: lectura del saldo, creación del pago, verificación del estado y abono de la operación confirmada. Este tipo de clave no necesita acceso a los usuarios, a la configuración de servicios, a los pedidos ni al retiro de fondos. Si el servicio admite restricción por direcciones IP, permita las solicitudes solo desde el servidor de la integración.

Las claves se guardan en variables de entorno o en un almacén de secretos protegido. No las transmita al código del navegador, a los registros, a repositorios públicos ni a mensajes de error. Cada clave debe tener un propietario y un procedimiento de sustitución claro. La desventaja de rotar las claves con frecuencia es que la recarga se detendrá si el nuevo secreto no se actualiza en todos los procesos de producción.

Cree el pago con un identificador único

A cada recarga se le asigna un identificador interno antes de llamar a la API de pago. Se guarda en el registro y se transmite como clave de idempotencia o número externo de la operación. En caso de tiempo de espera de red, la misma solicitud puede repetirse con el mismo identificador: el servicio de pago debe devolver la operación ya creada, y no cargar el dinero dos veces.

A continuación se muestra un ejemplo genérico de solicitud. Sustituya los nombres de los campos y las direcciones por los valores de la documentación del proveedor concreto. En la variable PAYMENT_ID se guarda un ID único creado de antemano, y CALLBACK_URL apunta al gestor 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"}'

No determine la unicidad del pago solo por el importe y la hora de creación. Dos recargas idénticas pueden ser legítimas, pero una solicitud repetida tras un fallo no lo es. La desventaja del ID externo en su propia base de datos es que debe almacenarse de forma fiable y no reutilizarse tras la cancelación de la operación.

Compruebe el saldo y guarde el estado de la operación

La solicitud del saldo debe realizarse antes de decidir una nueva recarga y después de un abono exitoso. Una solicitud genérica puede tener este aspecto: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". En la respuesta guarde no solo el importe, sino también la hora de la comprobación, para no tomar decisiones con datos desactualizados.

Para cada operación lleve un registro con el ID interno, el ID del pago en el proveedor, el importe, la moneda, la hora de creación, el estado, las respuestas de la API y el motivo del error. Una cadena de estados adecuada es: «creada», «pendiente de pago», «pagada», «abonándose», «abonada», «cancelada», «requiere verificación».

El abono en el panel solo se permite para un pago confirmado y aún no procesado. No reescriba los estados sin historial: en caso de disputa debe verse qué solicitud se envió y por qué se modificó la operación. La desventaja de un registro detallado es que puede contener datos sensibles, por lo que se restringe el acceso a él.

Reciba el webhook y concilie el estado del pago

La página de pago exitoso y la redirección del usuario no confirman la recepción del dinero. La confirmación es el webhook del servicio de pago o una nueva verificación del estado mediante su API. Al recibir el webhook, compruebe la firma, la hora de envío, el ID del pago, el ID externo, el importe y la moneda. Solo después de esto pase la operación al estado de pago confirmado.

Tras verificar el webhook, es útil solicitar al proveedor el estado actual del pago. Por ejemplo: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". Concilie el estado con los datos del registro y luego envíe la solicitud de abono al panel SMM con el mismo ID interno.

Un webhook repetido no debe crear un segundo abono. El gestor encuentra la operación por el ID externo, ve el estado «abonada» y devuelve una respuesta exitosa sin nuevas acciones. La desventaja de los webhooks es que pueden retrasarse o no llegar si el gestor no estaba disponible.

Gestione los tiempos de espera, los reintentos y los pagos bloqueados

En caso de tiempo de espera tras crear el pago, no envíe una nueva solicitud con otro ID. Primero busque la operación por el identificador interno o repita la solicitud con la misma clave de idempotencia. Si el proveedor aceptó la solicitud original, devolverá el pago existente. Esto protege frente a un doble cargo en caso de corte de la conexión.

Si el webhook no llegó en el tiempo definido, una tarea en segundo plano solicita el estado del pago mediante la API. Las comprobaciones repetidas se hacen con una pausa creciente y un número limitado de intentos, para no sobrecargar la API ni el registro. La operación que permanece mucho tiempo en espera se pasa a verificación manual, y no se considera cancelada sin conciliación.

Ante respuestas de error temporal de red o de indisponibilidad de la API, los reintentos son admisibles. Ante un rechazo del pago, un importe incorrecto, una firma de webhook no válida o la superación del límite, no conviene repetir la solicitud automáticamente. La desventaja de los reintentos es que complican la lógica de estados y pueden crear una carga adicional ante un fallo masivo del proveedor.

Abone el pago confirmado en el panel SMM

Antes del abono, el gestor comprueba una vez más: que el importe no supere el límite, que la moneda coincida, que la operación no haya sido cancelada y que su estado aún no sea «abonada». En la solicitud se transmiten el importe y el identificador externo del pago. Si la API del panel admite una clave de idempotencia, utilice el mismo ID interno de la operación.

Aspecto genérico de la solicitud: 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"}'

Tras la respuesta del panel, solicite el saldo de nuevo y guarde el resultado en el registro. Si el dinero se cargó en el servicio de pago, pero la API del panel devolvió un error, no cree un nuevo pago. La operación permanece en el estado «requiere verificación» hasta un nuevo intento de abono o una conciliación manual. La desventaja de este esquema tan prudente es que el saldo puede no recargarse automáticamente de forma temporal.

Añada notificaciones, un interruptor y una comprobación del arranque

Las notificaciones son necesarias para las desviaciones: el saldo cayó por debajo del nivel crítico, el pago fue rechazado, no se recibió el webhook, se superó el límite, la API no está disponible o la operación requiere verificación manual. En el mensaje basta con indicar el ID interno, el estado y el motivo. No incluya en él claves de API, firmas de webhooks ni datos de pago.

Deje un interruptor separado para la recarga automática sin eliminar la integración. Es necesario al cambiar de proveedor, durante trabajos técnicos, ante la sospecha de un error o un cambio brusco de los gastos. La desventaja del interruptor es evidente: si no se vuelve a activar tras los trabajos, el saldo puede agotarse durante pedidos activos.

Lista de comprobación antes de activar la recarga automática

• La comprobación del saldo no crea un pago mientras haya una operación pendiente.
• Para cada pago se crea un ID interno único y una clave de idempotencia.
• Están configurados los límites por operación y por periodo elegido.
• Los webhooks se verifican por firma, importe, moneda e identificador.
• Si no hay webhook, se inicia una nueva conciliación del estado mediante la API.
• Un tiempo de espera no provoca la creación de un segundo pago antes de comprobar el primero.
• El abono en el panel se realiza una sola vez y queda registrado en el registro.
• El modo de prueba se ha verificado con éxito, rechazo, webhook duplicado e indisponibilidad de la API.