Movimientos y ajustes por indexación

Próximamente

Contrato publicado para diseño; las operaciones aún no responden de punta a punta.

Leer movimientos

GET /v1/accounts/{accountId}/movements (alcance movements:read) devuelve los movimientos de la cuenta del más reciente al más antiguo, por cursor.

Cada fila trae lo necesario para sumarla sin errores:

Campo	Para qué sirve
`naturaleza`	Clasificación del catálogo: `CONSUMO`, `AVANCE`, `PAGO`, `REVERSO`, `DEVOLUCION`, `INTERES`, `COMISION`, `ABONO`, `AJUSTE`, `AJUSTE_INDEXACION`, `RETENCION`, `FINANCIAMIENTO` u `OTRO`
`fase`	Fase real en el libro: `RETENIDA`, `CAPTURADA`, `REVERSADA`, `LIBERADA`, `RECHAZADA` o `FALLIDA`
`efectoSaldo`	`CARGO`, `ABONO` o `NINGUNO`. Suma por este campo: así no cuentas dos veces un reverso ni una preautorización ya capturada
`monto`	Importe en la moneda del libro, como texto decimal
`contrato` / `contratoEstimado`	En cuentas UVC, el importe en la unidad del contrato (o su estimación si aún no se convirtió)
`tarjeta`	`cardId` y `last4` del plástico, si aplica. Nunca el número completo
`comercio`	MCC, nombre y terminal, si aplica

Filtros:

Parámetro	Por defecto	Efecto
`desde`, `hasta`	—	Rango de fechas (`hasta` obligatorio si supera 93 días)
`naturaleza`	todas menos `AJUSTE_INDEXACION`	Lista separada por coma, p. ej. `naturaleza=CONSUMO,PAGO`
`incluirRechazadas`	`false`	Incluye las fases `RECHAZADA` y `FALLIDA`, siempre con `efectoSaldo = NINGUNO`
`incluirAjustes`	`false`	Incluye los ajustes por indexación. Exige `movements:adjustments`

Ajustes por indexación: ocultos por defecto

En el crédito indexado en UVC, la deuda en UVC no cambia cuando se publica un nuevo IDI, pero su valor en Bs sí. Ese cambio se registra como un movimiento de naturaleza AJUSTE_INDEXACION. Como no es una compra ni un pago del titular, y podría confundir a un sistema que suma movimientos, la API lo oculta por defecto y solo lo muestra a quien lo pide expresamente y tiene el alcance movements:adjustments.

Quieres…	Necesitas
Ver los ajustes dentro de la lista de movimientos	`incluirAjustes=true` (o `naturaleza` con `AJUSTE_INDEXACION`) y `movements:adjustments`
La serie diaria de ajustes con el IDI y el detalle por tramo	`GET /v1/accounts/{accountId}/indexation-adjustments` con `movements:adjustments`
Recibir los eventos `cuenta.ajuste_indexacion` e `indexacion.revaluacion_completada`	Suscribirte a ellos con `movements:adjustments`

Sin el alcance, cualquiera de esas formas responde 403 ALCANCE_INSUFICIENTE:

curl 'https://api-cms.example.com/v1/accounts/3f0c2a7e-5b1d-4e8f-a9c2-7d6e5f4a3b21/movements?incluirAjustes=true' \
  -H "Authorization: Bearer $TOKEN_SIN_AJUSTES"

{
  "type": "urn:finora:cms-api:alcance-insuficiente",
  "title": "Alcance insuficiente",
  "status": 403,
  "codigo": "ALCANCE_INSUFICIENTE",
  "detail": "La operación exige movements:adjustments.",
  "requestId": "01JBX2Q7M8N9P0R1S2T3V4W5X6"
}

Con el alcance, el ajuste aparece como una fila más:

{
  "id": "idx_2026-10-19_3f0c2a7e",
  "operationId": null,
  "fecha": "2026-10-19T00:30:00-04:00",
  "fechaValor": "2026-10-19",
  "tipo": "INDEXACION",
  "naturaleza": "AJUSTE_INDEXACION",
  "evento": "INDEXACION_SUBE",
  "fase": "CAPTURADA",
  "efectoSaldo": "CARGO",
  "monto": { "valor": "167.68", "moneda": "VES" },
  "contrato": { "valor": "0.0000", "unidad": "UVC" },
  "indexacion": { "idiAnterior": "4.20535193", "idiNuevo": "4.21876543" },
  "descripcion": "Ajuste por indexación: la deuda en UVC no cambia",
  "puedeDevengar": false,
  "tarjeta": null,
  "comercio": null,
  "codigoRespuesta": null
}

Observa contrato.valor = "0.0000": en UVC la deuda no se movió; solo cambió su valoración en Bs.

Los estados de cuenta siempre lo muestran

El estado de cuenta (GET /v1/accounts/{accountId}/statements/{statementId}, alcance statements:read) siempre incluye el resumen de los ajustes por indexación del período, sin depender de filtros ni del alcance movements:adjustments.

Saldo: dos vistas

GET /v1/accounts/{accountId}/balance (alcance balances:read) devuelve:

contrato: el saldo en la unidad del contrato (UVC o VES), que no cambia con la indexación.
valoracion: el libro en Bs con el que el emisor autoriza. No se recalcula al leer.
valoracion.montoParaCancelarHoy (solo UVC): lo que costaría cancelar la deuda hoy, al IDI del día.

En prepago y en crédito en Bs, ambas vistas coinciden. Si la serie del IDI está atrasada, la respuesta sigue siendo 200 con un aviso en avisos.

Leer movimientos​

Ajustes por indexación: ocultos por defecto​

Saldo: dos vistas​

Leer movimientos

Ajustes por indexación: ocultos por defecto

Saldo: dos vistas