Saltar a contenido

Contratos de integracion#

REST#

  • El backend expone endpoints documentados en rest-openapi.yaml. Usa OpenAPI 3.1.
  • Autenticacion (produccion/demos externas):
  • Con AUTH_ENABLED=true, la API requiere Authorization: Bearer <token> en casi todos los endpoints.
  • Login: POST /auth/login devuelve access_token (JWT HS256).
  • Endpoints publicos esperados aun con auth habilitado: GET / y POST /auth/login.
  • Si se desea una barrera adicional en lectura operativa, /ops/* puede requerir X-Ops-Token via OPS_READ_TOKEN.
  • Versionado: todas las rutas actuales son v1 implicito. Si se agregan rutas breaking, considerar prefijo /v1.

Ejemplos#

# 1) Login -> obtener token
TOKEN=$(
  curl -sS -X POST http://127.0.0.1:8096/auth/login \
    -H "Content-Type: application/json" \
    -d '{"email":"admin@example.com","password":"***"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])"
)

# Alertas abiertas
curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:8096/analytics/goals/alerts?status=open&limit=20"

# Resolver alerta
curl -X POST http://127.0.0.1:8096/analytics/goals/alerts/123/resolve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note": "Reducimos lotaje y ajustamos stops"}'

Datos de mercado para frontend / TradingView#

  • Ticks historicos (para inspeccion fina o calculos propios):
curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:8096/market-data/ticks?symbol=EURUSD&limit=500"
  • Velas historicas (pensadas para integracion con TradingView u otros chartings):
curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:8096/market-data/candles?symbol=EURUSD&timeframe=M1&limit=1000"

Parametros soportados:

  • symbol: par/simbolo (EURUSD, XAUUSD, etc.).
  • timeframe: string tipo M1, M15, H1, etc.
  • limit: maximo de velas a devolver (por defecto 500).
  • from_timestamp, to_timestamp (opcional): rango temporal (ISO8601).

Binance (cuenta/estado/trading)#

curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8096/binance/status
curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:8096/binance/account?nonzero_only=true"

Webhooks externos#

  • scripts/notify_external_alerts.py genera alertas operativas en logs (texto plano) y mantiene estado en storage/alerts/alert_state.json: 
     Goal Alerts abiertas

[Goal Alert #18] DAILY window (2025-02-11 00:00 -> 2025-02-11 23:59)  consecutive misses: 2
Motivo: P/L diario < objetivo
  • TODO: evaluar integracion con canales locales (correo/Telegram/self-hosted) si se requiere notificacion push externa.

Integraciones externas#

  • Binance API: market data + trading (spot/futures) segun BINANCE_BASE_URL y credenciales del entorno.
  • News/macro providers: claves NEWSAPI_KEY, PRIXE_API_KEY, TRADINGECONOMICS_API_KEY (o FMP_API_KEY) guardadas como variables de entorno.
  • BI consumers: acceden a storage/bi_exports/ (montar carpeta o servir via /bi/datasets).

Manten sincronizadas las definiciones con el codigo; al introducir nuevos endpoints o webhooks, actualiza rest-openapi.yaml, este documento y agrega ADR si cambia el contrato.