trading-platform/orchestration/tareas/2026-01-25/TASK-2026-01-25-002-FRONTEND-COMPREHENSIVE-AUDIT/entregables/API-CONTRACTS-MASTER-MATRIX.md

API-CONTRACTS-MASTER-MATRIX.md

Matriz Maestra de Contratos API - Trading Platform Frontend

Proyecto: trading-platform Fecha: 2026-01-25 Total Endpoints: 113

---

Tabla Maestra de Endpoints API

OQI-001: Auth (15 endpoints)

#	Método	Endpoint	Componente Consumidor	Request Body	Response 200	Estado
1	POST	/auth/register	Register.tsx	{ email, password, name }	{ token, user }	✅
2	POST	/auth/login	Login.tsx	{ email, password }	{ token, user, refreshToken }	✅
3	POST	/auth/logout	SecuritySettings	{}	{ success: true }	✅
4	POST	/auth/logout-all	SecuritySettings	{}	{ success: true }	✅
5	POST	/auth/refresh	AuthService (auto)	{ refreshToken }	{ token }	❌ TODO
6	POST	/auth/forgot-password	ForgotPassword	{ email }	{ success: true }	✅
7	POST	/auth/reset-password	ResetPassword	{ token, password }	{ success: true }	✅
8	POST	/auth/verify-email	VerifyEmail	{ token }	{ success: true }	✅
9	POST	/auth/phone/send-otp	PhoneLoginForm	{ phone }	{ success: true }	✅
10	POST	/auth/phone/verify-otp	PhoneLoginForm	{ phone, code }	{ token, user }	✅
11	POST	/auth/oauth/callback	AuthCallback	{ code, provider }	{ token, user }	✅
12	GET	/auth/sessions	SecuritySettings	-	[ { id, device, ip, lastActive } ]	✅
13	DELETE	/auth/sessions/:sessionId	SessionsList	-	{ success: true }	✅
14	POST	/auth/2fa/enable	SecuritySettings (UI falta)	{ method: 'totp' }	{ qrCode, secret }	❌ TODO
15	POST	/auth/2fa/verify	SecuritySettings (UI falta)	{ code }	{ success: true }	❌ TODO

Cobertura: 87% (13/15)

---

OQI-002: Educación (14 endpoints)

#	Método	Endpoint	Componente Consumidor	Request Body	Response 200	Estado
16	GET	/education/categories	Courses (filtros)	-	[ { id, name, slug } ]	✅
17	GET	/education/courses	Courses	?category=&level=&search=&sort=&page=&limit=	{ courses: [], total, page }	✅
18	GET	/education/courses/:slug	CourseDetail	-	{ id, title, modules: [...] }	✅
19	POST	/education/courses/:courseId/enroll	CourseDetail (botón)	{}	{ enrollmentId }	✅
20	GET	/education/lessons/:lessonId	Lesson	-	{ id, title, videoUrl, content }	✅
21	POST	/education/lessons/:lessonId/progress	VideoProgressPlayer	{ progress: 0-100, timestamp }	{ success: true }	✅
22	POST	/education/lessons/:lessonId/complete	Lesson (auto)	{}	{ xpGained, badge? }	✅
23	GET	/education/quizzes/:quizId	Quiz	-	{ id, questions: [...] }	✅
24	POST	/education/quizzes/:quizId/submit	Quiz (submit)	{ answers: [] }	{ score, passed, xpGained }	✅
25	GET	/education/achievements	MyLearning	-	[ { id, title, icon, earnedAt } ]	✅
26	GET	/education/leaderboard	Leaderboard	?period=all_time|week|month	[ { rank, userId, name, xp } ]	✅
27	GET	/education/gamification/profile	MyLearning (stats)	-	{ xp, level, badges, streak }	✅
28	GET	/education/enrollments	MyLearning	-	[ { courseId, progress, lastAccessed } ]	✅
29	POST	/education/videos/upload	Creator Dashboard (NO EXISTE)	multipart/form-data (video)	{ videoId, processingStatus }	❌ FALTA

Cobertura: 93% (13/14) - Video upload bloqueante

---

OQI-003: Trading (20 endpoints)

