Saltar a contenido

Traza del motor de divisas (FX)

Para auditar o depurar cómo se construye una cifra de divisa (casillas 1633/1637), DeclaRenta puede emitir una traza completa de los movimientos internos del motor FX: el libro mayor acquire → park → unpark → discard → profit → dispose, con el saldo del pool gastable y del principal aparcado tras cada paso. Permite reconstruir lote a lote, con tus propios datos, cómo se llegó a cada importe. Es una herramienta para usuarios avanzados y asesores; disponible desde la v0.52.0.

Está desactivada por defecto y nunca aparece en la interfaz normal (coste cero cuando está apagada).

En la web (modo diagnóstico)

El modo diagnóstico se activa de dos formas:

  • Añadiendo #debug a la URL: https://declarenta.com/#debug
  • O, de forma persistente, en la consola del navegador: localStorage.declarenta_debug = "1" y recargar.

El orden importa: la traza solo se calcula si el modo diagnóstico está activo al generar el informe. Receta fiable:

  1. Entra directamente en https://declarenta.com/#debug.
  2. Sube tus ficheros y genera el informe.
  3. Pulsa «Descargar traza de cálculo FX (diagnóstico)» → se descarga declarenta_fxtrace_<año>.csv.

En modo monodivisa, o si no hay movimientos de divisa, el botón avisa de que «no hay movimientos FX que trazar».

En la CLI

# Traza a un fichero, en CSV
node dist/cli.js convert --input flex_query.xml --year 2025 --fx-trace traza.csv --fx-trace-format csv

# Traza a stderr (sin ruta), en JSONL (por defecto)
node dist/cli.js convert --input flex_query.xml --year 2025 --fx-trace
  • --fx-trace [fichero] — sin valor vuelca a stderr; con una ruta, escribe el fichero (nunca contamina la salida estándar del informe).
  • --fx-trace-format jsonl|csv — jsonl (por defecto: una línea JSON por evento, ideal para máquinas/tests) o csv (tabla legible).

Formato de la traza

Cada fila es un movimiento del motor, con estas columnas:

Columna Significado
seq Número de orden del movimiento
date Fecha del evento
kind Tipo de movimiento (ver abajo)
currency Divisa (p. ej. USD)
trigger Origen del movimiento (conversión, dividendo, interés, compra/venta de valor…)
quantityFcy Cantidad de divisa movida
rate Tipo de cambio aplicado (EUR por 1 unidad de divisa)
costBasisEur Valor de adquisición en EUR
proceedsEur Valor de transmisión en EUR
gainLossEur Ganancia/pérdida FX realizada (solo en dispose)
poolBalanceFcy Saldo de divisa «gastable» tras el movimiento
parkedBalanceFcy Saldo de principal aparcado (en posiciones aún abiertas)
positionKey Posición a la que pertenece el principal aparcado
lotId Lote afectado. En acquire, unpark y profit es el lote creado; en park y dispose, el lote consumido (UNKNOWN = sin lote previo suficiente → ganancia FX forzada a 0). Vacío en discard y en un park que no sale de un lote de la pool (sin origen rastreado, o de un lote manual). Es un contador de orden de creación, compartido entre divisas — NO indica el orden FIFO.
lotAcquireDate Fecha de adquisición del lote de lotId. En unpark es la fecha original que conserva el principal (la de la venta si no había compra rastreada); en profit, la de la venta; en el park de un lote manual, la de ese lote. Esta es la prueba del FIFO: en dispose consecutivos de una misma divisa es no decreciente (se consume siempre el dólar más antiguo primero).
note Aclaración del movimiento
brokerSource Broker del fichero del que sale el movimiento (vacío si no consta)

Por qué lotId (FX-N) no va en orden ascendente: el número de lote se asigna al crearse el lote y es único para todas las divisas. Cuando vendes un valor en divisa, su principal vuelve a la pool conservando su fecha de adquisición original (antigua) pero con un número de lote nuevo (distinto, no necesariamente mayor), e insertado en su posición por fecha — así que una conversión puede consumir FX-5 antes que FX-2 si FX-5 es más antiguo por fecha. Eso es FIFO correcto. La columna que hay que mirar para verificarlo es lotAcquireDate, no lotId.

Para ver dónde nació un lote, busca la fila acquire, unpark o profit con el mismo lotId: cada lote que consume un dispose o un park aparece antes en una de ellas, con la misma divisa y la misma lotAcquireDate. Un principal re-añadido en unpark lleva número nuevo, así que su park de origen no se encuentra por lotId. Búscalo entre los park de la misma divisa y positionKey: las ventas devuelven los tramos aparcados de una posición en el mismo orden en que se aparcaron (el primero aparcado es el primero devuelto), y un park puede repartirse entre varios unpark o al revés, así que empareja por ese orden y por quantityFcy. positionKey y lotAcquireDate no bastan: dos lotes de la misma fecha aparcados en la misma posición dan dos park con los mismos valores.

Tipos de movimiento (kind):

kind Qué representa
acquire Entra divisa al pool (conversión EUR→divisa, dividendo o interés recibido)
dispose Sale divisa y se realiza la ganancia/pérdida FX (conversión divisa→EUR)
park Una compra de valor en divisa consume divisa del pool y aparca su coste de adquisición
unpark Una venta re-añade al pool el principal aparcado, a su coste original
discard Principal perdido en una venta con minusvalía (esa divisa nunca se convirtió a EUR)
profit El beneficio de una venta entra como divisa nueva, al tipo de la fecha de venta