Moneda extranjera

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

commercial_info en dólares

{
  "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

Terminal

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

200 OK

{
  "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:

Terminal

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

200 OK (extracto)

{
  "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:

Terminal

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"

200 OK

{
  "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:

Terminal

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

200 OK

{
  "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

items

[
  {
    "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á.