Tutorial: Flujo de trabajo de la API de cuentas

Guía para crear y gestionar cuentas de inversión utilizando la API de cuentas.

Pasos principales

Paso 1: Crear un partícipe

Antes de crear una cuenta, necesitamos crear un partícipe.

Endpoint para crear partícipe

POST /api/shareholders/create/

Request Body para crear partícipe

{
  "external_id": "ext123",
  "risk_level": 3,
  "is_active": true,
  "first_name": "Juan",
  "last_name": "Pérez",
  "business_activity": "0"  // 0: Persona Natural (valor por defecto)
}

Response para creación de partícipe

{
  "external_id": "ext123",
  "uuid": "f41c7699-a1b9-4caa-9ff3-fa2f0e447e34",
  "risk_level": 3,
  "is_active": true,
  "rut": null,
  "first_name": "Nombre",
  "last_name": "Apellido",
  "created": "2024-11-20T15:30:44.119534-03:00",
  "business_activity": "0"

}

Errores en creación de partícipe

400: Error de validación

{ "message": "Validation error", "code": "1003", "extra": { "fields": { "risk_level": [ "This field is required." ], "external_id": [ "This field is required." ], "first_name": [ "This field is required." ], "last_name": [ "This field is required." ] } } }

400: Erronea selección de risk_level

"extra": { "fields": { "risk_level": [ "Value 10 is not a valid choice." ] } }

Guarda el external_id devuelto en la respuesta, lo necesitarás para los siguientes pasos.

Paso 1.1 (Opcional): Agregar información de contacto

Endpoint para crear información de contacto

POST /api/shareholders/contact/create/

Request Body para crear información de contacto

{
  "share_holder_external_id": "ext123",
  "email": "juan.perez@ejemplo.com",
  "phone": "+56912345678",
  "birthdate": "1990-01-01",
  "address": "Calle Ejemplo 123",
  "commune": "Santiago"
}

Response para creación de información de contacto

{
  "share_holder_external_id": "ext123",
  "email": "juan.perez@ejemplo.com",
  "phone": "+56912345678",
  "birthdate": "1990-01-01",
  "address": "Calle Ejemplo 123",
  "commune": "Santiago"
}

Paso 1.2 (Opcional): Agregar información bancaria

Endpoint para crear información bancaria

POST /api/shareholders/bank/create/

Request Body para crear información bancaria

{
  "share_holder_external_id": "ext123",
  "bank": "Banco Ejemplo",
  "account_type": "Cuenta Corriente",
  "account_number": "00012345678"
}

Response para creación de información bancaria

{
  "shareholder_external_id": "ext123",
  "bank": "Banco Ejemplo",
  "account_type": "Cuenta Corriente",
  "account_number": "00012345678"
}

Paso 2: Crear una cuenta de inversión

Endpoint: Crear cuenta

POST /api/accounts/create/

Request Body para crear cuenta

{
  "share_holder_external_id": "ext123",
  "is_active": true,
  "product": "SFC",
  "objective": "Ahorro Vivienda",
  "housing_subsidy": false,
  "withdrawal_lock": false,
  "contract_signed_at": "2024-03-15T10:00:00Z",
  "contract_version": "v1.0",
  "contract_url": "https://ejemplo.com/contrato.pdf",
  "external_id": "cuenta123",
  "metadata": {
    "account_type": "premium",
    "region": "metropolitana"
  },
  // Campos opcionales para crear DxP al mismo tiempo
  "dxp_amount": "1000.0000",
  "dxp_currency": "CLP",     // Opciones: CLP, UF
  "dxp_withdrawal_starts_at": "2024-04-15"
}

Response para creación de cuenta (sin DxP)

{
  "uuid": "98765432-abcd-5678-efgh-987654321000",
  "share_holder_external_id": "ext123",
  "is_active": true,
  "risk_level": "Bajo",
  "product": "SFC",
  "objective": "Ahorro Vivienda",
  "housing_subsidy": false,
  "withdrawal_lock": false,
  "contract_signed_at": "2024-03-15T10:00:00Z",
  "contract_version": "v1.0",
  "contract_url": "https://ejemplo.com/contrato.pdf",
  "external_id": "cuenta123",
  "metadata": {
    "account_type": "premium",
    "region": "metropolitana"
  },
  "dxp_amount": null,
  "dxp_currency": null,
  "dxp_withdrawal_starts_at": null,
  "dxp_is_active": null
}

Response para creación de cuenta (con DxP)

{
  "uuid": "98765432-abcd-5678-efgh-987654321000",
  "share_holder_external_id": "ext123",
  "is_active": true,
  "risk_level": "Bajo",
  "product": "SFC",
  "objective": "Ahorro Vivienda",
  "housing_subsidy": false,
  "withdrawal_lock": false,
  "contract_signed_at": "2024-03-15T10:00:00Z",
  "contract_version": "v1.0",
  "contract_url": "https://ejemplo.com/contrato.pdf",
  "external_id": "cuenta123",
  "metadata": {
    "account_type": "premium",
    "region": "metropolitana"
  },
  "dxp_amount": "1000.0000",
  "dxp_currency": "CLP",
  "dxp_withdrawal_starts_at": "2024-04-15",
  "dxp_is_active": true
}