#	Método	Endpoint	Componente Consumidor	Request Body	Response 200	Estado
30	GET	/trading/market/klines/:symbol	CandlestickChart	?interval=1h&limit=500	[ [timestamp, open, high, low, close, volume] ]	✅
31	GET	/trading/market/price/:symbol	SymbolInfoPanel	-	{ symbol, price, change24h }	✅
32	GET	/trading/market/ticker/:symbol	SymbolInfoPanel	-	{ high, low, volume, ... }	✅
33	GET	/trading/market/order-book/:symbol	OrderBookPanel	?limit=20	{ bids: [], asks: [] }	✅
34	GET	/trading/indicators/sma/:symbol	IndicatorConfigPanel	?period=20&interval=1h	[ { timestamp, value } ]	⚠️ NO RENDERIZA
35	GET	/trading/indicators/ema/:symbol	IndicatorConfigPanel	?period=12&interval=1h	[ { timestamp, value } ]	⚠️ NO RENDERIZA
36	GET	/trading/indicators/rsi/:symbol	IndicatorConfigPanel	?period=14&interval=1h	[ { timestamp, value } ]	⚠️ NO RENDERIZA
37	GET	/trading/indicators/macd/:symbol	IndicatorConfigPanel	?interval=1h	[ { timestamp, macd, signal, histogram } ]	⚠️ NO RENDERIZA
38	GET	/trading/indicators/bollinger/:symbol	IndicatorConfigPanel	?period=20&stdDev=2&interval=1h	[ { timestamp, upper, middle, lower } ]	⚠️ NO RENDERIZA
39	GET	/trading/paper/account	PaperTradingPanel	-	{ balance, equity, margin, ... }	✅
40	GET	/trading/paper/positions	PositionsList	-	[ { symbol, side, size, entryPrice, pnl } ]	✅
41	GET	/trading/paper/orders	TradesHistory	?status=open|closed	[ { id, symbol, side, type, status } ]	✅
42	POST	/trading/paper/orders	OrderForm	{ symbol, side, type, quantity, price? }	{ orderId, status }	✅
43	DELETE	/trading/paper/orders/:orderId	TradesHistory (cancel)	-	{ success: true }	✅
44	GET	/trading/alerts	AlertsPanel	-	[ { id, symbol, condition, price } ]	✅
45	POST	/trading/alerts	AlertsPanel (crear)	{ symbol, condition, price }	{ alertId }	✅
46	DELETE	/trading/alerts/:alertId	AlertsPanel (eliminar)	-	{ success: true }	✅
47	POST	/trading/drawings/save	ChartDrawingToolsPanel	{ symbol, interval, drawings: [] }	{ success: true }	❌ FALTA
48	GET	/trading/drawings/:symbol	ChartDrawingToolsPanel	?interval=1h	{ drawings: [] }	❌ FALTA
49	WebSocket	ws://localhost:3082/trading	useTradingWebSocket	-	Real-time price updates	❌ FALTA

Cobertura: 65% (13/20) - Indicadores renderizado, drawings persistencia, WebSocket faltan

---

OQI-004: Inversión (10 endpoints)

#	Método	Endpoint	Componente Consumidor	Request Body	Response 200	Estado
50	GET	/investment/accounts/summary	Investment (overview)	-	{ totalValue, totalGain, accounts: [] }	✅
51	GET	/investment/products	Products	-	[ { id, name, type, minInvestment, expectedReturn } ]	✅
52	GET	/investment/products/:productId	ProductDetail	-	{ id, name, description, performance: [] }	✅
53	GET	/investment/products/:productId/performance	ProductDetail (chart)	?period=1M|3M|1Y	[ { date, value } ]	✅
54	GET	/investment/accounts/:accountId	AccountDetail	-	{ id, balance, product, createdAt }	✅
55	GET	/investment/accounts/:accountId/transactions	Transactions	?type=&startDate=&endDate=	[ { id, type, amount, date } ]	✅
56	GET	/investment/accounts/:accountId/withdrawals	Withdrawals	-	[ { id, amount, status, requestedAt } ]	✅
57	POST	/investment/accounts/:accountId/deposits	DepositForm	{ amount, paymentMethodId }	{ depositId }	✅
58	POST	/investment/accounts/:accountId/withdrawals	WithdrawForm	{ amount, bankAccountId }	{ withdrawalId }	✅
59	POST	/investment/accounts	CreateAccountForm (NO EXISTE)	{ productId, initialAmount }	{ accountId }	❌ FALTA

Cobertura: 90% (9/10) - Creación cuentas bloqueante

---

OQI-005: Pagos Stripe (24 endpoints)

