Verificación del saldo mediante la API antes de un lanzamiento masivo de pedidos

Por qué consultar el saldo antes de lanzar la cola

Un lanzamiento masivo de pedidos sin una verificación actualizada del saldo provoca rechazos parciales: las primeras solicitudes se crean y las siguientes reciben un error por falta de fondos. Lo más complicado es resolver esta situación cuando se envían solicitudes en paralelo, con distintos servicios y varios procesos trabajando sobre una misma cuenta.

Para el lanzamiento no importa el volumen total de recargas ni el saldo contable del panel de usuario. Se necesita la suma que el servicio permite debitar en el momento de crear un nuevo pedido. El dinero destinado a solicitudes activas puede estar ya en reserva, aunque el débito definitivo aún no se refleje en el historial de operaciones.

Compare el presupuesto de la cola con el campo de saldo disponible, no con la suma total de la cuenta.

Cómo es la respuesta del método de saldo

Los nombres de los campos los define la documentación de cada plataforma, pero un contrato cómodo del método de saldo suele devolver total, available, reserved, currency y updated_at. A continuación se muestra un ejemplo de estructura que puede servir de referencia al integrar. No es una respuesta universal para cada servicio, sino un ejemplo de esquema de datos comprensible.

La solicitud puede verse así:

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

Respuesta:

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

En este ejemplo, total son todos los fondos de la cuenta, available es el dinero para nuevos pedidos y reserved es la suma destinada a operaciones creadas previamente. La comprobación cuadra: 125.80 menos 41.30 es igual a 84.50. El campo currency define la unidad de cálculo y updated_at ayuda a entender qué tan recientes son los datos.

Cómo interpretar available y reserved

El campo available se usa para decidir el lanzamiento. Si la cola cuesta 80.00 y available es 84.50, los fondos alcanzan solo si la API no añade una comisión aparte ni recalcula el precio en el momento de crear la solicitud. El campo reserved no se suma al saldo disponible: esa suma ya está ocupada.

reserved puede incluir el costo de pedidos con estados processing, pending o review; el conjunto exacto depende de las reglas de la plataforma. A veces la reserva se libera tras una cancelación, una ejecución parcial o una revisión manual. Por eso, calcularla por tu cuenta a partir de la lista de pedidos solo sirve como verificación adicional.

• total sirve para cotejar con el historial de recargas y débitos;
• available sirve para admitir el lanzamiento de una nueva cola;
• reserved muestra cuánto dinero ya está bloqueado para operaciones activas;
• currency no debe ignorarse incluso si se trabaja con una sola cuenta;
• updated_at es útil para el registro y para diagnosticar una respuesta desactualizada.

Una respuesta con solo el campo balance es más fácil de procesar, pero tiene una desventaja: no permite saber si ese dinero está disponible de inmediato o si parte de la suma ya está retenida para otros pedidos.

Verifique el formato de las sumas en la documentación de la API

En el ejemplo, las sumas se envían como cadenas: "84.50", no como el número 84.5. Ese formato conserva el valor exacto que devolvió el servicio. Si la API usa cadenas con punto decimal, no conviene convertirlas de inmediato a números de coma flotante ni hacer comparaciones con float.

Por ejemplo, tu cálculo puede dar 84.499999 en lugar de los 84.50 esperados. En el límite del presupuesto, esto puede hacer que la cola se admita por error o, al contrario, que se detenga. Para operaciones con valores decimales en cadena, use un tipo de dato decimal que admita la precisión de una parte fraccionaria fija.

Otro contrato habitual son las unidades mínimas enteras. En ese caso, la respuesta puede contener "available_minor": 8450 y "currency": "USD", y el precio del pedido, "price_minor": 1250. Dentro de esa API, 8450 significa 84.50 si las reglas de la moneda suponen dos posiciones decimales. Solo se puede dividir el valor entre 100 cuando la documentación lo indica expresamente.

No mezcle monedas ni formatos de precios

Antes de calcular la cola, compare la currency del saldo con la moneda del método de precios o de la respuesta al crear el pedido. Si el saldo devuelve una moneda y el catálogo de servicios otra, no se pueden usar las cifras directamente. Se necesita un cálculo que proporcione la propia plataforma o un método de conversión independiente y confirmado.

La conversión previa por tu cuenta es cómoda para planificar, pero tiene una desventaja: el servicio puede aplicar otro tipo de cambio, una comisión o una regla de redondeo en el momento del débito. Es más fiable enviar el pedido con parámetros para los que la API devuelva el costo final en la moneda del saldo, o bien obtener el cálculo del precio justo antes de crearlo.

