Multi-moneda

Monedas soportadas

moneda acepta el código ISO ("CRC", "USD") o el código interno ("01", "02"). Cada tenant define qué monedas tiene activas: el catálogo se lee de su propia configuración, no de una lista fija.

Qué moneda se usa si no se envía moneda

La moneda principal del tenant, que no siempre es el colón. Un tenant que opera en dólares emite en dólares cuando el campo se omite.

Un tenant puede estar limitado a una sola moneda

Si el tenant no está habilitado para multi-moneda, el comprobante se emite en su moneda principal aunque el request pida otra. Es una garantía del lado del servidor, no un error del request: no se devuelve 400, se emite en la moneda del tenant.

Por eso la respuesta devuelve siempre la moneda con la que realmente se emitió, no el eco de lo enviado. Si se pidió CRC y la respuesta dice USD, el tenant está limitado a dólares y hay que habilitarle multi-moneda.

Tipo de cambio

El tipo de cambio es el parametrizado en el tenant, que un administrador mantiene desde el POS.

{ "moneda": "USD", "tipoCambio": 670.50 }

Si se envía tipoCambio, se respeta el valor enviado — útil cuando el sistema del integrador maneja un tipo de cambio fijo por política.

{ "moneda": "USD" }

Si no se envía, se usa el del tenant. Si el tenant no tiene ninguno definido, la emisión se rechaza: no se inventa un valor ni se consulta una fuente externa, porque un tipo de cambio equivocado queda escrito en un documento fiscal.

{
  "error": "No hay un tipo de cambio definido. Un administrador debe establecerlo desde la barra superior antes de facturar en otra moneda."
}

Precios del catálogo y conversión

Los precios del catálogo están escritos en una sola moneda por tenant, que no necesariamente es la del comprobante.

Cuando una línea no envía precioUnitario, se toma el precio de lista y se convierte a la moneda del comprobante con el tipo de cambio del tenant. Un producto de $4,88 facturado en colones con tipo de cambio 500 sale a ₡2.440.

Cuando la línea sí envía precioUnitario, se respeta tal cual: se asume que ya viene expresado en la moneda que pidió el request, y no se convierte.

Enviar precioUnitario explícito es la forma más predecible de integrar, sobre todo si el sistema del integrador ya maneja sus propios precios.

Notas de crédito y débito: la moneda se hereda

Una NC o ND hereda la moneda y el tipo de cambio del documento que corrige, aunque el request envíe otros o los omita.

Hacienda exige que coincidan con los del documento referenciado y rechaza si no: error -510 para la moneda y -511 para el tipo de cambio. Como el rechazo llega de forma asíncrona, heredar es la única combinación que evita descubrirlo horas después.

Si el documento referenciado no fue emitido por este sistema y no se encuentra, se respeta lo que venga en el request.

Por qué importa

• Hacienda exige que los totales del XML se expresen en la moneda original del comprobante.
• El tipo de cambio queda registrado en el documento: es el que se usa para los reportes en colones.

Ver también: catálogo de monedas · cálculo de totales.