Mutual Funds - Fondos Comunes de Inversión

Introducción

El módulo de Fondos Comunes de Inversión (FCI) te permite ofrecer a tus usuarios la posibilidad de invertir, consultar y gestionar fondos de Adcap Asset Management directamente desde tu plataforma, sin tener que construir la infraestructura operativa desde cero.

A través de las APIs de API Broker, tu equipo puede integrar en una sola conexión: el listado de fondos disponibles, los valores de cuotaparte en tiempo real, las operaciones de suscripción y rescate, y la consulta de posiciones de cada usuario. La integración es 100% vía API y webhooks, y el soporte de API Broker acompaña todo el proceso, desde el desarrollo hasta el go-live.

Está dirigido a equipos de producto, tecnología y negocio que quieran incorporar FCI como funcionalidad dentro de su app, wallet o plataforma financiera.

Funcionalidades del módulo

Consulta de fondos disponibles

Listado completo de fondos con sus características: nombre, tipo (Renta Fija, Money Market, etc.), moneda, estrategia y horizonte de inversión.

Precios y valores de cuotaparte (VCP)

Valores en tiempo real o al cierre. También permite obtener históricos para mostrar rendimiento o calcular TNA/TEA.

Suscripciones

Tus usuarios pueden invertir en un fondo enviando una solicitud desde su cuenta comitente. La operación se ejecuta con el saldo disponible o, en ciertos casos, desde una cuenta bancaria.

Rescates

Permite solicitar rescates totales o parciales de un fondo. El estado de la orden puede consultarse en tiempo real o recibirse por webhook.

Consulta de posiciones

Tus usuarios pueden ver qué fondos tienen suscriptos, la cantidad de cuotapartes y la valuación actual de su cartera.

Métodos de colocación: ACDI y SIMPLE

Para entender cómo opera el módulo, es clave distinguir los dos métodos de colocación disponibles. El método determina quién ejecuta la suscripción y desde/hacia dónde se mueven los fondos.

Método ACDI

Bajo este esquema, Adcap Securities actúa como Agente de Colocación y Distribución Integral (ACDI) y suscribe el fondo en nombre de los comitentes. Es el método estándar para personas físicas.

• Suscripciones: los fondos se descuentan del saldo disponible en la cuenta comitente del usuario.
• Rescates: los fondos se acreditan en la cuenta comitente del usuario.
• No se admiten transferencias bancarias directas bajo esta modalidad.
• No requiere número de cuotapartista por parte de la gestora.

Método SIMPLE

El propio comitente suscribe directamente al fondo, sin intermediación de un ACDI. Es el método utilizado para personas jurídicas.

• Suscripciones: pueden realizarse desde el saldo de la cuenta comitente o mediante una transferencia bancaria desde una cuenta same-name del usuario.
• Rescates: los fondos pueden acreditarse en la cuenta comitente o transferirse a una cuenta bancaria same-name.
• Requiere que el usuario tenga asignado un número de cuotapartista por parte de la gestora.

Regla general: personas físicas operan por ACDI; personas jurídicas operan por SIMPLE. Para cuentas que cuenten con cuotapartista, ambos métodos son opcionales en el request. Si no se informa method_type, API Broker asigna el método por defecto según las reglas operativas.

Flujo de integración

a. Onboarding de usuarios y cuentas

El onboarding es un prerequisito para operar FCI. El usuario debe tener una cuenta comitente activa antes de poder suscribir o rescatar fondos.

Resultado esperado: person_id, investment_account_id, bank_account_id.

Importante: para personas jurídicas, el sistema genera automáticamente una cuenta cuotapartista además de la cuenta comitente. Esto habilita la operatoria por método SIMPLE.

API Broker notifica de forma asincrónica cuando la cuenta comitente y/o la cuenta cuotapartista fueron creadas:

• Webhook: investment_account_update

b. Ingreso de fondos (Cash In)

El usuario transfiere fondos a una cuenta recaudadora de Adcap Securities (CBU disponible en ARS y USD). A través de la integración bancaria, API Broker identifica el depósito y acredita el saldo en la cuenta comitente.

API Broker notifica al partner con los detalles de la transferencia recibida:

• Webhook: deposit_create
• Incluye: investment_account_id, moneda, monto y fecha de acreditación.

{
  "topic": "deposit_create",
  "items": [{
    "investment_account_id": 43101,
    "currency_id": "ARS",
    "amount": 10.0,
    "trade_date": "2024-09-03",
    "status_id": "COMPLETED",
    "deposit_id": 631184,
    "tax_identification_value": "20415653825"
  }]
}

c. Consulta de fondos y precios

Antes de suscribir, el usuario puede explorar los fondos disponibles y sus valores actuales.

