Documentación de la API

Guía de Migración de API — Actualización entre Versiones

Planea y ejecuta actualizaciones de versión de API sin problemas. Comprende los cambios importantes, cronogramas de desuso y mejores prácticas para migrar entre versiones de Smart Money API.

Publicado el 21 de marzo de 2026 • 16 min de lectura • Avanzado

Resumen de la Migración

Smart Money API se desarrolla activamente con actualizaciones regulares. Esta guía cubre la gestión de versiones, cambios importantes y cómo migrar tu integración sin tiempo de inactividad.

Principios clave de la migración:

  • Versionado Semántico — Formato MAJOR.MINOR.PATCH seguido estrictamente
  • Soporte a Largo Plazo — Versión mayor anterior soportada por 24+ meses
  • Advertencias de Desuso — Aviso con 6 meses de antelación sobre cambios importantes
  • Versiones Paralelas — Ejecuta v1 y v2 simultáneamente durante la migración
  • Pruebas Automatizadas — Herramientas de compatibilidad de suite de pruebas proporcionadas

Estado Actual: v1 (actual), v2 (beta, disponibilidad general Q2 2026). v1 soportada hasta Q1 2028.

Política de Versiones

Versionado Semántico

Formato de Versión
Versión de la API: MAJOR.MINOR.PATCH
Ejemplo: 2.1.3
MAJOR (2) - Cambios importantes, nueva arquitectura
MINOR (1) - Funciones compatibles con versiones anteriores
PATCH (3) - Correcciones de errores, actualizaciones de seguridad

Ciclo de Lanzamiento de Versiones

Fase Duración Características
Alpha 2-4 semanas Cambios importantes, solo pruebas
Beta 4-8 semanas Mayormente estable, feedback de la comunidad
Candidato a Lanzamiento 2-4 semanas Listo para producción, ajustes finales
Disponibilidad General 24+ meses Soporte completo en producción
Obtén tu clave API en 30 segundos

¿Listo para construir? Obtén una clave API gratuita (200 llamadas/día, sin tarjeta) y comienza a obtener datos en vivo de ballenas, financiamiento y cadena.

Obtén tu clave API →

Compatibilidad con Versiones Anteriores

Compatibilidad de Versiones

Dentro de una versión mayor, siempre puedes actualizar a versiones menores/parches de forma segura:

  • URLs de Endpoints — Permanecen sin cambios
  • Campos Requeridos — Nunca se eliminan (solo se añaden nuevos campos opcionales)
  • Códigos de Estado HTTP — Preservados para escenarios existentes
  • Estructura de Respuesta — Los campos principales permanecen idénticos
  • Autenticación — Sin cambios en los mecanismos de autenticación

Desuso Gradual

Cronograma de Desuso
// Mes 1: Anuncio de desuso
// Función marcada con encabezado Deprecation
Deprecation: version="2.2", sunset="2026-09-01"
// Mes 3-6: Período de desuso activo
// La API devuelve advertencias pero sigue funcionando
X-Deprecation-Warning: Este endpoint será eliminado el 2026-09-01
// Mes 6: Eliminación final
// El endpoint devuelve 410 Gone
HTTP/1.1 410 Gone

Migración de V1 a V2

Cambios Importantes

  • Rediseño de la API REST — Endpoints de recursos más limpios
  • Formato de Respuesta — Envoltura consistente, mejor manejo de errores
  • Autenticación — Se añade soporte para OAuth 2.0 (las claves API aún funcionan)
  • Límite de Tasa — Mejor granularidad y claridad
  • Webhooks — Formato de evento y firma rediseñados

Mapeo de Endpoints

Endpoint V1 Endpoint V2 Cambios
GET /whales GET /v2/whales/tracking Reorganizado, añadido filtrado
GET /funding GET /v2/derivatives/funding-heatmap Parámetro de exchange requerido
GET /positions GET /v2/derivatives/positions Nuevas opciones de agregación

Cambios en los Endpoints

Cambios en los Parámetros de Solicitud

Solicitud V1
// V1: Tasas de financiamiento
GET /v1/funding?symbol=BTCUSDT&exchange=binance
Solicitud V2
// V2: Mismos datos, estructura más clara
GET /v2/derivatives/funding-heatmap?
symbol=BTCUSDT&
exchange=binance