#	Método	Endpoint	Componente Consumidor	Request Body	Response 200	Estado
60	GET	/payments/plans	Pricing	-	[ { id, name, price, features: [] } ]	✅
61	GET	/payments/plans/:slug	Pricing (detalle)	-	{ id, name, price, features, stripePriceId }	✅
62	GET	/payments/subscription	Billing	-	{ id, planId, status, currentPeriodEnd }	✅
63	POST	/payments/subscription	Pricing (subscribe)	{ planId, paymentMethodId }	{ subscriptionId }	✅
64	POST	/payments/subscription/change-plan	SubscriptionUpgradeFlow	{ newPlanId }	{ subscriptionId, proratedAmount }	✅
65	POST	/payments/subscription/cancel	Billing (cancel)	{}	{ success: true }	✅
66	POST	/payments/subscription/reactivate	Billing (reactivate)	{}	{ success: true }	✅
67	GET	/payments/methods	PaymentMethodsList	-	[ { id, brand, last4, expiryMonth, expiryYear } ]	✅
68	POST	/payments/methods	PaymentMethodForm	{ cardNumber, expMonth, expYear, cvc }	{ methodId }	⚠️ PCI-DSS RISK
69	POST	/payments/methods/default	PaymentMethodsList	{ methodId }	{ success: true }	✅
70	DELETE	/payments/methods/:methodId	PaymentMethodsList	-	{ success: true }	✅
71	POST	/payments/checkout	Pricing (Hosted Checkout)	{ planId, successUrl, cancelUrl }	{ sessionId, checkoutUrl }	✅
72	POST	/payments/billing-portal	Billing (Stripe Portal)	{ returnUrl }	{ portalUrl }	✅
73	GET	/payments/invoices	InvoiceList	?limit=10	[ { id, amount, status, date, pdfUrl } ]	✅
74	GET	/payments/invoices/:invoiceId	InvoiceDetail	-	{ id, lineItems: [], total, pdfUrl }	✅
75	GET	/payments/invoices/:invoiceId/pdf	InvoiceDetail (download)	-	PDF binary	✅
76	GET	/payments/wallet	WalletCard	-	{ balance, available, pending }	✅
77	POST	/payments/wallet/deposit	WalletDepositModal	{ amount, paymentMethodId }	{ transactionId }	✅
78	POST	/payments/wallet/withdraw	WalletWithdrawModal	{ amount, bankAccountId }	{ withdrawalId }	✅
79	GET	/payments/wallet/transactions	TransactionHistory	?type=&startDate=&endDate=&page=&limit=	[ { id, type, amount, status, date } ]	✅
80	POST	/payments/coupons/validate	CouponForm	{ code }	{ valid: true, discount: 20 }	✅
81	POST	/payments/refunds	RefundModal (NO EXISTE)	{ invoiceId, reason }	{ refundId }	❌ FALTA
82	GET	/payments/usage	Billing (uso plan)	-	{ limit, used, percentage }	✅
83	POST	/payments/payment-intent	PaymentMethodForm (Stripe.js)	{ amount }	{ clientSecret }	❌ FALTA

Cobertura: 96% (23/24) - Payment Intent (PCI-DSS) crítico falta

---

OQI-006: ML Signals (12 endpoints)

#	Método	Endpoint	Componente Consumidor	Request Body	Response 200	Estado
84	GET	/api/v1/signals/active	MLDashboard	?symbol=&status=active	[ { id, symbol, direction, entry, sl, tp, confidence } ]	✅
85	GET	/api/v1/signals/latest/:symbol	PredictionCard	-	{ signal: {...}, validUntil }	✅
86	GET	/api/v1/amd/detect/:symbol	AMDPhaseIndicator	?timeframe=1H	{ currentPhase, probabilities: {...}, keyLevels: [] }	✅
87	GET	/api/v1/predict/range/:symbol	RangePredictor	?timeframe=1H	{ predictedHigh, predictedLow, confidence }	✅
88	POST	/api/v1/signals/generate	MLDashboard (refresh)	{ symbol, timeframe }	{ signal: {...} }	✅
89	POST	/api/ict/:symbol	ICTAnalysisCard	{ timeframe: '1H' }	{ orderBlocks: [], fvg: [], bias: 'bullish' }	✅
90	POST	/api/ensemble/:symbol	EnsembleSignalCard	{ timeframe: '1H' }	{ strategies: [], aggregatedSignal: {...} }	✅
91	GET	/api/ensemble/quick/:symbol	EnsembleSignalCard (quick)	-	{ signal: {...} }	✅
92	POST	/api/scan	MLDashboard (multi-symbol)	{ symbols: [], timeframe }	[ { symbol, signal: {...} } ]	✅
93	GET	/api/v1/backtest/results/:strategyId	BacktestResultsVisualization	-	{ trades: [], metrics: { winRate, profitFactor } }	✅
94	WebSocket	ws://localhost:3083/signals	useMLWebSocket	-	Real-time signal updates	❌ FALTA
95	POST	/api/v1/signals/:signalId/export	MLDashboard (export)	{ format: 'csv' | 'pdf' }	Blob (file download)	❌ FALTA

Cobertura: 83% (10/12) - WebSocket y exportación faltan

---

OQI-007: LLM Agent (6 endpoints)

