Cuentas
Una cuenta en InvWallet representa la estructura necesaria para que un usuario pueda operar productos de inversión. Está compuesta por dos niveles:
- MainAccount (cuenta principal): agrupa a las personas y cuentas bancarias asociadas al cliente. Es el nodo central del usuario dentro del sistema.
- Subcuenta: representa el vehículo operativo dentro de una entidad registrante (SG, AM, broker). Una MainAccount puede tener múltiples subcuentas de distintos tipos.
A cada cuenta puede asignarse cualquier cantidad de Personas, tanto físicas como jurídicas. Una, y solo una, puede ser declarada como titular. Las demás pueden agregarse como firmantes o ejecutantes.
Para el caso de Personas Jurídicas, la validación de la potestad de los apoderados para representar a dicha entidad debe haber sido validada previamente por la wallet.
Tipos de Subcuenta
Cada subcuenta habilita distintas operaciones y requiere diferentes datos de onboarding. Los tipos disponibles para cada billetera pueden consultarse en GET /api/v1/specs/.
| Tipo | Nombre | Descripción |
|---|---|---|
1 | Cuotapartista Simplificado | Onboarding más simple, específico para productos de remuneración de saldos. Es el tipo por defecto en la mayoría de los tenants. |
2 | Cuotapartista Estándar | Sirve para operar todas las alternativas de Fondos Comunes de Inversión. Requiere el Perfil del Inversor. |
3 | Comitente | Cuenta para operar en mercado (acciones, Cedears, etc.). Requiere habilitación específica y más datos del cliente, además del Perfil del Inversor. |
El tipo 3 (Comitente) aplica únicamente para operaciones en el mercado local argentino.
Estado de Cuenta
Las cuentas al crearse pasan por distintos procesos hasta darse de alta. El estado puede consultarse en cualquier momento:
| Estado | Descripción |
|---|---|
DRAFT | Cuenta en borrador, requiere ser validada por la aplicación |
PENDING | Cuenta pendiente, se encuentra en proceso de validación |
OPEN | Cuenta abierta y lista para operar |
CLOSED | Cuenta cerrada, no puede operar Fondos |
LOCKED | Cuenta bloqueada, no puede operar Fondos |
Creación de Cuenta
POST /api/v1/accounts/
Crea una cuenta en el sistema. Según los parámetros enviados, se crea una nueva MainAccount con una subcuenta, o se agrega una subcuenta a una MainAccount existente.
Flujo de creación
- Sin
main_account_id: se crea una nueva MainAccount (external_idobligatorio) junto con una subcuenta del tipo indicado, o cuotapartista por defecto. - Con
main_account_id: se reutiliza la cuenta principal existente y se crea una nueva subcuenta asociada a ella. No se genera una nueva MainAccount.
Guardar el main_account_id de la respuesta permite luego crear nuevas subcuentas sobre la misma cuenta principal sin duplicar datos del cliente.
Parámetros del Request
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
account_type | string | No | Tipo de representación: individual, company, government_entity, non_profit. Default: individual. |
external_id | string | Condicional | ID de referencia de la wallet (máx. 100 caracteres). Obligatorio al crear una nueva MainAccount. Debe ser único por wallet. |
persons | array | Sí | Personas asociadas a la cuenta. Ver Personas. |
bank_accounts | array | Sí | Cuentas bancarias asociadas. |
sub_account_type | integer | No | Tipo de subcuenta: 1 Simplificado, 2 Estándar, 3 Comitente. Si se omite, se usa el tipo por defecto del tenant. |
main_account_id | string | No | ID de una MainAccount existente. Si se envía, se agrega una subcuenta a esa cuenta principal. |
Respuesta (201)
La respuesta incluye account_id, main_account_id, sub_account_type, estado, personas y cuentas bancarias.
| Campo | Descripción |
|---|---|
account_id | ID único de la subcuenta creada |
main_account_id | ID de la cuenta principal (nueva o reutilizada) |
sub_account_type | Tipo de subcuenta asignado |
account_type | Tipo de representación |
external_id | ID externo de referencia |
persons | Personas asociadas |
bank_accounts | Cuentas bancarias asociadas |
Validaciones
El sub_account_type debe estar habilitado para el tenant y para la billetera. Verificar con GET /api/v1/specs/ antes de crear.
El external_id debe ser único por wallet al crear una nueva MainAccount. Si ya existe, se devuelve error.
Si se reutiliza una MainAccount con main_account_id y la billetera no permite más de una subcuenta del mismo tipo por cuenta principal, la API devolverá error.