Ir al contenido

Beta privada · apertura 23 de diciembre

Saldo y error 402

OpenNexum funciona con saldo prepagado en soles. Tú recargas, y cada operación que cobra descuenta de ese saldo. Los precios están por confirmar; consulta siempre tu consumo en lugar de suponerlo.

  • Al empezar una operación que cobra, reservamos su precio de tu saldo.
  • Lo cobramos solo si el servicio confirma. Por ejemplo, un comprobante se cobra cuando SUNAT lo acepta; si SUNAT lo rechaza, la reserva se libera.
  • Las consultas de datos (RUC, tipo de cambio) son lecturas medidas: cuentan contra tu cupo gratis o tu saldo.

Consulta tu saldo con GET /v1/cuenta/saldo: trae lo disponible, lo reservado, el tope de la clave que pregunta y recarga_url. El consumo detallado está en GET /v1/cuenta/consumo. En la API los montos son texto con dos decimales: "1250.50" es S/ 1,250.50.

Cuando no hay con qué pagar la operación, la API responde 402 con recarga_url:

{
"error": {
"codigo": "saldo_insuficiente",
"mensaje": "No te alcanza el saldo para esta operación. Pásale `recarga_url` a una persona de tu cuenta para que recargue.",
"detalle": { "disponible": "12.40", "requerido": "15.00" },
"request_id": "req_8f2c1a7d",
"docs": "https://docs.opennexum.com/errores#saldo_insuficiente",
"recarga_url": "https://app.opennexum.com/recargar"
}
}

Hay dos códigos, los dos con HTTP 402:

  • saldo_insuficiente: el saldo de la cuenta no alcanza. En detalle, disponible es lo que queda y requerido lo que costaría la operación.
  • tope_alcanzado: la clave llegó a su tope de gasto del periodo (diario o mensual), aunque la cuenta tenga saldo. Una persona sube el tope desde el panel. En detalle, disponible es lo que queda del tope.
  1. No reintentes en bucle: el resultado no va a cambiar hasta que alguien recargue o suba el tope.
  2. Dile a una persona de tu cuenta lo que pasó y pásale recarga_url tal cual.
  3. Cuando te avise que recargó, repite la operación con la misma Idempotency-Key: mira Idempotencia.

Un agente nunca recarga por su cuenta ni sube su propio tope: esa decisión es de una persona.