FAQs

Documentación de referencia para clientes B2B. Cubre los escenarios operativos más frecuentes en las áreas de onboarding, movimientos de fondos, órdenes, tenencias, webhooks y normativa vigente. Ante cualquier caso que no esté contemplado aquí, el equipo de Customer Experience de API Broker está disponible para asistirlos.

📋 Tabla de Contenidos

• 🧾 Onboarding y Apertura de Cuentas
• 💸 Depósitos
• 🏦 Retiros (Extracciones)
• 📦 Solicitudes de Fondos (Fund Requests)
• 📊 Tenencias (Holdings) y Plazos de Liquidación
• 🔔 Webhooks

🧾 Onboarding y Apertura de Cuentas

¿Cuál es el flujo correcto para dar de alta una cuenta de inversión?

El orden de los pasos es estricto y debe respetarse para que el alta se complete correctamente:

1. POST v2/persons — Alta de la persona (se obtiene el person_id)
2. POST identity-documents — Carga de documentos de identidad (frente de DNI, dorso de DNI y selfie)
3. POST v2/investment-accounts — Creación de la cuenta comitente (se obtiene el investment_account_id)
4. POST bank-accounts — Alta de la cuenta bancaria para poder realizar extracciones

⚠️

Si se intenta crear la cuenta de inversión sin haber cargado previamente los documentos de identidad, el alta se cancelará con el error missing_attached_documents.

¿Por qué un usuario completó el proceso pero no tiene número de comitente asignado?

En algunos casos, la apertura de la cuenta puede quedar en revisión manual por parte de nuestro equipo de Compliance. Esto ocurre cuando el perfil del usuario es identificado como Sujeto Obligado (SO), Persona Expuesta Políticamente (PEP) o presenta un nivel de riesgo medio/alto que requiere validación adicional antes de habilitar la operatoria.

Este proceso es parte del flujo normal de aprobación. Si detectan usuarios en esta situación, pueden reportarlo a nuestro equipo indicando el CUIT del usuario y la fecha de inicio del proceso para que podamos informar el estado de la revisión.

¿Qué documentos son obligatorios para completar el alta?

Son tres imágenes obligatorias: frente del DNI, dorso del DNI y selfie del usuario. Deben enviarse mediante el endpoint POST identity-documents antes de ejecutar el POST v2/investment-accounts. Si falta alguno de ellos, la cuenta no podrá crearse.

💸 Depósitos

Un usuario reporta que realizó una transferencia pero los fondos no aparecen en su cuenta. ¿Qué puede estar pasando?

Cuando un usuario reporta un depósito no reflejado, las causas más frecuentes son:

• El depósito está en proceso: puede estar en estado "Pendiente" o "Procesando" y aún no completó. Nuestro equipo puede verificar el estado en tiempo real.
• CUIT no coincidente: si el CUIT del depositante no coincide con el titular de la cuenta comitente, el depósito queda pendiente de validación manual. Por normativa, los depósitos de terceros (distinto CUIT al del titular) no se acreditan automáticamente.

Para investigar cualquiera de estos casos, reportarlo a nuestro equipo indicando: CUIT del usuario, monto, fecha/hora aproximada y moneda.

¿Qué significa la validación "same name" en depósitos?

Por normativa, el CUIT/CUIL de quien realiza la transferencia bancaria debe coincidir con el titular de la cuenta comitente. Los depósitos donde el depositante es una persona distinta al titular no se acreditan automáticamente. La excepción aplica únicamente para transferencias entre cuentas del mismo titular.

🏦 Retiros (Extracciones)

¿Por qué se rechazó un retiro si el usuario dice tener saldo?

Existen varias causas posibles, más allá del saldo visible:

• Saldo comprometido: Puede haber operaciones pendientes de liquidación (T+1 o T+2) que comprometan parte del saldo. El saldo "aparente" puede diferir del disponible real.
• CBU no same name: El CBU ingresado no pertenece al titular del comitente. Por normativa, la cuenta bancaria debe estar a nombre de la misma persona.
• CBU inválido: Dígitos verificadores incorrectos, cuenta cerrada o suspendida.

¿Qué significa el estado IN_PROGRESS en un retiro y cuánto puede demorar?

Indica que el retiro está siendo procesado. Es un estado normal y transitorio; los saldos del usuario permanecen intactos en todo momento. Si el estado persiste más de lo esperado, pueden contactarnos con el ID del retiro y el CUIT del usuario para que lo revisemos.