Si el método de precios responde "price": "12.345" y el saldo almacena valores con dos decimales, aclare la regla de redondeo. No redondee automáticamente hacia abajo: el débito real puede ser mayor. Para admitir la cola, use exactamente la suma que la API indica como costo final del pedido.

Calcule el presupuesto de la cola antes de la primera solicitud

Antes del lanzamiento, reúna todas las solicitudes y calcule su costo teniendo en cuenta el volumen, el servicio elegido, la región, las opciones adicionales y la comisión, si se transmite por separado. No compare available con el precio base de la interfaz: en la API, el total puede depender de los parámetros de cada pedido concreto.

Supongamos que en la cola hay tres pedidos. La API de cálculo de precios devolvió para ellos 18.40, 27.15 y 31.60 en la misma moneda indicada en balance.currency. El presupuesto es 77.15. Si balance.available es 84.50, tras el lanzamiento previsto quedan 7.35. Si available es 76.90, no se puede lanzar toda la cola.

1. Obtenga los precios según los parámetros reales de cada pedido.
2. Sume los costos finales sin cambiar su formato ni su moneda.
3. Compare el presupuesto con available de una respuesta de saldo reciente.
4. Si el saldo es suficiente, fije la suma como reserva local del lanzamiento.
5. Tras crear cada solicitud, reduzca la reserva local en el costo confirmado.

Un margen reduce el riesgo de rechazo por un débito adicional, pero tiene una desventaja: parte de los fondos disponibles quedará sin usar, aunque la cola podría haberse procesado por completo.

Haga una segunda verificación justo antes del envío

El saldo obtenido durante la preparación de la campaña pierde vigencia rápido. Entre el cálculo y el lanzamiento, otro operador, una automatización o un pedido activo pueden modificar available y reserved. Se necesita una nueva solicitud después de formar la cola y justo antes del primer pedido.

El esquema de trabajo consta de dos etapas: primero obtener los precios y estimar el presupuesto, luego solicitar balance otra vez. Si el valor de available disminuyó y quedó por debajo de la suma calculada, la cola no se envía completa. Entre la verificación final y el lanzamiento no conviene realizar otros débitos con la misma cuenta.

Una sola solicitud para todo el lanzamiento reduce la carga sobre la API, pero su desventaja es que el saldo disponible puede cambiar mientras aún se procesa una cola larga.

Cómo lanzar la cola cuando faltan fondos

Si available es menor que el presupuesto, no envíe todas las solicitudes con la esperanza de que algunas pasen. Divida la cola en paquetes cuyo costo quepa en el límite disponible. En el ejemplo con un saldo de 76.90, se pueden enviar los dos primeros pedidos por 45.55 y luego detenerse: el tercero, por 31.60, requiere una nueva verificación.

Defina explícitamente el orden de las solicitudes al agrupar. Se pueden enviar primero los pedidos prioritarios o formar paquetes de costo similar. Cada opción tiene una desventaja: el orden por prioridad pospondrá las posiciones menos importantes, y la ordenación por precio puede alterar el plan original de la campaña.

• Forme un paquete con una suma no superior al available actual.
• Cree los pedidos del paquete y guarde sus identificadores.
• Espere las respuestas o verifique los estados de las operaciones tras los tiempos de espera.
• Haga una pausa si los límites de la API o las reglas del servicio lo requieren.
• Solicite balance de nuevo antes del siguiente paquete.

Después de cada paquete, guíese por la nueva respuesta de la API, no solo por la deducción local del saldo anterior. El cálculo local es útil para el control, pero no ve devoluciones, débitos externos ni recálculos de reservas.

Proteja el presupuesto en el envío paralelo

En el procesamiento secuencial basta con reducir el límite local tras confirmar el pedido. En el modelo paralelo, dos workers pueden ver al mismo tiempo available 84.50 y planificar cada uno un gasto de 60.00. Ambas decisiones parecen admisibles por separado, pero juntas superan el saldo disponible.

Para protegerse se necesita un contador común de reserva local o una cola cuyo acceso se realice de forma atómica. Antes del envío, el worker intenta ocupar la suma del pedido en ese contador. Si el límite libre no alcanza, la solicitud queda en espera de una nueva verificación del saldo.

