Beta privada · apertura 23 de diciembre
Lista tu consumo
GET /v1/cuenta/consumo
Movimientos de tu saldo del periodo (por omisión, el mes en curso): reservas, cobros y liberaciones con la operación y la clave que los hizo, y las recargas acreditadas. Trae además el gasto de cada clave o agente en todo el periodo.
| Dato | Valor |
|---|---|
| Permiso | cuenta:leer |
| Cobro | No cobra. |
Idempotency-Key |
No aplica |
| Herramienta MCP | cuenta_consumo (Próximamente) |
Parámetros
Sección titulada «Parámetros»| Nombre | En | Requerido | Tipo | Descripción |
|---|---|---|---|---|
cursor |
query | No | string | Cursor opaco que devolvió la página anterior en siguiente_cursor. |
limite |
query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). |
desde |
query | No | string | Desde este día (incluido). Si no lo envías, desde el día 1 del mes de hasta. |
hasta |
query | No | string | Hasta este día (incluido). Si no lo envías, hoy en Lima. |
servicio |
query | No | string | Solo el consumo de ese servicio (deja fuera las recargas). |
clave_id |
query | No | string | Solo lo gastado con esta clave (deja fuera las recargas). |
X-Request-Id |
header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. |
Ejemplo
Sección titulada «Ejemplo»Contra el sandbox, con una clave onx_test_…:
curl "https://api-sandbox.opennexum.com/v1/cuenta/consumo" \ -H "Authorization: Bearer onx_test_…"Respuestas
Sección titulada «Respuestas»Página de movimientos con el gasto por clave.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
elementos |
object[] | Sí | |
elementos[].id |
string | Sí | Identificador que empieza con mov_. |
elementos[].tipo |
“consumo” | “recarga” | Sí | consumo: lo que gastó una clave; recarga: saldo que sumaste. |
elementos[].fecha |
string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
elementos[].servicio |
“datos” | “comprobantes” | “conecta” | null | Sí | Servicio del consumo; null en una recarga. |
elementos[].operacion |
string | Sí | operationId de la ruta, por ejemplo comprobante_emitir o recarga_crear. |
elementos[].monto |
string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. “1250.50” es S/ 1,250.50. |
elementos[].moneda |
“PEN” | Sí | |
elementos[].estado |
“reservado” | “cobrado” | “liberado” | “acreditado” | Sí | Consumo: reservado mientras se completa, cobrado al confirmarse, liberado si falló o venció. Recarga: acreditado. |
elementos[].clave_id |
string | null | Sí | Clave (o agente conectado) que gastó; null en una recarga. |
elementos[].request_id |
string | null | Sí | |
elementos[].recurso |
object | null | Sí | |
elementos[].recurso.tipo |
“comprobante” | “baja” | “resumen” | “guia” | “sire_propuesta” | “mensaje” | “entrega” | “clave” | “conexion” | “webhook” | Sí | |
elementos[].recurso.id |
string | Sí | |
siguiente_cursor |
string | null | Sí | Pásalo como cursor para la página siguiente; null si ya no hay más. |
periodo |
object | Sí | Días consultados, en hora de Lima. |
periodo.desde |
string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). |
periodo.hasta |
string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). |
gasto_por_clave |
object[] | Sí | Gasto de cada clave o agente en todo el periodo (no solo en esta página), de mayor a menor. |
gasto_por_clave[].clave_id |
string | Sí | Identificador que empieza con clv_. |
gasto_por_clave[].nombre |
string | Sí | |
gasto_por_clave[].prefijo |
string | Sí | Inicio visible de la clave; onx_<entorno>_oauth si es un agente conectado. |
gasto_por_clave[].origen |
“clave” | “agente_oauth” | Sí | agente_oauth: un agente conectado desde el panel con OAuth. |
gasto_por_clave[].cobrado |
string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. “1250.50” es S/ 1,250.50. |
gasto_por_clave[].reservado |
string | Sí | Retenido en operaciones que todavía no terminan. |
gasto_por_clave[].operaciones |
integer | Sí | Operaciones que cobraron o reservaron saldo en el periodo. |
Errores
Sección titulada «Errores»Cada código tiene su explicación en Errores.
- 400
validacion - 401
clave_invalida - 403
permiso_faltante - 429
limite_uso - 500
error_interno - 501
operacion_no_disponible - 503
no_disponible