Reference

Catálogos

Endpoints de consulta para CABYS, ubicaciones, tablas de códigos de Hacienda, contribuyentes y tipo de cambio.

This content is not available in your language yet.

Aster expone los catálogos que necesitás para armar un comprobante válido. Los endpoints de /reference/* y /hacienda/taxpayers son públicos: no requieren llave, así que podés usarlos para llenar formularios en tu sistema. Los de tipo de cambio requieren una llave con el permiso reference:read.

Todas las rutas son relativas a https://aster.astranexo.com/api/v1.

Límites de los endpoints públicos

Las rutas sin autenticación se limitan por dirección IP, por minuto:

Ruta	Solicitudes por minuto e IP
`/reference/*`	300
`/hacienda/taxpayers`	60
`/status`	120
`POST /auth/token`	10

Al superar el límite la respuesta es 429 rate_limited con Retry-After. Si necesitás consultar mucho un catálogo, guardalo en caché de tu lado: el CABYS y las ubicaciones cambian pocas veces al año.

CABYS

El Catálogo de Bienes y Servicios (CABYS) clasifica cada línea de un comprobante. Cada código tiene 13 dígitos; el primero indica si es un bien (0–4) o un servicio (5–9), y Aster usa ese dígito para clasificar la línea en los totales. La unidad de medida tiene que ser coherente con ese capítulo: Sp, Os, Spe, St y Al son unidades de servicio.

Método	Ruta	Uso
`GET`	`/reference/cabys?q=…`	Búsqueda por texto. `q` mínimo 2 caracteres, `limit` de 1 a 100 (50 por defecto), `match_any=1` para buscar cualquiera de las palabras
`GET`	`/reference/cabys/{code}`	Un código
`GET`	`/reference/cabys/categories`	Categorías de primer nivel (`?type=producto` o `?type=servicio`)
`GET`	`/reference/cabys/browse`	Navegación por categoría (`?category_1=…&category_2=…`)
`POST`	`/reference/cabys/batch`	Hasta 50 códigos en una solicitud

curl "https://aster.astranexo.com/api/v1/reference/cabys?q=tornillos%20madera&limit=2"

{
  "success": true,
  "data": [
    {
      "id": 11969,
      "code": "4294401030100",
      "category_1": "4",
      "description_1": "Productos metálicos, maquinaria y equipo",
      "category_2": "42",
      "description_2": "Productos de metal elaborados, excepto maquinaria y equipo",
      "category_3": "429",
      "description_3": "Productos metálicos elaborados, n.c.p.",
      "description_9": "Tornillos para madera, de hierro o acero",
      "tax_rate": "13%",
      "rank": 0.0991
    },
    {
      "id": 11970,
      "code": "4294401030200",
      "category_1": "4",
      "description_1": "Productos metálicos, maquinaria y equipo",
      "category_2": "42",
      "description_2": "Productos de metal elaborados, excepto maquinaria y equipo",
      "category_3": "429",
      "description_3": "Productos metálicos elaborados, n.c.p.",
      "description_9": "Tornillos taladradores, de hierro o acero",
      "tax_rate": "13%",
      "rank": 0.0607
    }
  ]
}

description_9 es la descripción del código final y tax_rate es la tarifa de IVA que el catálogo le asigna. Si tax_rate es Exento, la línea se factura con la tarifa 10 (Tarifa Exenta); Aster rechaza otras tarifas del 0 % para ese código porque Hacienda las rechaza (-483, -485).

curl https://aster.astranexo.com/api/v1/reference/cabys/batch \
  -H "Content-Type: application/json" \
  -d '{ "codes": ["4423201000100", "4292199990200"] }'

Las partidas arancelarias, para las facturas de exportación, tienen endpoints equivalentes en /reference/tariff-codes.

Ubicaciones

Los códigos de provincia, cantón, distrito y barrio que pide la dirección del emisor y del receptor:

Ruta	Devuelve
`/reference/provinces`	Las 7 provincias
`/reference/cantons/{province}`	Cantones de una provincia
`/reference/districts/{province}/{canton}`	Distritos de un cantón
`/reference/neighborhoods/{province}/{canton}/{district}`	Barrios de un distrito
`/reference/address-search?q=…`	Búsqueda por nombre en todos los niveles, sin importar tildes

curl "https://aster.astranexo.com/api/v1/reference/address-search?q=guadalupe"

{
  "success": true,
  "data": [
    {
      "type": "district",
      "id": 54,
      "primary_text": "Guadalupe",
      "secondary_text": "Goicoechea, San José",
      "province": { "id": 1, "code": "1", "name": "San José" },
      "canton": { "id": 8, "code": "08", "full_code": "108", "name": "Goicoechea" },
      "district": { "id": 54, "code": "01", "full_code": "010801", "name": "Guadalupe" },
      "neighborhood": null
    }
  ]
}

En el comprobante se envían los campos code: "province": "1", "canton": "08", "district": "01".

Tablas de códigos

Tablas de las notas técnicas de Hacienda, útiles para llenar listas desplegables. Cada elemento trae code y name.

Ruta	Contenido
`/reference/document-types`	Tipos de comprobante: `01` FE, `02` ND, `03` NC, `04` TE, `08` FEC, `09` FEE, `10` REP
`/reference/payment-methods`	Medios de pago `01`–`07` y `99`, incluidos `06` SINPE Móvil y `07` Plataforma Digital
`/reference/sale-conditions`	Condiciones de venta `01`–`15` y `99`
`/reference/tax-rates`	Códigos de tarifa de IVA con su porcentaje
`/reference/economic-activities`	Actividades económicas frecuentes
`/reference/reference-codes`	Códigos de referencia (Nota 9) `01`–`17` y `99`, incluidos los códigos `13`–`17` obligatorios desde el 1 de noviembre de 2026. Cada uno trae una `note` con su efecto contable
`/reference/reference-doc-types`	Tipos de documento de referencia (Nota 10) `01`–`20` y `99`

curl https://aster.astranexo.com/api/v1/reference/payment-methods

{
  "success": true,
  "data": [
    { "code": "01", "name": "Efectivo" },
    { "code": "02", "name": "Tarjeta" },
    { "code": "03", "name": "Cheque" },
    { "code": "04", "name": "Transferencia / Depósito Bancario" },
    { "code": "05", "name": "Recaudado por terceros" },
    { "code": "06", "name": "SINPE Móvil" },
    { "code": "07", "name": "Plataforma Digital" },
    { "code": "99", "name": "Otros" }
  ]
}

Contribuyentes

GET /hacienda/taxpayers busca en el registro de contribuyentes de Hacienda, con actualización desde consultas en vivo a Hacienda: si una cédula no está en el registro de Aster, Aster la consulta a Hacienda y guarda la respuesta. Sirve para autocompletar el nombre del receptor a partir de su cédula.

Parámetro	Descripción
`cedula`	Identificación, solo dígitos (o dígitos y mayúsculas en cédulas jurídicas alfanuméricas). Alias `id`, `identification`
`nombre`	Búsqueda por nombre, mínimo 2 caracteres. Requerido si no hay `cedula`
`apellidos`	Búsqueda por apellidos
`tipo`	`F` (persona física) o `J` (persona jurídica)
`exact_match`	`true` para coincidencia exacta

curl "https://aster.astranexo.com/api/v1/hacienda/taxpayers?cedula=3101654321"

{
  "success": true,
  "data": {
    "cedulas_fisicas": [],
    "cedulas_juridicas": [
      { "cedula": "3101654321", "razon_social": "FERRETERIA LA SABANA S.A." }
    ]
  }
}

curl "https://aster.astranexo.com/api/v1/hacienda/taxpayers?nombre=laura&apellidos=jimenez%20mora&tipo=F"

{
  "success": true,
  "data": {
    "cedulas_fisicas": [
      { "cedula": "109870654", "nombre": "LAURA", "primer_apellido": "JIMENEZ", "segundo_apellido": "MORA" }
    ],
    "cedulas_juridicas": []
  }
}

La búsqueda por nombre no distingue tildes ni mayúsculas. Antes de emitir, Aster verifica por su cuenta que el emisor y el receptor estén inscritos (error -38 de Hacienda); no hace falta que lo consultés vos.

Tipo de cambio

Para comprobantes en moneda extranjera necesitás el tipo de cambio en commercial_info.exchange_rate. Aster expone el tipo de cambio de referencia del Banco Central de Costa Rica (BCCR) y el de ventanilla de cada entidad autorizada. Estos endpoints requieren una llave con reference:read.

Ruta	Devuelve
`GET /exchange-rates`	Tipo de cambio de referencia del día (compra y venta)
`GET /exchange-rates/historical?date=AAAA-MM-DD`	Tipo de cambio de referencia del BCCR para una fecha pasada. Fines de semana y feriados devuelven el último día hábil anterior
`GET /exchange-rates/pair?from=USD&to=CRC`	Un par de monedas. Con `&entity=…`, el tipo de cambio de ventanilla de ese banco
`GET /exchange-rates/entities`	Tipo de cambio de ventanilla de cada banco, cooperativa, casa de cambio y puesto de bolsa

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

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

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

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

rate es igual a sell.
Usá en entity el nombre exacto que devuelve /exchange-rates/entities.
fallback: true significa que no hubo dato de ese banco y respondió el tipo de cambio de referencia del BCCR. Si necesitás específicamente el de ese banco, tratalo como “no disponible”.
stale: true significa que la fuente en vivo no respondió y el dato es la última copia guardada; date dice de qué día es. Para un banco solo se usa una copia de 7 días o menos.

El tipo de cambio de referencia también se puede ver sin llave en /exchange-rates.