• La cola secuencial es más fácil de controlar, pero se lanza más despacio.
• El envío paralelo reduce el tiempo de lanzamiento, pero exige bloquear el presupuesto común.
• La reserva local reduce los conflictos, pero puede quedar bloqueada tras un fallo de un worker.
• La reserva del lado de la API es más fiable, pero no está disponible en todas las plataformas.

Si el proceso terminó antes de recibir la respuesta, la reserva local no puede considerarse de inmediato gastada ni libre. Primero verifique si el pedido se creó, por su identificador externo o mediante el método de búsqueda de operaciones.

Use la reserva de la API si está prevista

Algunas API permiten crear una reserva para un conjunto de operaciones o realizar el pedido en dos pasos: cálculo, bloqueo de la suma y confirmación. En ese esquema, la ventana entre la verificación y el débito es menor, y otro proceso tiene menos oportunidad de gastar los fondos de la cuenta.

Si existe ese método, guarde el identificador de la reserva, su suma, la moneda, la fecha de vencimiento y el estado. Luego transmita ese identificador al crear los pedidos, si el contrato de la API lo requiere. Al terminar la cola, coteje la parte no utilizada y el hecho de que el bloqueo se haya liberado.

La reserva de la API no resuelve todos los problemas: puede tener una vigencia corta, no cubrir comisiones o liberarse tras un error de confirmación. La reserva local es más fácil de implementar, pero su desventaja es que no protege de los gastos creados fuera de tu aplicación.

Distinga un error de saldo de un saldo cero

Una respuesta con código de error, un tiempo de espera agotado o un límite de frecuencia de solicitudes no significan que available sea cero. No sustituya automáticamente el último valor conocido si de él depende un lanzamiento grande. Si no es posible obtener un saldo reciente, hay que pausar la cola.

Procese por separado el rechazo al crear el pedido. Puede deberse a falta de fondos, pero también a un identificador de servicio incorrecto, un volumen no permitido, una restricción del canal o la repetición de una misma operación. Guarde el código y el texto del error junto con el identificador externo de la solicitud.

• Si hay un error de autorización, actualice el acceso y solo después repita la solicitud.
• Si se alcanza el límite de solicitudes, espere según las reglas de la API.
• Si se agota el tiempo de espera al crear, primero verifique si la operación apareció realmente.
• Si hay un error por falta de fondos, detenga el paquete y solicite balance de nuevo.

No cree duplicados tras un tiempo de espera agotado

Un tiempo de espera agotado significa que tu cliente no recibió respuesta, no que el servidor no haya procesado la solicitud. Un reenvío sin verificación puede crear un segundo pedido y volver a ocupar dinero. Esto es especialmente peligroso en una cola donde el reintento automático está configurado para varios intentos.

Transmita un identificador externo único del pedido si la API admite el campo client_order_id, external_id o idempotency_key. Guárdelo antes de enviar la solicitud. Tras un tiempo de espera agotado, busque la operación por ese valor o solicite el estado por el identificador obtenido anteriormente.

El reintento sin verificación es más rápido, pero su desventaja es directa: son posibles los pedidos duplicados, la doble reserva y las discrepancias entre tu cálculo del presupuesto y los débitos reales.

Qué guardar en el registro del lanzamiento

El registro ayuda a reconstruir el curso de una operación masiva y a explicar por qué se detuvo un paquete concreto. Para cada lanzamiento, guarde la hora de las dos verificaciones, total, available, reserved, currency, el presupuesto calculado, el tamaño de la reserva local y la lista de identificadores externos de las solicitudes.

Para cada intento de creación, registre el costo, el código de respuesta, el identificador técnico de la operación y el estado final. Los secretos no deben llegar al registro: los tokens de autorización, las claves de API, las cabeceras completas de las solicitudes y los datos personales deben enmascararse o excluirse antes de escribirlos.

El registro completo es cómodo para depurar, pero tiene una desventaja: sin filtrado, pueden acabar en el almacenamiento datos de acceso e información de clientes.

Pruebe el esquema con una cola pequeña

Antes de un lanzamiento grande, realice un escenario breve: obtenga balance, solicite los precios finales, cree un paquete limitado, solicite balance de nuevo y compare el cambio esperado de available y reserved con la respuesta real. Así se puede observar cuándo el servicio reserva la suma y cuándo la debita definitivamente.

Un paquete de prueba no garantiza el mismo comportamiento bajo una gran carga: pueden activarse límites, procesos paralelos o restricciones de un servicio concreto. Por eso, en una cola masiva conviene seguir dividiendo el lanzamiento en paquetes, verificar el saldo disponible entre ellos y analizar cada rechazo por separado.