Paso 3: Crear un DxP (Descuento por Planilla) [Opcional]

Si no creaste el DxP junto con la cuenta, puedes crearlo después:

Endpoint: Crear DxP

POST /api/accounts/dxpcreate/

Request Body para crear DxP

{
  "account_external_id": "cuenta123",
  "amount": "1000.0000",
  "currency": "CLP",         // Opciones: CLP, UF
  "withdrawal_starts_at": "2024-04-15",
  "is_active": true
}

Response para creación de DxP

{
  "uuid": "98765432-abcd-5678-efgh-987654321000",
  "id": 1,
  "investment_account": "98765432-abcd-5678-efgh-987654321000",
  "amount": "1000.0000",
  "currency": "CLP",
  "withdrawal_starts_at": "2024-04-15",
  "is_active": true
}

Paso 4: Actualizar un DxP

Endpoint: Actualizar DxP

POST /api/accounts/dxpupdate/

Request Body para actualizar DxP

{
  "account_external_id": "cuenta123",
  "amount": "1500.0000",           // Opcional
  "currency": "CLP",               // Opcional
  "withdrawal_starts_at": "2024-05-15"  // Opcional
}

Response para actualización de DxP

{
  "uuid": "98765432-abcd-5678-efgh-987654321000",
  "id": 1,
  "investment_account": "98765432-abcd-5678-efgh-987654321000",
  "amount": "1500.0000",
  "currency": "CLP",
  "withdrawal_starts_at": "2024-05-15",
  "is_active": true
}

Paso 5: Cambiar el estado activo de un DxP

Endpoint: Actualizar estado activo del DxP

POST /api/accounts/dxpupdatestatus/

Request Body para actualizar estado activo del DxP

{
  "account_external_id": "cuenta123",
  "is_active": false
}

Response para actualización de estado activo del DxP

{
  "uuid": "98765432-abcd-5678-efgh-987654321000",
  "id": 1,
  "investment_account": "98765432-abcd-5678-efgh-987654321000",
  "amount": "1500.0000",
  "currency": "CLP",
  "withdrawal_starts_at": "2024-05-15",
  "is_active": false
}

Otros endpoints

Listar cuentas

Endpoint: Listar cuentas

GET /api/accounts/list/

Parámetros de consulta opcionales

shareholder_external_id=ext123
external_id=cuenta123
metadata_value={"account_type": "premium"}

Response para listar cuentas

[
  {
    "uuid": "98765432-abcd-5678-efgh-987654321000",
    "share_holder_external_id": "ext123",
    "is_active": true,
    "risk_level": "Bajo",
    "product": "SFC",
    "objective": "Ahorro Vivienda",
    "housing_subsidy": false,
    "withdrawal_lock": false,
    "contract_signed_at": "2024-03-15T10:00:00Z",
    "contract_version": "v1.0",
    "contract_url": "https://ejemplo.com/contrato.pdf",
    "external_id": "cuenta123",
    "metadata": {
      "account_type": "premium",
      "region": "metropolitana"
    },
    "dxp_amount": "1000.0000",
    "dxp_currency": "CLP",
    "dxp_withdrawal_starts_at": "2024-04-15",
    "dxp_is_active": true
  },
  // ... más cuentas ...
]

Cambiar el estado activo de una cuenta

Endpoint: Actualizar estado activo de una cuenta

POST /api/accounts/active/

Request Body para actualizar estado activo de una cuenta

{
  "external_id": "cuenta123",
  "is_active": false
}

Response para actualización de estado activo de una cuenta

{
  "uuid": "98765432-abcd-5678-efgh-987654321000",
  "share_holder_external_id": "ext123",
  "is_active": false,
  "risk_level": "Bajo",
  "product": "SFC",
  "objective": "Ahorro Vivienda",
  "housing_subsidy": false,
  "withdrawal_lock": false,
  "contract_signed_at": "2024-03-15T10:00:00Z",
  "contract_version": "v1.0",
  "contract_url": "https://ejemplo.com/contrato.pdf",
  "external_id": "cuenta123",
  "metadata": {
    "account_type": "premium",
    "region": "metropolitana"
  }
}

Establecer el estado de subsidio de vivienda

Endpoint: Actualizar estado de subsidio de vivienda

POST /api/accounts/subsidy/

Request Body para actualizar estado de subsidio de vivienda

{
  "external_id": "cuenta123",
  "housing_subsidy": true
}

Response para actualización de estado de subsidio de vivienda

{
  "uuid": "98765432-abcd-5678-efgh-987654321000",
  "share_holder_external_id": "ext123",
  "is_active": true,
  "risk_level": "Bajo",
  "product": "SFC",
  "objective": "Ahorro Vivienda",
  "housing_subsidy": true,
  "withdrawal_lock": false,
  "contract_signed_at": "2024-03-15T10:00:00Z",
  "contract_version": "v1.0",
  "contract_url": "https://ejemplo.com/contrato.pdf",
  "external_id": "cuenta123",
  "metadata": {
    "account_type": "premium",
    "region": "metropolitana"
  }
}