Skip to main content

Guía de Integración

El objetivo de la siguiente guía es llevarte de la mano en un proceso de integración óptimo. Para esto seguiremos una serie de pasos que permitirán el desarrollo de la integración, desde el registro de usuarios en la plataforma de inversión, incluyendo el proceso de onboarding, pasando por el fondeo de la cuenta y las operaciones de trading.

El único requisto previo para poder llevar a cabo esta serie de pasos es haber realizado una autenticación exitosa. Recuerda que en todos los llamados a la API debes pasar en el header "Authorization" el token de autenticación.

Paso 1: Registro de Usuario​

El primer paso recomendado para iniciar el proceso de integración, es el registro de tu primer usuario.

Aquí tienes un ejemplo de como crear tu primer usuario:

  POST /v1/user

Cuerpo de la Solicitud

  {
      "externalId": "2946445a-f37d-4aaa-8327-e372adf763b8",
      "name": "Anakin",
      "familyName": "Skywalker",
      "email": "anakin.skywalker@tatooine.com",        
      "countryCode": "CRI"
  }

En el campo "externalId" puedes pasar opcionalmente un id externo para el usuario. En este caso recomendamos pasar el id de tu usuario en tu plataforma para así mejorar la identificación o equivalencia entre los usuarios de ambas plataformas. El campo es opcional con una longitud máxima de 50 caracteres.

El campo countryCode debe ser un código de país según la lista retornada por el endpoint /v1/onboarding/trading-countries.

Ejemplo de Respuesta

  {
      "id": "7c44e25f-7e0a-4c4e-b114-3d119bdff290",
      "partnerId": "015ae137-31aa-467f-bfc4-f99536381a81",
      "externalId": "2946445a-f37d-4aaa-8327-e372adf763b8",
      "name": "Anakin",
      "familyName": "Skywalker",
      "email": "anakin.skywalker@tatooine.com",
      "phone": "+506897654231",
      "countryCode": "CRI"
      "dateCreated": "2019-08-24T14:15:22Z",
      "dateModified": "2019-08-24T14:15:22Z"
  }

Es importante que en tu backend guardes el id retornado por TraderPal Connect, ya que la mayoría de los endpoints para acceder a los datos del usuario reciben este id en su url.

Consulta aquí la guía detallada de la API de Usuarios.

Paso 2: Onboarding​

Una vez que hayas registrado tu primer usuario, debes proceder con el proceso de onboarding. TraderPal usa el servicio de Footprint para realizar la verificación de identidad y onboarding de sus usuarios.

Footprint ofrece un SDK compatible con varias plataformas de front-end como React Native, Flutter, Javascript, etc. Puedes consultar más acerca de Footprint en su sitio web https://www.onefootprint.com/

Obteniendo el token de sessión de onboarding​

Primero debes obtener un toquen de sesión de onboarding para poder inicializar el SDK de Footprint según la plataforma de front-end que estés usando.

Para eso debes llamar al endpoint POST /v1/onboarding/{userId}/session-token

Aquí tienes un ejemplo de como obtener el onboarding session token:

  POST /v1/onboarding/{userId}/session-token

Cuerpo de la Solicitud

  {
    "dateOfBirth": "2000-01-31",
    "gender": "Male",
    "maritalStatus": "Single",
    "state": "Granada",
    "city": "Granada",
    "addressLine1": "Calle La Calzada, la gran francia",
    "addressLine2": "Casa B02",
    "zipCode": "12345"
  }

En userId pasas el id de usuario devuelto por TraderPal Connect al crear el usuario. En el cuerpo de la llamada puedes pasar una lista de campos opcionales en caso que en tu plataforma ya cuentes con esa información de tus usuarios, evitando así que el usuario tenga que ingresar de nuevo dicha información. En caso que no cuentes con alguno de estos campos, puedes pasar una cadena vacía.

TraderPal Connect te dará una respuesta como la siguiente:

    {
      "token": "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
      "link": "https://verify.onefootprint.com/?type=user#obtok_ssPvNRjNGdk8Iq9qgf6lsO2iTVhALuR4Nt",
      "expiresAt": "2022-01-04T12:00-07:00"
    }

En el campo token se retorna el token necesario para inicializar el SDK de Footprint en tu App. Footprint soporta las plataformas de front-end más populares de la actualidad como: React Native, Futter, JS/TS, Expo, Swift y Android.

En el campo link se retorna un enlace para poder probar o integrar el proceso de onboarding bajo un enfoque codeless. Sin embargo el equipo de TraderPal Connect recomienda la integración con el SDK para ofrecer una mejor experiencia de usuario. El uso de este enlace está únicamente recomendado para pruebas iniciales en ambiente sandbox.

Y finalmente el campo "expiresAt" indica hasta que fecha y hora el token es válido.

A continuación tienes los enlaces a las guías de inicialización del SDK de footprint en las plataformas mencionadas.

No dudes en consultar la guía correspondiente y en contactar al equipo de TraderPal para cualquier duda.

Paso 3: Consultando el Perfil de Trader del Usuario​

Una vez que el SDK de Footprint haya reportado la finalización del proceso de onboarding y haya informado a TraderPal de sus resultados, se creará el perfil de trader del usuario, el cual es además compartido con nuestro broker en USA para la apertura de la cuenta de inversión.

Puedes consultar el perfil de trader del usuario a través del endpoint GET /v1/onboarding/{userId}/trader-profile

  GET /v1/onboarding/{userId}/trader-profile