📦 Solicitudes de Fondos (Fund Requests)

¿Qué diferencia hay entre los estados RETRY y NOT_SENT?

• RETRY: La solicitud está siendo procesada. Si el estado persiste más de lo esperado, pueden contactarnos para que revisemos el caso.
• NOT_SENT: La solicitud no llegó a enviarse al mercado. El dinero se devuelve automáticamente al comitente.

¿Una solicitud de fondos cancelada genera un boleto o confirmation?

No. Si una solicitud se cancela, solo se genera el webhook fund_request_update con estado CANCELLED. No se genera ninguna mutual_fund_confirmation porque la liquidación nunca llega a existir.

📊 Tenencias (Holdings) y Plazos de Liquidación

¿Por qué quantity_available aparece mayor que quantity en un holding?

No es un error. El campo quantity_available se calcula así:

quantity_available = quantity + quantity_t1 + quantity_t2

Si el usuario tiene compras pendientes de liquidación en T+1 o T+2, quantity_t1 será positivo, haciendo que quantity_available supere a quantity. Esto es comportamiento esperado.

¿Qué significa quantity_t1 negativo en un holding?

Indica que existe una venta ejecutada a T+1 que todavía no liquidó. Las tenencias en quantity aún reflejan las acciones como disponibles, pero quantity_t1 negativo descuenta ese monto del disponible hasta que se complete la liquidación al día hábil siguiente.

¿Cómo debo sincronizar tenencias correctamente después de un rescate?

Para una sincronización precisa es importante considerar el plazo de liquidación de la operación. El webhook mutual_fund_confirmation_create refleja la concertación de la operación, pero los fondos quedan disponibles al día hábil siguiente según el plazo del fondo (T+1 o T+2).

✅

Recomendación: Consumir el endpoint /api/portfolio/account-statements/{investment_account_id} como fuente de verdad para la sincronización de tenencias, ya que refleja correctamente los plazos de liquidación y es el resumen consolidado del portfolio.

¿Qué son los compromised_holdings y cómo afectan al disponible?

Los compromised_holdings representan cuotapartes comprometidas en solicitudes de fondos enviadas pero que aún no liquidaron. Al enviar una solicitud de rescate, las cuotapartes a rescatar pasan a compromised_holdings: se "reservan" para evitar que se usen dos veces mientras la operación está pendiente.

Ejemplo: Un usuario con 24.485,37 cuotapartes de un fondo envía un rescate de 7.602,3207 cuotapartes a T+1:

• quantity: refleja lo que ya liquidó
• quantity_available: refleja lo que queda libre (24.485,37 - 7.602,32 = 16.883,05)
• Los 7.602,32 quedan en compromised_holdings hasta que la liquidación se hace efectiva al día hábil siguiente

¿Cuándo se reflejan las tenencias de una compra en el portfolio?

Las tenencias se reflejan en el portfolio después de que la operación liquida, no en el momento de la ejecución. Los plazos de liquidación son:

Si un usuario realizó una compra hoy y no ve sus tenencias actualizadas, puede deberse a que la operación todavía no liquidó según el plazo correspondiente.

🔔 Webhooks

¿Qué webhooks debo suscribir para operar fondos comunes de inversión?

La arquitectura recomendada para clientes que operan fondos es suscribirse a los siguientes webhooks:

✅

Para obtener los datos finales y confirmados de liquidación (share_quantity y share_price), utilizar el webhook mutual_fund_confirmations_create.

¿Los webhooks fund_request_update (SETTLED) y mutual_fund_confirmations_create se envían al mismo tiempo?

Sí, se generan prácticamente en simultáneo. Como buena práctica de integración, recomendamos que el sistema esté preparado para manejar ambos eventos de forma independiente.

¿Qué topic_id corresponde a mutual_fund_confirmations_create?

Los topic_id difieren según el ambiente:

¿Cuál es el endpoint recomendado para sincronizar tenencias si no quiero depender solo de webhooks?

El endpoint /api/portfolio/account-statements/{investment_account_id} es la fuente de verdad para sincronización de tenencias. Devuelve un resumen consolidado del portfolio reflejando correctamente los plazos de liquidación de cada operación.

Última actualización: Mayo 2026 — Equipo de Customer Experience, API Broker