Actualizaciones del Formato de Respuesta

Estructura de Respuesta V1

Formato V1
{
status: success,
data: {
symbol: BTCUSDT,
funding: 0.0001
}
}

Estructura de Respuesta V2

Formato V2
{
data: {
symbol: BTCUSDT,
funding_rate: 0.0001
},
_meta: {
request_id: req_abc123,
timestamp: 1709980800000
}
}

Diferencias Clave: Sin envoltorio de estado, nombres de campos más claros, metadatos estandarizados.

Cronograma de Desuso

Desusos Planificados

Característica Anunciado Fecha de Desuso Reemplazo
/v1/whales Ene 2026 Ene 2028 /v2/whales/tracking
/v1/funding Ene 2026 Ene 2028 /v2/derivatives/funding-heatmap
Autenticación solo con clave API Mar 2026 Mar 2027 OAuth 2.0 (las claves aún funcionan)
Formato Webhook v1 Q2 2026 Q2 2027 Formato Webhook v2

Detalles de Cambios Importantes

Endpoints Eliminados

  • /v1/stats — Reemplazado por /v2/metrics
  • /v1/historical — Reemplazado por /v2/historical con nuevos parámetros
  • /v1/alerts/create — Reemplazado por POST /v2/alerts

Cambios en Parámetros

  • limit — Valor predeterminado cambiado de 100 a 20 (¡sé explícito!)
  • timeframe — Ahora es obligatorio en consultas históricas
  • sort — Formato cambiado de "field asc" a "field:asc"

Cambios en Campos de Respuesta

  • funding → funding_rate
  • price → mark_price
  • vol → volume_quote

Migración Paso a Paso

Fase 1: Planificación (Semana 1-2)

  1. Auditar la integración existente para características desusadas
  2. Mapear endpoints v1 a equivalentes v2
  3. Identificar cambios importantes que afecten tu código
  4. Planificar estrategia y cronograma de pruebas

Fase 2: Desarrollo (Semana 3-4)

  1. Crear rama v2 en control de versiones
  2. Actualizar todos los endpoints de API a URLs v2
  3. Actualizar manejo de solicitudes/respuestas
  4. Ejecutar pruebas unitarias en el entorno de pruebas

Fase 3: Pruebas (Semana 5-6)

  1. Ejecutar suite completa de pruebas de integración
  2. Probar escenarios de error y casos límite
  3. Pruebas de carga con endpoints v2
  4. Auditoría de seguridad del código actualizado

Fase 4: Puesta en Escena (Semana 7)

  1. Implementar código v2 en entorno de staging
  2. Ejecutar pruebas de aceptación completas
  3. Obtener aprobación de las partes interesadas
  4. Preparar plan de reversión

Fase 5: Producción (Semana 8)

  1. Implementación blue-green en producción
  2. Monitorear métricas y tasas de error
  3. Estar en guardia para problemas de soporte
  4. Desmantelar gradualmente el código v1

Soporte y Recursos

Herramientas Disponibles

  • Validador de Migración — Verificar código por uso desusado
  • Comprobador de Actualización de API — Comparar compatibilidad entre v1 y v2
  • Lista de Verificación de Migración — PDF con tareas y cronograma
  • Ejemplos de Código — Muestras antes/después de la migración

Obtener Ayuda

  • Correo electrónico: [email protected]
  • Documentación: Ver changelog-versioning.html
  • Discord: Canal de soporte comunitario
  • Empresa: Ingeniero de migración dedicado

Comienza tu Migración Hoy

Actualiza a la API v2 con herramientas de migración completas, documentación y soporte. Diseñado para soportar migración sin tiempo de inactividad.

Explora V2
V1 soportado hasta Ene 2028. Planifica tu migración hoy.

Recursos Relacionados

Registro de Cambios y Versiones →

Historial detallado de versiones

Referencia de API REST →

Documentación de la API V2

Guía de Pruebas →

Entorno de pruebas para pruebas
Comienza gratis — 200 llamadas/día, sin tarjeta

Obtén flujo de ballenas, financiamiento, interés abierto y datos on-chain de 3 exchanges desde una API. Nivel gratuito, sin tarjeta de crédito, actualiza en cualquier momento.

Comienza gratis →
Prueba la consola de API en vivo → (no se necesita cuenta)