Respuesta

  {
      "id": "41b2af64-0f31-4895-8121-e870244db5b6",
      "userId": "6e971654-d66e-42c6-9b0c-0811058ed90a",
      "country": "CRI",
      "countryName": "Costa Rica",
      "state": "Cartago",
      "stateName": "Cartago",
      "phone": "+505897654231",
      "city": "Tres Rios",
      "legalFirstName": "Anakin",
      "legalLastName": "Skywalker",
      "dateOfBirth": "2000-02-01T00:00:00",
      "taxID": "DNI75983614",
      "residentialAddress": "Condominio Palmeras, Guacima, Cartago",
      "unitAptNumber": "B51",
      "postalCode": "10101",
      "emailAddress": "anakin.skywalker@tatooine.com",
      "countryOfTaxResidence": "CRI",
      "permanentResident": false,
      "countryOfBirth": "CRI",
      "countryOfCitizenship": "CRI",
      "isVisaHolder": false,
      "visaType": null,
      "visaExpirationDate": null,
      "dateOfDepartureFromUSA": null,
      "annualHouseholdIncomeRange": "R50K",
      "investibleLiquidAssetsRange": "R20K",
      "accountFundingSource": "savings",
      "employmentStatus": "employed",
      "nameOfEmployer": "Acme Corporation",
      "employerAddress": "San José, Avenida Central 101",
      "occupationJobTitle": "Engineer",
      "trustedContactFirstName": null,
      "trustedContactLastName": null,
      "trustedContactEmailAddress": null,
      "trustedContactPhoneNumber": null,
      "isAffiliatedExchangeOrFinra": false,
      "isControlPerson": false,
      "isPoliticallyExposed": false,
      "inmediateFamilyExposed": false,
      "dateCreated": "2025-05-09T23:49:51.53",
      "dateModified": "2025-05-09T23:55:35.677",
      "brokerAccountNumber": "823790788",
      "brokerAccountStatus": "ACTIVE",
      "statusReason": null,
      "gender": "M",
      "maritalStatus": "S"
  }

El campo "brokerAccountStatus" es de gran importancia porque nos dice si el profile del usuario ya está activo en la plataforma del broker. Una vez que el profile ya está en el estado ACTIVE, se puede proceder con el resto los pasos del flujo, como son el fondear la cuenta de inversiones y el de enviar órdenes de compra o venta de stocks en nombre de tus usuarios.

Paso 4: Fondeo​

Para poder iniciar transacciones de trading, o sea, compra y venta de stocks, es necesario que la cuenta de inversión del usuario tenga fondos. A continuación se muestra un ejemplo de como cargar fondos (hacer un depósito):

  POST /v1/funding

Cuerpo de la Solicitud​

  {
      "userId": "4be3c6d1-2d49-4843-b5f4-1c63abde443e",
      "direction": "DEPOSIT",
      "amount": "100",
      "externalId": "a1d27847-0645-4e95-8698-5b09a516d932"
  }

Ejemplo de Respuesta​

  {
      "id": "bbdcf204-ef0c-4612-95f8-b6329211b99c",
      "userId": "4be3c6d1-2d49-4843-b5f4-1c63abde443e",
      "direction": "DEPOSIT",
      "amount": 100,
      "fee": 2,
      "netAmount": 98,
      "partnerId": "29e16674-3baa-4ae6-b13d-d4384499d16e",
      "externalId": "4a4f8547-9ef1-4054-a2c9-699da47ebd20",
      "status": "pending",
      "statusReason": "",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z",
      "completedAt": "2019-08-24T14:15:22Z"
  }

Notas:

  • El monto de las transacciones de fondeo en TraderPal Connect siempre está dado en dólares americanos.
  • El modelo de fondeo por defecto con TraderPal Connect está basado en un modelo de compensaciones, en el cual, el partner es responsable de debitar en su propia plataforma el monto a fondear de la cuenta del usuario (sea esta una cuenta bancaria, un wallet digital, por citar algunos ejemplos). TraderPal Connect aplica un crédito a la cuenta de inversiones del usuario desde una cuenta prefondeada en la plataforma de nuestro broker. Luego en cada liquidación, el partner debe transferir a una cuenta bancaria en USA con cierta periodicidad a definir con TraderPal, el total de los depósitos del período para alimentar nuevamente la cuenta prefondeada.
  • El modelo de fondeo puede cambiar dependiendo de las negociaciones realizadas con un partner específico, por tanto en esos casos pueden usarse otros endpoints personalizados para dicho fin. Sin embargo, el método de fondeo mostrado anteriormente puede usarse también para pruebas en ambiente sandbox.

Paso 5: Trading​

Una vez que la cuenta del usuario ya tiene fondos, es posible enviar una orden de compra de un stock.

A continuación se muestra un ejemplo de como enviar una orden de compra de 50 dólares en acciones de Apple:

  POST /v1/orders

Cuerpo de la Solicitud​

  {
      "userId": "2946445a-f37d-4aaa-8327-e372adf763b8",
      "symbol": "AAPL",
      "qty": 0,
      "amount": 50,
      "side": "buy",
      "externalId": "540d78ab-9d74-4ae3-8ffb-c96a959709ab"
  }

Ejemplo de Respuesta​

  {
      "id": "e1d73a31-2495-4f68-aa88-e251174552f4",
      "userId": "2946445a-f37d-4aaa-8327-e372adf763b8",
      "symbol": "AAPL",
      "qty": 0,
      "ammount": 50,
      "commission": 0.25,
      "side": "buy",
      "status": "pending"
  }

Próximos Pasos​