d. Suscripciones

El usuario selecciona un fondo e instruye la suscripción:

POST /market/fund-requests

Campos requeridos:

{
  "investment_account_id": 12345,
  "mutual_fund_id": 10,
  "fund_operation_type": "subscription",
  "currency_id": "ARS",
  "amount": 150000,
  "external_id": "client-op-0001"
}

Campos opcionales (para cuentas con cuotapartista):

e. Rescates

Mismo endpoint que suscripción, cambiando el tipo de operación:

POST /market/fund-requests
fund_operation_type = "redemption"

El rescate puede instruirse por monto (amount) o por cantidad de cuotapartes (share_quantity). Para rescatar por cuotapartes, enviar "by_share_quantity": true.

Casos de uso por método:

Lógica de defaults cuando la cuenta tiene cuotapartista:

f. Consulta de estado de la solicitud

Más allá de los webhooks, es posible consultar en cualquier momento el estado y detalle de una solicitud de FCI directamente por su request_id.

GET /market/fund-requests/{request_id}

Respuestas posibles:

Cuándo usarlo: este endpoint es útil para reconciliación, soporte al usuario o cuando el webhook no fue recibido correctamente. Permite verificar el estado exacto de la operación en cualquier momento.

g. Consulta de boletos / confirmaciones de liquidación

Una vez que una solicitud de suscripción o rescate fue procesada, la gestora genera un boleto (confirmación de liquidación). Estos boletos pueden consultarse para obtener el detalle operativo de la liquidación: cuotapartes, precio, fecha de liquidación y montos.

GET /markets/mutual-fund-confirmations

Parámetros de consulta recomendados:

Casos de uso: mostrar al usuario el comprobante de su operación, realizar conciliación contable, o verificar el precio y cantidad de cuotapartes liquidadas. Los boletos están disponibles una vez que la operación pasa a estado SETTLED.

h. Consulta de estado de cuenta (Account Statement)

Permite obtener el estado de cuenta completo de una cuenta comitente: posición monetaria (saldos disponibles) y tenencias de fondos.

GET /portfolio/account-statements/{investment_account_id}

Parámetros de path:

Parámetros de query opcionales:

Respuestas:

Cuándo usarlo: para mostrar al usuario su saldo disponible antes de suscribir, o para mostrar el detalle de su cartera de FCI con valuación actualizada.

i. Retiros (Cash Out)

Una vez que el rescate se encuentra liquidado (status = SETTLED), el partner puede instruir el retiro de los fondos a una cuenta bancaria del usuario.

POST /withdraw-requests

Los retiros son asincrónicos. API Broker notifica los cambios de estado vía webhook:

• Webhook: withdraw_request_update
• Estados: IN_PROGRESS → COMPLETED / REJECTED

{
  "topic": "withdraw_request_update",
  "items": [{
    "amount": 100,
    "status_id": "COMPLETED",
    "currency_id": "ARS",
    "bank_account_id": 121535,
    "withdraw_request_id": 984479,
    "investment_account_id": 74659
  }]
}

Endpoints principales

Webhooks a implementar

Tu plataforma debe exponer una URL para recibir los siguientes eventos:

deposit_create

Se dispara cuando API Broker acredita un depósito en la cuenta comitente de un usuario. Incluye investment_account_id, moneda, monto y fecha de acreditación.

investment_account_update

Se dispara cuando la cuenta comitente y/o la cuenta cuotapartista son creadas en el ALyC o en la Sociedad Gestora. Permite saber cuándo el usuario está habilitado para operar.

withdraw_request_update

Se dispara ante cada cambio de estado de un retiro. Incluye estado actualizado (IN_PROGRESS, COMPLETED, REJECTED), monto y cuenta destino.

Puntos clave para recordar

1. El onboarding es prerequisito: el usuario necesita una investment_account_id activa para operar FCI.
2. Las PJ tienen cuotapartista automático: esto habilita el método SIMPLE y la operatoria desde/hacia cuenta bancaria.
3. ACDI y SIMPLE no son intercambiables libremente: si el usuario no tiene cuotapartista, solo puede operar por ACDI.
4. method_type es opcional pero importante: si no se envía, API Broker asigna el default según las reglas operativas. Entender esas reglas evita comportamientos inesperados.
5. bank_account_id solo funciona con SIMPLE: no es compatible con el método ACDI.
6. Los retiros requieren fondos liquidados: no se puede instruir un retiro hasta que el rescate tenga status = SETTLED.
7. Los webhooks son obligatorios: deposit_create y withdraw_request_update son eventos críticos del flujo. Tu plataforma debe tener una URL disponible para recibirlos.
8. external_id previene duplicados: siempre enviar un identificador único por operación para evitar doble procesamiento.