🔌 API de Analítica

La API de Analítica es el componente de la Capa 2 (Backend 2) que proporciona acceso a los datos procesados y agregados del mercado P2P. Está diseñada para ser consumida por la Capa de Visualización (Frontend) y otras aplicaciones externas que requieran información analítica.

Endpoints de Consulta

Esta API expone una variedad de endpoints para consultar diferentes aspectos del mercado P2P. A continuación, se describen algunos ejemplos clave:

`GET /api/v1/analytics/summary`

Descripción: Proporciona un resumen de las métricas clave del mercado P2P, como el número total de ofertas, el volumen total, el spread promedio, etc.
Parámetros de Consulta (Query Parameters):
- asset (opcional, string): Filtra por el activo (ej. USDT, BTC).
- fiat (opcional, string): Filtra por la moneda fiat (ej. ARS, USD).
- trade_type (opcional, string): Filtra por tipo de operación (BUY o SELL).
Autenticación: Puede ser un endpoint público o requerir autenticación ligera (ej. API Key de lectura).

Ejemplo de Respuesta (Response)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "total_offers": 1500,
  "total_volume_usd": 125000.75,
  "average_buy_spread": 0.015,
  "average_sell_spread": 0.012,
  "last_updated": "2025-07-30T10:30:00Z"
}

`GET /api/v1/analytics/historical_spreads`

Descripción: Devuelve datos históricos de spreads para un par de activo/fiat específico, permitiendo el análisis de tendencias a lo largo del tiempo.
Parámetros de Consulta (Query Parameters):
- asset (requerido, string): Activo (ej. USDT).
- fiat (requerido, string): Moneda fiat (ej. ARS).
- start_date (opcional, date): Fecha de inicio para el rango histórico (formato YYYY-MM-DD).
- end_date (opcional, date): Fecha de fin para el rango histórico (formato YYYY-MM-DD).
- interval (opcional, string): Agregación de tiempo (ej. hourly, daily, weekly).
Autenticación: Requiere autenticación (ej. API Key de lectura o JWT).

Ejemplo de Respuesta (Response)

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "timestamp": "2025-07-29T00:00:00Z",
    "asset": "USDT",
    "fiat": "ARS",
    "buy_spread": 0.016,
    "sell_spread": 0.013,
    "volume_usd": 10000.00
  },
  {
    "timestamp": "2025-07-30T00:00:00Z",
    "asset": "USDT",
    "fiat": "ARS",
    "buy_spread": 0.015,
    "sell_spread": 0.012,
    "volume_usd": 12000.00
  }
]

`GET /api/v1/analytics/order_book_depth`

Descripción: Proporciona una representación de la profundidad del libro de órdenes para un par de activo/fiat, simulando la liquidez disponible en diferentes niveles de precio.
Parámetros de Consulta (Query Parameters):
- asset (requerido, string): Activo (ej. USDT).
- fiat (requerido, string): Moneda fiat (ej. ARS).
- trade_type (requerido, string): Tipo de operación (BUY o SELL).
- limit (opcional, integer): Número de niveles de profundidad a devolver (por defecto: 10).
Autenticación: Requiere autenticación.

Ejemplo de Respuesta (Response)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "asset": "USDT",
  "fiat": "ARS",
  "trade_type": "BUY",
  "depth": [
    {
      "price": 1050.00,
      "amount": 500.00,
      "cumulative_amount": 500.00
    },
    {
      "price": 1049.50,
      "amount": 750.00,
      "cumulative_amount": 1250.00
    },
    {
      "price": 1049.00,
      "amount": 1000.00,
      "cumulative_amount": 2250.00
    }
  ]
}

Consideraciones de Rendimiento y Escalabilidad

Caché: La API de Analítica utiliza mecanismos de caché (ej. Redis) para almacenar los resultados de consultas frecuentes, reduciendo la carga sobre la base de datos y mejorando los tiempos de respuesta. Se recomienda que los clientes implementen también estrategias de caché.
Paginación: Para endpoints que pueden devolver grandes volúmenes de datos, se implementa paginación (limit y offset o page y size) para evitar la sobrecarga de la red y del cliente.
Throttling: Se aplican límites de tasa a los endpoints para prevenir abusos y asegurar la disponibilidad del servicio para todos los consumidores.
Optimización de Consultas: Las consultas a la base de datos están optimizadas con índices y técnicas de agregación eficientes para garantizar un rendimiento óptimo.

La API de Analítica es la puerta de entrada a la inteligencia de mercado generada por el P2P Dashboard, permitiendo a los desarrolladores construir aplicaciones y herramientas poderosas sobre esta base de datos enriquecida.