#	Método	Endpoint	Componente Consumidor	Request Body	Response 200	Estado
96	POST	/api/v1/llm/sessions	Assistant (new chat)	{ title? }	{ sessionId, title }	✅
97	GET	/api/v1/llm/sessions	ConversationHistory	-	[ { id, title, createdAt, messageCount } ]	✅
98	GET	/api/v1/llm/sessions/:sessionId	Assistant (load)	-	{ id, title, messages: [] }	✅
99	POST	/api/v1/llm/sessions/:sessionId/chat	ChatInput (send)	{ content, role: 'user' }	{ id, role: 'assistant', content, toolCalls: [] }	✅
100	DELETE	/api/v1/llm/sessions/:sessionId	ConversationHistory (delete)	-	{ success: true }	✅
101	GET	/api/v1/llm/analyze/:symbol	Assistant (quick analyze)	-	{ analysis: '...' }	✅

Cobertura: 100% (6/6) - Backend funcional, falta persistencia BD y streaming

---

OQI-008: Portfolio (12 endpoints)

#	Método	Endpoint	Componente Consumidor	Request Body	Response 200	Estado
102	GET	/portfolio/portfolios	PortfolioDashboard	-	[ { id, name, totalValue, allocations: [] } ]	✅
103	GET	/portfolio/portfolios/:portfolioId	PortfolioDashboard (detalle)	-	{ id, name, allocations: [], performance: [] }	✅
104	POST	/portfolio/portfolios	CreatePortfolio	{ name, riskProfile, allocations: [] }	{ portfolioId }	✅
105	PUT	/portfolio/portfolios/:portfolioId	EditAllocations	{ name?, allocations? }	{ success: true }	✅
106	DELETE	/portfolio/portfolios/:portfolioId	PortfolioDashboard (delete)	-	{ success: true }	✅
107	GET	/portfolio/portfolios/:portfolioId/performance	PerformanceChart	?period=1M|3M|1Y	[ { date, value } ]	✅
108	PUT	/portfolio/portfolios/:portfolioId/allocations	EditAllocations (save)	{ allocations: [] }	{ success: true }	✅
109	GET	/portfolio/goals	PortfolioDashboard (goals)	-	[ { id, name, targetAmount, deadline } ]	✅
110	POST	/portfolio/goals	CreateGoal	{ name, targetAmount, deadline }	{ goalId }	✅
111	DELETE	/portfolio/goals/:goalId	PortfolioDashboard (delete goal)	-	{ success: true }	✅
112	GET	/portfolio/recommendations/rebalance/:portfolioId	RebalanceCard	-	{ recommended: [], changes: [] }	✅
113	POST	/portfolio/optimize/:portfolioId	OptimizeButton (NO EXISTE)	{ method: 'markowitz', constraints: {} }	{ optimizedAllocations: [] }	❌ FALTA

Cobertura: 92% (11/12) - Markowitz optimization bloqueante

---

OQI-009: MT4 Gateway (0 endpoints - TODO completo)

#	Método	Endpoint	Componente Consumidor	Request Body	Response 200	Estado
-	-	TODOS FALTANTES	MT4 components (stubs)	-	-	❌ 0%

Cobertura: 0% - Epic completo NO IMPLEMENTADO

---

Resumen Global

Epic	Total Endpoints	Implementados	Faltantes	Cobertura
OQI-001 (Auth)	15	13	2	87%
OQI-002 (Educación)	14	13	1	93%
OQI-003 (Trading)	20	13	7	65%
OQI-004 (Inversión)	10	9	1	90%
OQI-005 (Pagos)	24	23	1	96%
OQI-006 (ML Signals)	12	10	2	83%
OQI-007 (LLM Agent)	6	6	0	100%
OQI-008 (Portfolio)	12	11	1	92%
OQI-009 (MT4)	0	0	0+	0%
TOTAL	113	98	15	87%

---

Endpoints Críticos Faltantes (Bloqueantes)

Epic	Endpoint	Criticidad	Impacto
OQI-001	POST /auth/refresh	P0	Token refresh manual
OQI-002	POST /education/videos/upload	P0	Video upload bloqueado
OQI-003	WebSocket trading	P0	Real-time data (polling 30s)
OQI-003	POST /trading/drawings/save	P1	Drawing tools orphaned
OQI-004	POST /investment/accounts	P0	Creación cuentas bloqueada
OQI-005	POST /payments/payment-intent	P0	PCI-DSS non-compliant
OQI-006	WebSocket signals	P1	Polling 60s vs real-time
OQI-008	POST /portfolio/optimize	P0	Markowitz optimization
OQI-009	ALL	P0	Epic completo NO FUNCIONA

---

Actualizado: 2026-01-25 Próxima actualización: Después de implementar Fase 1