Trading - Acciones, Bonos y Cedears

Introducción

El módulo de Trading le permite a tu plataforma ofrecer a tus usuarios la operatoria completa de compra y venta de instrumentos del mercado de capitales argentino: CEDEARs, acciones y bonos. La integración es 100% vía APIs y webhooks.

Tus usuarios pueden consultar instrumentos y precios, enviar órdenes de compra y venta, hacer seguimiento del estado de sus operaciones y visualizar su portfolio en tiempo real.

Prerrequisitos

Onboarding

Para operar Trading, el usuario debe tener una cuenta comitente activa. El flujo de onboarding es el mismo que en los demás módulos:

1. POST /v2/persons → genera el person_id
2. POST /identity-documents → carga de documentación de identidad
3. POST /v2/investment-accounts → genera el investment_account_id
4. POST /bank-accounts → genera el bank_account_id (recomendado para habilitar retiros)

Sin cuenta comitente activa no es posible operar instrumentos de mercado.

Depósitos (Cash In)

Antes de enviar órdenes, el usuario debe contar con saldo disponible en su cuenta comitente. El proceso es el mismo que en los demás módulos: el usuario transfiere a la cuenta recaudadora y API Broker acredita el saldo automáticamente, notificando al partner vía webhook deposit_create.

Flujo de integración

a. Consulta de instrumentos

Antes de operar, tu plataforma puede consultar el catálogo completo de instrumentos disponibles.

Obtener todos los instrumentos:

GET /api/instruments/market/all

Devuelve el listado completo de CEDEARs, acciones y bonos disponibles para trading.

Recomendación: almacená los instrumentos en tu base de datos y actualizálos periódicamente (por ejemplo, una vez al día). Usá este catálogo para búsquedas por ticker, tipo de activo o mercado.

Obtener instrumento por ID:

GET /api/instruments/market/{market_instrument_id}

b. Consulta de precios

Una vez seleccionado el instrumento, se puede consultar su último precio disponible.

GET /api/prices/market-instrumentsprices/{market_instrument_id}

Util para mostrar precios en la UI, calcular montos estimados de compra o venta, y validar disponibilidad de saldo antes de enviar órdenes.

c. Envío de órdenes

Con el instrumento y el precio definidos, se envía la orden de compra o venta:

POST /api/market/market-order

Body params:

Body de ejemplo:

{
  "investment_account_id": 7403,
  "quantity": 10,
  "amount": 50000,
  "currency_id": "ARS",
  "market_instrument_id": 1234,
  "market_operation_type": "buy",
  "instrument_price": 5000,
  "term": 2,
  "external_id": "orden-abc-001",
  "by_amount": false,
  "at_market_price": false
}

Respuestas posibles:

Nota sobre idempotencia: el campo external_id es obligatorio y debe ser único por operación. Si se reintenta el envío con el mismo external_id, la API retornará 409 en lugar de crear una orden duplicada.

Nota sobre by_amount vs quantity: cuando by_amount es true, el sistema usa el campo amount para determinar cuántas unidades comprar al precio disponible. Cuando es false, usa el campo quantity directamente.

d. Estados de las órdenes

Las órdenes enviadas pueden atravesar los siguientes estados. Es importante distinguir los estados temporales de los finales para reflejarlos correctamente en tu UI.

e. Consulta del estado de una orden

Una vez enviada la orden, el partner puede consultar su estado en cualquier momento mediante el market_order_id devuelto en el POST /api/market/market-order/.

GET /api/market/market-order/{market_order_id}

Parámetros:

Respuestas posibles:

Nota: Este endpoint es útil para consultas puntuales y reconciliaciones. Para seguimiento en tiempo real, implementar el webhook market_order_update.

f. Obtención de boletos de las órdenes de mercado

Luego de ejecutadas las operaciones, el partner puede obtener los boletos (confirmaciones de mercado) asociados a una cuenta comitente. Esto es útil para mostrar comprobantes al usuario o para procesos de conciliación.

GET /api/market/stock-market-confirmations/confirmations-by-investment-account/{investment_account_id}

Path params:

Query params opcionales:

Ejemplo de uso:

GET /api/market/stock-market-confirmations/confirmations-by-investment-account/7403?from_date=2024-09-01&to_date=2024-09-30&page=1&size=50

Respuestas posibles:

Nota: Los boletos incluyen el detalle de cada operación ejecutada (instrumento, precio, cantidad, monto). Se recomienda consultar este endpoint para generar comprobantes descargables para el usuario final.

g. Consulta de cuenta, saldos y tenencias

Permite obtener el estado actualizado de la cuenta comitente del usuario.

GET /api/portfolio/accounts-tatements/{investment_account_id}

Este endpoint es clave para validar saldo antes de enviar órdenes, mostrar el portfolio del usuario y reflejar el impacto de órdenes ejecutadas.

h. Retiros (Cash Out)

Una vez que el usuario tiene fondos disponibles en su cuenta comitente, puede retirarlos a una cuenta bancaria same-name:

POST /withdraw-requests

API Broker notifica los cambios de estado del retiro vía webhook withdraw_request_update.

Estados posibles: IN_PROGRESS → COMPLETED / REJECTED

Endpoints principales

Webhooks a implementar

Tu plataforma debe exponer una URL para recibir los siguientes eventos:

deposit_create

Notifica los depósitos acreditados: investment_account_id, moneda, monto y fecha.

market_order_update (si disponible)

Notifica cambios de estado en las órdenes enviadas.

withdraw_request_update

Notifica el estado de los retiros: IN_PROGRESS, COMPLETED o REJECTED.

Los webhooks permiten mantener sincronizado el estado operativo sin necesidad de polling constante.

Consideraciones operativas

• Caché de instrumentos: almacená el catálogo de instrumentos y refrescalo periódicamente. No consultes el endpoint en cada operación.
• Validación previa: verificar saldo y tenencias antes de enviar órdenes evita rechazos innecesarios.
• Estados finales vs temporales: manejelos de forma diferenciada en tu UI para no generar confusión al usuario.
• Órdenes parciales y expiradas: reflejarlas claramente en el portfolio del usuario.
• Horarios de mercado: tener en cuenta el horario de operación de BYMA y el cierre diario para el manejo de órdenes.
• Idempotencia: usar external_id en las órdenes para evitar duplicados ante reintentos.

Soporte de desarrollo e integración

API Broker brinda soporte directo durante todo el proceso de integración.

Soporte técnico: implementación de APIs, webhooks y seguridad, manejo de estados de órdenes, testing conjunto en staging.

Soporte de negocio: modelo de revenue share, onboarding regulatorio del partner, estrategia de adopción del módulo.

Soporte operativo: monitoreo de órdenes, conciliación de depósitos y retiros, mesa de operaciones Adcap como respaldo.

El soporte está disponible los días hábiles de mercado de 9 a 18 hs.

Puntos clave para recordar

1. El onboarding es prerequisito: sin cuenta comitente activa no es posible operar.
2. El saldo debe estar disponible antes de enviar órdenes: siempre validar via account statements.
3. Distinguir estados temporales de finales: COMPLETED, REJECTED, NOT_SENT, EXPIRED y CANCELLED son estados finales.
4. Las órdenes parciales pueden ser temporales o finales según si son del día o de otro día.
5. Cachear el catálogo de instrumentos y actualizar periódicamente, no en cada operación.
6. Los retiros son solo a cuentas same-name: no se admiten transferencias a terceros.
7. Todo es asincrónico: siempre seguir el estado vía webhooks.