Guides

Moneda extranjera

Emití comprobantes en dólares u otras monedas con el tipo de cambio correcto, usando las tasas del BCCR o de un banco específico.

This content is not available in your language yet.

Podés emitir cualquier comprobante en una moneda distinta del colón. Todos los montos del cuerpo (precios, descuentos, cargos) van en la moneda del documento, y Hacienda recibe además el tipo de cambio a colones.

Los dos campos

Campo	Regla
`commercial_info.currency`	Código ISO 4217. Aster acepta `CRC`, `USD`, `EUR`, `GBP`, `JPY`, `CAD` y `CHF`. Si lo omitís, se asume `CRC`
`commercial_info.exchange_rate`	Colones por una unidad de la moneda del documento. Obligatorio si la moneda no es `CRC`; con `CRC` se omite o se envía `1`

{
  "currency": "USD",
  "exchange_rate": 506.40,
  "sale_condition": "01",
  "payment_method": "02"
}

exchange_rate puede ir como número o como texto ("506.40"). Si la moneda no es colones y falta el tipo de cambio, la API responde 422 en commercial_info.exchange_rate. Si la moneda es colones y enviás un tipo de cambio distinto de 1, también.

Los totales quedan en la moneda del documento

Aster calcula líneas, impuestos y resumen en la moneda que declaraste. Una factura de USD 100 con IVA del 13 % tiene un total de USD 113, no de ₡57 223. Los campos de monto que devuelve GET /electronic-documents/{clave} (total_amount, tax_amount, net_amount) también están en esa moneda, junto a currency.

El PDF muestra los totales en la moneda del documento y su equivalente en colones con el tipo de cambio declarado.

Qué tipo de cambio usar

La referencia habitual es el tipo de cambio de venta del Banco Central (BCCR) del día de emisión. Si tu política contable usa la tasa de un banco específico, también podés consultarla. En cualquier caso, guardá la tasa que usaste junto al comprobante: es la que queda en el XML.

Tipo de cambio de referencia del BCCR

curl https://aster.astranexo.com/api/v1/exchange-rates \
  -H "Authorization: Bearer aster_test_8KfQ2mVx3TzL9pRw"

{
  "success": true,
  "data": {
    "buy": 499.85,
    "sell": 506.40,
    "date": "2026-10-08",
    "source": "hacienda",
    "entity": "BCCR"
  }
}

Usá sell como exchange_rate.

Tipo de cambio de un banco

Primero listá las entidades con su tasa de ventanilla del día:

curl https://aster.astranexo.com/api/v1/exchange-rates/entities \
  -H "Authorization: Bearer aster_test_8KfQ2mVx3TzL9pRw"

{
  "success": true,
  "data": [
    { "entity": "Banco BAC San José S.A.", "buy": 498.00, "sell": 508.00, "date": "2026-10-08", "provider": "ventanilla" },
    { "entity": "Banco Nacional de Costa Rica", "buy": 499.00, "sell": 507.00, "date": "2026-10-08", "provider": "ventanilla" }
  ]
}

Guardá el valor de entity tal como viene y usalo para pedir el par de monedas de ese banco:

curl "https://aster.astranexo.com/api/v1/exchange-rates/pair?from=USD&to=CRC&entity=Banco%20BAC%20San%20Jos%C3%A9%20S.A." \
  -H "Authorization: Bearer aster_test_8KfQ2mVx3TzL9pRw"

{
  "success": true,
  "data": {
    "from": "USD",
    "to": "CRC",
    "buy": 498.00,
    "sell": 508.00,
    "rate": 508.00,
    "date": "2026-10-08",
    "source": "ventanilla",
    "entity": "Banco BAC San José S.A.",
    "fallback": false,
    "stale": false
  }
}

rate es igual a sell. Revisá dos indicadores antes de usarla:

Campo	Significado
`fallback: true`	La tasa de ese banco no estaba disponible y respondió la cadena de referencia del BCCR; `entity` muestra la fuente real. Si necesitás la tasa de ese banco, tratalo como “no disponible”
`stale: true`	La fuente en vivo no respondió y se usó la última tasa guardada de ese banco, de hasta 7 días. `date` indica de qué día es

Sin entity, /exchange-rates/pair devuelve la tasa de referencia del BCCR.

Tipo de cambio de una fecha pasada

Para un comprobante con fecha pasada, como una Factura de Compra de una compra de semanas atrás, usá el tipo de cambio de esa fecha:

curl "https://aster.astranexo.com/api/v1/exchange-rates/historical?date=2026-09-15" \
  -H "Authorization: Bearer aster_test_8KfQ2mVx3TzL9pRw"

{
  "success": true,
  "data": { "buy": 500.12, "sell": 507.03, "date": "2026-09-15", "source": "bccr", "entity": "BCCR" }
}

El histórico viene del BCCR. Para fines de semana y feriados, el BCCR repite la tasa del último día hábil. Una fecha futura o mal formada responde 400; si la tasa no se puede obtener, buy y sell vienen en 0 con un campo note que explica el motivo.

Los tres endpoints requieren el permiso reference:read.

Ejemplo de línea en dólares

[
  {
    "line_number": 1,
    "cabys_code": "8314300000000",
    "quantity": 1,
    "unit": "Os",
    "description": "Desarrollo de módulo de inventario, setiembre 2026",
    "price": 1500.00,
    "tax": [
      { "type": "01", "rate_code": "08", "rate": 13 }
    ]
  }
]

Con exchange_rate: 506.40, el comprobante declara un total de USD 1 695,00 (1 500 + 195 de IVA), equivalente a ₡858 348.

Ejemplos por tipo de documento

Factura de Compra en dólares a un proveedor del exterior.
Factura de Exportación en dólares a un comprador en Panamá.