BuscaFondosDevelopers
Documentación

Changelog

Cambios públicos del portal y del contrato de la API. Cada entrada indica fecha efectiva, endpoints o modelos afectados, compatibilidad hacia atrás, acción requerida y enlace a la referencia actualizada.

2026-10-08: Fondos de inversión y ETF

Impacto: aditivo para quien consume fondos mutuos con los parámetros por defecto, con un cambio de tipo en el contrato: asset_id de las rutas /api/real_assets/{asset_id}/* pasa de integer a string. Acción requerida: si generas un SDK desde OpenAPI, regenéralo y trata asset_id y serieId como texto. Los IDs numéricos de fondos mutuos siguen funcionando igual. Si pides vehicle=etf, investment_fund o all, considera que serieId puede ser un UUID.

Endpoints nuevos

Los cinco requieren X-Api-Key y están disponibles en el playground. Pertenecen al área Investment Funds, que todavía no está declarada en la lista de tags del contrato. Las tres primeras devuelven un objeto meta con generated_at y expires_at; el catálogo y los precios agregan total, limit y offset. Las rutas de cartera usan otro meta, descrito abajo.

  • GET /api/fi/instruments: catálogo de fondos de inversión y ETF. Filtra por provider_id, is_etf, regulatory_type (FIRES o FINRE), status (active por defecto, inactive, unknown o all) y q (nombre, ticker o RUN). Pagina con limit (100 por defecto, máximo 500) y offset.
  • GET /api/fi/instruments/{instrument_id}: detalle de un instrumento por UUID, con su clasificación regulatoria, la última cuota y los bloques fact_sheet, article107, patrimony y tac tomados de la ficha CMF. tac.status indica la situación del dato: available, pending_review, not_checked, stale, not_reported o unavailable_or_conflict.
  • GET /api/fi/instruments/{instrument_id}/prices: historial de valores libro CMF, con valor económico, patrimonio y aportantes por fecha. Filtra con from_date y to_date (YYYY-MM-DD) y pagina con limit (1.000 por defecto, máximo 5.000) y offset. Un rango con from_date posterior a to_date responde 422.
  • GET /api/fi/instruments/{instrument_id}/cartera/holdings y /cartera/resumen: cartera trimestral del fondo, por posición o agrupada por tipo de instrumento. Aceptan month (YYYY-MM) y market (N nacional, E extranjero o all, por defecto). Sin month, usan el último período con posiciones observadas y responden 404 si el fondo no tiene ninguno. Con un month sin datos responden 200 con data: []. Un month mal formado responde 400. meta informa run, month, availability (available o unavailable para N y E), sources, valuation_unit: "cmf_reported" y percentage_unit: "percent_of_fund_assets".

Un instrumento que no está publicado responde 404. Si el servicio de fondos de inversión no está disponible, estas rutas responden 503.

Endpoints modificados

  • GET /api/all-funds: nuevo parámetro vehicle con mutual_fund (por defecto), etf, investment_fund (fondos de inversión rescatables que no son ETF) o all. Sin vehicle, la respuesta sigue siendo el universo de fondos mutuos; cada fila agrega el campo vehicle.
    • En filas ETF y de fondos de inversión, serieId es un UUID, fundId tiene la forma fi:{run}, price es el último valor libro CMF (price_basis: "valor_libro") y price_status indica si la cuota está al día (current), atrasada (stale) o ausente (unavailable). Cuando la cuota no está al día, dailyChange y monthlyChange son null. category, fundFamily, investorClass, article107RegulationStatus y seriesContinuity son null, así que los filtros category, fund_family y article107_regulation_status las excluyen. Sin date, tac es null cuando no hay una ficha CMF revisada y vigente, y solo se listan instrumentos con estado CMF activo.
    • Con vehicle=etf o investment_fund, meta.date y meta.previousDate son la fecha de corte de fondos de inversión y ETF, meta.agfCount es 0 y el conteo de administradoras va en etfAgfCount o investmentFundAgfCount.
    • Con vehicle=all, meta.date, meta.previousDate y meta.agfCount conservan los valores de fondos mutuos; meta agrega etfAgfCount, investmentFundAgfCount y datesByVehicle (ETF y fondos de inversión comparten la misma fecha de corte).
    • Cualquier vehicle distinto de mutual_fund, incluido all, responde 503 si los datos de fondos de inversión no están disponibles. En ese caso tampoco se entregan las filas de fondos mutuos; usa el valor por defecto si solo necesitas fondos mutuos.
  • GET /api/asset_providers: nuevo parámetro scope. Con scope=all incluye las administradoras de fondos de inversión, agrega coverage (FM, ETF, FI) a cada administradora y rut, displayName, slug, instrument_count y fund_count a las que tienen fondos de inversión o ETF. La respuesta agrega meta con generated_at y expires_at. Sin scope, la respuesta no cambia. Con scope=all puede responder 503 si el servicio de fondos de inversión no está disponible; declara 422 para valores inválidos.
  • /days, /returns, /expense_ratio, /expense_ratio/history y /risk_metrics bajo /api/real_assets/{asset_id}: asset_id acepta el ID numérico de una serie de fondo mutuo o el UUID de un ETF o fondo de inversión.
    • Un UUID que no corresponde a un instrumento publicado responde 404. Si los datos de fondos de inversión no están disponibles, estas rutas responden 503.
    • /days entrega valores libro CMF en la moneda contable del instrumento; cada día agrega currency, price_source: "cmf" y price_basis: "valor_libro".
    • /returns usa las mismas ocho ventanas y declara quota_source: "cmf_valor_libro". Para estos instrumentos solo admite return_basis=price: total responde 422, o 503 mientras la base total no esté habilitada. Las series en monedas sin conversión disponible (por ejemplo COP) entregan ventanas null con motivo unknown_currency.
    • /expense_ratio responde 200 con expense_ratio: null cuando no hay TAC documentada, y /expense_ratio/history responde data: [] sin observaciones. /risk_metrics entrega el último cálculo de riesgo, con unavailable_reason cuando no se puede calcular (por ejemplo unknown_currency).

Modelos

  • quota_source en ReturnAttributes, FundReturnAttributes y AdjustedReturnAttributes pasa de la constante CMF a un enum: CMF, market_close o cmf_valor_libro. Hoy las respuestas usan CMF para fondos mutuos y cmf_valor_libro para fondos de inversión y ETF. TotalReturnAttributes mantiene la constante CMF.
  • En los modelos de rentabilidad, algunos minimum y maximum enteros se publican ahora como 0.0 y 31.0. Es un cambio de serialización, no de contrato.
  • WatchlistRequest (rutas de cuenta, fuera de la API pública): serie_id admite hasta 36 caracteres para aceptar UUID de ETF.

Alcance

  • /api/compare, /api/screener, las estadísticas por administradora y los rankings por familia siguen cubriendo solo fondos mutuos.
  • Las rutas de cartera /api/funds/{run}/cartera/* no resuelven ETF ni fondos de inversión; usa las rutas de cartera bajo /api/fi/instruments.
  • Las respuestas de las rutas /api/fi/* no declaran schema en OpenAPI y no traen ejemplo. Los campos descritos en esta entrada provienen del comportamiento del backend, no del contrato publicado.

2026-10-02: Continuidad de series renombradas

Impacto: aditivo en el contrato, con cambio de comportamiento en /days, /returns, /compare, /screener y /all-funds para las series renombradas. Acción requerida: si guardas IDs de series BCI renombradas, puedes seguir usándolos como entrada. Si cruzas respuestas por ID, considera que /compare, /screener y /all-funds devuelven el ID vigente; usa seriesContinuity.aliasIds para mapear el ID anterior.

Comportamiento

  • La API reconoce 18 series BCI que la CMF publicó con una etiqueta nueva desde el 24 de septiembre de 2026. Ambos IDs de serie, el anterior y el vigente, resuelven a la misma identidad. Los valores cuota no se modifican. Las series Familia (FAMIL) absorbidas por otra serie no se vinculan: su historia termina el 23 de septiembre de 2026 y sigue separada.
  • GET /api/real_assets/{asset_id}/days entrega la misma secuencia continua con cualquiera de los dos IDs y conserva el ID solicitado en los recursos.
  • GET /api/real_assets/{asset_id}/returns calcula sobre el historial continuo, conserva el ID solicitado e informa la etiqueta de serie vigente a la fecha de corte.
  • GET /api/compare acepta los IDs anteriores. Si pides el ID anterior y el vigente de una misma serie, la respuesta trae una sola serie canónica, con el ID vigente, así que puede tener menos elementos que los IDs solicitados.
  • GET /api/screener lista una sola fila por serie renombrada, con el ID vigente.
  • GET /api/all-funds lista una sola fila por serie renombrada, con el ID vigente y variaciones diaria y mensual que cruzan el cambio de etiqueta. Agrega los campos price_as_of_date (fecha del valor cuota) y seriesContinuity. El schema de esta respuesta sigue sin declararse en OpenAPI.

Modelos

  • Nuevo: SeriesContinuity, con type (hoy solo rename), previousSerie, currentSerie, firstCurrentDate (primera fecha observada con la etiqueta nueva) y aliasIds (ID vigente primero, luego el anterior).
  • MarketAttributes, usado por /api/compare y /api/screener, agrega seriesContinuity opcional y nullable. Es null cuando la serie no tiene renombre.

2026-10-01: Nueva cuota del tier free

Impacto: restrictivo para las keys del tier free. Acción requerida: revisa tu consumo diario con GET /api/key/info. Si supera 300 requests, optimiza o solicita más cuota.

  • La cuota diaria del tier free baja de 5.000 a 300 requests/día. Aplica a las keys nuevas y a las existentes. Las keys no cambian y siguen funcionando.
  • El tier institutional (referencia: 25.000 requests/día) y el límite por IP de 10 requests/segundo (ráfagas de 20) no cambian.
  • Si necesitas más cuota, escribe a api@buscafondos.com indicando tu requerimiento (requests diarias estimadas, endpoints y frecuencia) y tu justificación (caso de uso y por qué la cuota free no alcanza).
  • La tabla completa y recomendaciones para rendir la cuota están en límites por tier.

2026-09-06: Rentabilidades, comparador y screener

Impacto: aditivo. Ningún endpoint existente cambia de forma incompatible. Acción requerida: ninguna.

Endpoints nuevos

Los tres requieren X-Api-Key y están disponibles en el playground.

  • GET /api/real_assets/{asset_id}/returns: rentabilidades de una serie en ocho ventanas (1m, 3m, 6m, 1y, ytd, 3y_ann, 5y_ann, last_closed_month), en fracción decimal, con fecha de corte y motivo cuando una ventana no está disponible. valuation acepta accounting (por defecto), clp o real_uf; return_basis acepta price (por defecto) o total. Las bases ajustadas responden 503 mientras no estén habilitadas.
  • GET /api/compare: compara entre una y diez series del último lote publicado, conservando el orden solicitado. series recibe IDs decimales de serie separados por comas. Entrega retornos de precio en moneda contable, datos del catálogo y esferas CMF, con comparabilidad por período y de esferas informadas por separado. Responde 404 si un ID no pertenece al universo publicado y 422 si la lista es inválida, tiene duplicados o supera diez series.
  • GET /api/screener: filtra el último lote publicado por nombre o RUN, familia, clase de inversionista, moneda, categoría, administradora, rango de esferas CMF y familia o tipo de inversionista CMF. sort admite id, tac, cmf_spheres y las ocho ventanas de rentabilidad; ordenar por retorno requiere currency y ordenar por esferas requiere cmf_family y cmf_investor_type. Pagina con limit (1 a 200) y offset; el paginado es estable dentro del mismo lote.

Endpoints modificados

  • GET /api/all-funds: declara la respuesta 503 que ya producía cuando la base cambia entre dos lecturas consecutivas. Reintenta respetando Retry-After. Su descripción ahora explica que coalesce misses por respuesta efectiva.

Modelos

  • Nuevos: FundReturnResponse, AdjustedReturnResponse, TotalReturnResponse y sus recursos, atributos y ventanas (ReturnPeriods, ReturnPeriod, CmfSpheres, AppliedDistribution, AppliedExchange, FactorCoverage, EndpointInputs, IndicatorInput, PeriodInputs, entre otros).
  • Nuevos para el comparador y el screener: CompareResponse, CompareMeta, ScreenerResponse, ScreenerMeta, ReturnAttributes, MarketAttributes, MarketResource, PeriodComparability, ReturnComparability y SpheresComparability.
  • Article107EvidenceResponse agrega el campo requerido seriesException.
  • AlertPreferenceRequest (rutas de cuenta, fuera de la API pública): email_opt_in_alerts pasa a ser opcional y nullable, y se agrega email_opt_in_monthly_summary.
  • info.contact del contrato apunta a api@buscafondos.com.

Notas del contrato

  • /api/compare y /api/screener pertenecen al área nueva Fund Returns, declarada en el contrato con su descripción. Ambos declaran 503 cuando el lote publicado no existe o es inválido; reintenta respetando Retry-After.
  • El comparador no incluye historia diaria y el screener no incluye metadatos de comparabilidad. Las esferas CMF no equivalen a rentabilidad ajustada por riesgo.