Onboarding

El onboarding es el proceso mediante el cual registrás a los usuarios de tu plataforma en API Broker, habilitándoles una cuenta comitente para operar. Es el prerequisito obligatorio para cualquier módulo: Remuneración de Saldo, FCI, Dólar MEP o Trading.

El flujo es secuencial e interdependiente: cada paso genera un ID que se necesita en el siguiente. No es posible saltear pasos.

Flujo general

POST /accounts/v2/persons
      ↓ person_id
POST /accounts/identity-documents (o /contracts para PJ)
      ↓
POST /accounts/v2/investment-accounts
      ↓ investment_account_id
POST /accounts/bank-accounts
      ↓ bank_account_id

Paso 1 — Alta de persona

Endpoint

POST /api/accounts/v2/persons

El primer paso es registrar a la persona en el sistema. Antes de empezar, es fundamental distinguir el tipo:

• Persona Física (PF): individuo con DNI, fecha de nacimiento y datos personales.
• Persona Jurídica (PJ): entidad legal (SA, SRL, Fideicomiso, etc.) con CUIT propio y razón social.

Esta distinción determina qué campos son requeridos y qué documentación se solicitará en el paso siguiente.

Campos comunes (PF y PJ)

Campos exclusivos Persona Física (human_person)

Campos exclusivos Persona Jurídica (legal_person)

Body de ejemplo — Persona Física

{
  "persons": [{
    "job_activity_id": 10,
    "nationality_id": "AR",
    "country_document_id": "AR",
    "is_pep": false,
    "is_aml_cft_subject": false,
    "fatca_id": "",
    "oecd_identifiers": [],
    "tax_identifications": {
      "tax_identification_value": "20301234567",
      "residence_country_id": "AR",
      "tax_identification_type_id": "CUIL",
      "taxpayer_income_tax_type_id": "...",
      "vat_taxpayer_type_id": "...",
      "vat_country_taxpayer_type_id": "AR"
    },
    "human_person": {
      "surname": "García",
      "name": "Martín",
      "document_type_id": "DNI",
      "document_num": "30123456",
      "civil_status_id": "soltero",
      "birth_date": "1990-05-15",
      "birth_place": "Buenos Aires",
      "gender_id": "M",
      "signature": "base64string..."
    },
    "domiciles": [{
      "domicile_type_id": "real",
      "street": "Av. Corrientes",
      "house_number": 1234,
      "floor": 3,
      "apartment": "B",
      "country_id": "AR",
      "province_id": "BA",
      "zip_code": 1043,
      "location_id": 1
    }],
    "contact": {
      "email": "[email protected]",
      "mobile_phone": "+5491155667788"
    }
  }]
}

Body de ejemplo — Persona Jurídica

{
  "persons": [{
    "job_activity_id": 50,
    "nationality_id": "AR",
    "country_document_id": "AR",
    "is_pep": false,
    "is_aml_cft_subject": false,
    "fatca_id": "",
    "oecd_identifiers": [],
    "tax_identifications": {
      "tax_identification_value": "30712345678",
      "residence_country_id": "AR",
      "tax_identification_type_id": "CUIT",
      "taxpayer_income_tax_type_id": "...",
      "vat_taxpayer_type_id": "...",
      "vat_country_taxpayer_type_id": "AR"
    },
    "legal_person": {
      "company_name": "Inversiones del Sur S.A.",
      "registration_number": "12345",
      "incorporation_place": "Buenos Aires",
      "country_id": "AR",
      "constitution_date": "2010-03-20",
      "book": "5",
      "volume": "10",
      "page": "123",
      "is_state_supplier": false,
      "corporate_type": 1
    },
    "domiciles": [{
      "domicile_type_id": "legal",
      "street": "Florida",
      "house_number": 500,
      "country_id": "AR",
      "province_id": "BA",
      "zip_code": 1005,
      "location_id": 1
    }],
    "contact": {
      "email": "[email protected]",
      "mobile_phone": "+541143210000"
    }
  }]
}

Response

{
  "items": [{
    "person_id": "F-9686d35b-b2e4-4f29-bb33-28bd73d12437",
    "surname": "García",
    "name": "Martín",
    "tax_identification_value": "20301234567",
    "error": null
  }]
}

Guardá el person_id. Lo vas a necesitar en todos los pasos siguientes. Si error viene en null, el alta fue exitosa.

Paso 2 — Carga de documentación

Persona Física — Documentación de identidad

POST /api/accounts/persons/identity-document

Se requieren tres imágenes en formato base64:

{
  "person_id": "F-9686d35b-b2e4-4f29-bb33-28bd73d12437",
  "front": "base64...",
  "back": "base64...",
  "face": "base64..."
}

Si la persona física es PEP, además debe cargar documentación de origen de fondos (últimos 3 recibos de sueldo, certificación contable, escrituras, etc.) usando el endpoint /contracts con el campo pep_documents.

Persona Jurídica — Documentación societaria

POST /api/accounts/persons/contracts

Este endpoint usa multipart/form-data (no JSON). Permite enviar archivos y texto simultáneamente.

¿Qué va en cada campo según tipo societario?

Beneficiario final: debés identificar a todas las personas humanas con participación directa o indirecta del 10% o más. Por ejemplo: si la empresa A tiene 50% de la empresa B, y Juan tiene 30% de A → Juan tiene 15% indirecto de B y debe ser declarado.

Paso 3 — Alta de cuenta comitente

POST /api/accounts/v2/investment-accounts

Crea la cuenta de inversión del usuario. Vincula el person_id obtenido en el paso 1.

Campos requeridos

El cuestionario de perfil de inversión tiene 5 preguntas. Podés consultarlas en GET /api/master-tables/investor-questions. El sistema calcula automáticamente el perfil resultante: conservador, moderado o agresivo.

Body de ejemplo

{
  "investment_accounts": [{
    "external_id": "cliente-123",
    "person_account_type_id": "human",
    "market_type": ["stock_market"],
    "investment_profile": {
      "1": 2,
      "2": 1,
      "3": 3,
      "4": 2,
      "5": 1
    },
    "owners": [{
      "person_id": "F-9686d35b-b2e4-4f29-bb33-28bd73d12437",
      "person_role_id": "titular"
    }]
  }]
}

Response

{
  "items": [{
    "external_id": "cliente-123",
    "investment_account_id": 43101,
    "investment_risk_profile": "moderado",
    "error": null
  }]
}

Guardá el investment_account_id. Es el identificador central que vas a usar en todos los módulos operativos.

Para personas jurídicas: el sistema genera automáticamente una cuenta cuotapartista además de la cuenta comitente. Esto habilita el método de colocación SIMPLE en FCI.

Webhook de confirmación

API Broker notifica de forma asincrónica cuando la cuenta comitente y/o la cuenta cuotapartista fue creada en el ALyC y/o en la Sociedad Gestora de FCI:

Webhook: investment_account_update

Paso 4 — Alta de cuenta bancaria

POST /api/accounts/bank-accounts/

Vincula una cuenta bancaria a la cuenta comitente para habilitar depósitos y retiros.

Regla fundamental: SAME NAME

La cuenta bancaria debe estar a nombre del mismo titular que la cuenta comitente, verificado por CUIT. No se admiten cuentas de terceros.

Campos requeridos

Body de ejemplo

{
  "bank_accounts": [{
    "investment_account_id": 43101,
    "currency_id": "ARS",
    "cbu": "0000003100012345678901",
    "alias": "martin.garcia.mp"
  }]
}

Response

{
  "items": [{
    "investment_account_id": 43101,
    "cbu": "0000003100012345678901",
    "alias": "martin.garcia.mp",
    "bank_account_id": "ba-abc123",
    "error": null
  }]
}

Podés dar de alta múltiples cuentas bancarias por comitente (ej: una en ARS y una en USD) en una sola llamada.

Diferencias clave: PF vs PJ

Endpoints de consulta

Una vez completado el onboarding, podés consultar la información con:

Puntos clave para recordar

1. El orden es obligatorio: no se puede crear una cuenta comitente sin person_id, ni registrar una cuenta bancaria sin investment_account_id.
2. Guardá los IDs en cada paso: person_id, investment_account_id y bank_account_id son las llaves de toda la operatoria posterior.
3. SAME NAME es innegociable: la cuenta bancaria debe tener el mismo titular que la cuenta comitente, validado por CUIT.
4. Campos condicionales PEP: si is_pep = true, los campos pep_relation y pep_position se vuelven obligatorios.
5. FATCA y OCDE vacíos si no aplican: enviar "fatca_id": "" y "oecd_identifiers": [] en lugar de omitirlos.
6. Las PJ generan cuenta cuotapartista automáticamente, lo que habilita el método SIMPLE en FCI.
7. Usar siempre la v2 de los endpoints de personas y cuentas comitentes.
8. Revisar siempre el campo error en el response. Si no es null, el alta falló y hay que corregir antes de continuar.
9. Los valores de master-tables (países, provincias, tipos de documento, actividades AFIP, etc.) deben consultarse previamente en GET /api/master-tables/.