Cómo integrar una API forex WebSocket
Integrar una API forex WebSocket consiste en autenticar tu servidor, seleccionar pares de divisas y mantener las actualizaciones durante las interrupciones de conexión. Esta guía recorre esos pasos para QUOTC, con enlaces a las definiciones de mensajes y a los clientes completos de Python y Node.js.
Integrar una API forex WebSocket consiste en autenticar tu servidor, seleccionar pares de divisas y mantener las actualizaciones durante las interrupciones de conexión. Esta guía recorre esos pasos para QUOTC, con enlaces a las definiciones de mensajes y a los clientes completos de Python y Node.js.
Las cotizaciones de QUOTC se generan mediante algoritmos, no son precios del mercado ni reflejan sus condiciones reales. Lee la Advertencia de riesgos antes de decidir si los datos encajan con tu producto.
La conexión debe establecerse en tu backend. Tu frontend recibe las actualizaciones de tu aplicación, mientras la clave de API permanece en el servidor.
Antes de empezar con una API forex WebSocket
Prepara tu servidor antes de crear una clave de prueba. Confirma su dirección IP pública y cómo recibirá las credenciales tu aplicación.
Necesitas:
Un servidor con una dirección IPv4 o IPv6 pública conocida.
Una clave de prueba de QUOTC vinculada a esa dirección.
La clave almacenada en una variable de entorno.
Un proceso de backend capaz de mantener una conexión WebSocket.
Registros del estado de conexión, la autenticación y las interrupciones.
La clave de prueba gratuita proporciona 10 pares de divisas durante 14 días desde su creación, con una clave de prueba por cuenta.
Utiliza la variable de entorno QUOTC_API_KEY, como en los ejemplos oficiales. Mantén su valor fuera de los archivos de código, los repositorios y los registros de diagnóstico.
La dirección registrada debe coincidir con la IP pública utilizada por tu conexión saliente. Una dirección privada dentro de la red de tu servidor no es suficiente.
Consulta la documentación sobre claves y vinculación a IP y la guía sobre claves de API vinculadas a IP.
Conecta y autentícate
Abre una conexión WebSocket con wss://wss.quotc.net.
Dentro de los 10 segundos posteriores a su apertura, envía un mensaje de autenticación con tu clave y establece protocol en 2.
Esta configuración habilita los mensajes de servicio, incluidos auth_ok y subscribed. Estas respuestas ayudan a tu cliente a distinguir un socket abierto de una sesión autenticada.
No interpretes un handshake WebSocket correcto como prueba de que la clave fue aceptada. Espera a recibir auth_ok antes de configurar la suscripción.
La respuesta de autenticación contiene:
| Elemento | Significado | Qué debes comprobar |
|---|---|---|
| auth_ok | La autenticación se ha completado correctamente | Continúa con la selección de pares |
| symbols | Pares disponibles para la clave, incluidos sus símbolos, etiquetas y precisión decimal | Confirma que los pares solicitados están disponibles |
| expiresAt | Fecha de caducidad de la clave en segundos Unix, UTC | Convierte el valor utilizando segundos, no milisegundos |
Mantén visibles los fallos de autenticación en tus registros sin guardar el token.
Para conocer los formatos exactos de los mensajes, consulta la documentación sobre conexión y autenticación.
Lee e interpreta los mensajes de cotizaciones
QUOTC envía un mensaje de cotización cada segundo por cada par disponible, según tu selección de suscripción.
El flujo también contiene mensajes de servicio. Identifica el tipo de mensaje antes de enviar su contenido a la lógica de gráficos o almacenamiento.
Utiliza las siguientes definiciones de campos:
| Campo | Significado | Cómo utilizarlo |
|---|---|---|
| symbol | Identificador del par, como EURUSD | Dirige la actualización al instrumento correcto |
| value | Valor de cierre del último segundo | Utilízalo como cierre del segundo o como último valor mostrado |
| open | Valor de apertura del último segundo | Consérvalo al construir velas de mayor duración |
| high | Valor más alto del último segundo | Utilízalo para calcular el máximo de un intervalo |
| low | Valor más bajo del último segundo | Utilízalo para calcular el mínimo de un intervalo |
| volume | Actividad relativa del último segundo | Muéstralo como actividad, no como volumen negociado |
| ts | Marca de tiempo Unix en milisegundos, UTC | Utilízala para ordenar, almacenar y delimitar las velas |
Los campos de precios resumen el último segundo. No deben interpretarse como registros de operaciones individuales.
Conserva la marca de tiempo original en los registros almacenados. Conviértela en una fecha legible solo cuando tu interfaz o tus registros lo necesiten.
Utiliza internamente valores UTC con información de zona horaria. Aplica la zona horaria preferida del usuario al mostrar los datos.
Revisa las definiciones de los campos de cotizaciones antes de conectar el flujo a los componentes de gráficos existentes.
Selecciona pares con subscribe
De forma predeterminada, una conexión autenticada recibe todos los pares disponibles para su clave.
Envía subscribe para limitar el flujo a una lista concreta. Utiliza símbolos de API como EURUSD y USDJPY, no etiquetas visibles que contengan barras.
El servidor responde con subscribed, confirmando los símbolos seleccionados.
Compara esa respuesta con la lista solicitada por tu aplicación. El servidor ignora los pares no disponibles para la clave, por lo que la conexión puede funcionar sin entregar todos los pares solicitados.
Comprueba que la selección confirmada contiene al menos un par antes de esperar cotizaciones.
Puedes enviar otro mensaje de suscripción para cambiar la lista. Después de reconectar, autentícate de nuevo y vuelve a aplicar la selección deseada.
La documentación sobre solicitudes de ping y suscripción contiene los formatos de los mensajes.
Mantén la conexión en buen estado
Un socket abierto no garantiza que sigan llegando actualizaciones útiles. Supervisa tanto la conexión como el flujo de cotizaciones.
Envía un ping JSON cada 30 segundos
Envía el mensaje JSON ping de QUOTC a nivel de aplicación cada 30 segundos. El servidor devuelve pong con la misma marca de tiempo.
Este intercambio es independiente de las tramas Ping y Pong del protocolo WebSocket.
El mecanismo automático de mantenimiento de conexión de una biblioteca no envía el mensaje JSON de QUOTC. Configura explícitamente el heartbeat de la aplicación siguiendo la documentación.
Procesa las respuestas pong por separado de las cotizaciones. Un pong confirma la respuesta al heartbeat; no debe almacenarse como una actualización de precio.
Reconecta después de 10 segundos sin cotizaciones
Como recomendación de integración, considera que la conexión ha dejado de funcionar si no llega ninguna cotización durante 10 segundos después de autenticarte y confirmar una suscripción válida.
Este es un tiempo de espera sugerido para el cliente, no una regla de QUOTC.
Mide el tiempo transcurrido con un temporizador monotónico. Reinícialo cuando llegue una cotización, no cuando llegue cualquier mensaje.
Si se supera el tiempo de espera, cierra el socket existente y reconecta después de tres a cinco segundos. Autentícate y suscríbete de nuevo.
Una denegación explícita de acceso tiene prioridad: si recibes el código de cierre 1008, detén los intentos en lugar de reconectar.
Comprueba también que un procesamiento lento no esté causando esa aparente ausencia de datos. Las escrituras en bases de datos y otras tareas bloqueantes no deben impedir que el receptor lea mensajes.
Reconecta según el tipo de fallo
Utiliza un único controlador de reconexión por conexión. Varios temporizadores que respondan al mismo fallo pueden crear sockets duplicados.
| Evento | Acción recomendada |
|---|---|
| Código de cierre 1008 | Detén los intentos. Comprueba el estado de la clave, la IP del servidor y el número de conexiones antes de reiniciar |
| Código de cierre 1011 | Espera 3–5 segundos, reconecta y autentícate de nuevo |
| Error de red o reinicio del servicio | Espera 3–5 segundos y reconecta |
| Error HTTP durante el handshake WebSocket, como 503 durante un reinicio del servicio | Espera 3–5 segundos e intenta establecer una nueva conexión |
| Ausencia de cotizaciones durante 10 segundos después de una suscripción válida | Cierra el socket y reconecta después de 3–5 segundos, aplicando el tiempo de espera recomendado para el cliente |
| Tipo de mensaje desconocido | Regístralo e ignóralo; no detengas el cliente |
| Configuración no válida (falta la clave o los pares solicitados no están disponibles) | Detén el cliente y corrige la configuración en lugar de reintentar |
El código 1008 puede indicar una clave desconocida, inactiva, caducada o eliminada, una IP incorrecta, demasiadas conexiones o falta de autenticación.
Reintentar con las mismas credenciales no resuelve estas situaciones.
Gestiona los fallos del handshake y los cierres de conexiones ya establecidas. Un error HTTP puede producirse antes de que tu cliente reciba un código de cierre WebSocket.
Cancela las tareas de heartbeat y las comprobaciones de tiempo de espera anteriores antes de iniciar otra sesión.
Consulta la documentación sobre códigos de cierre y reconexión.
Clientes de Python y Node.js
La documentación oficial proporciona clientes completos para ambos lenguajes.
| Integración | Biblioteca utilizada por el ejemplo oficial | Por dónde empezar |
|---|---|---|
| Python | websockets, con asyncio | Cliente oficial de Python |
| Node.js | ws | Cliente oficial de Node.js |
Ambos clientes están disponibles en los ejemplos completos de código.
En Python, organiza las tareas de recepción, heartbeat y reconexión para que terminen correctamente cuando se cierre una sesión.
Comprueba la conversión de marcas de tiempo y la gestión de excepciones antes de añadir escrituras en bases de datos.
En Node.js, elimina los intervalos anteriores cuando se cierre una conexión, antes de abrir otro socket.
Antes de pasar a producción
Cada clave permite hasta 10 conexiones simultáneas. Cuenta todos los procesos que la comparten, incluidas herramientas de desarrollo, procesos de trabajo y servicios en segundo plano.
Recibe los datos forex por WebSocket en tu backend y transmite las actualizaciones necesarias a tu frontend. Evita crear una conexión con el proveedor por cada visitante.
Mantén la clave fuera de navegadores, aplicaciones móviles y repositorios públicos. Si se filtra, contacta con soporte para reemplazarla.
Los cambios de IP también se tramitan a través de soporte. Planifica ese paso antes de trasladar el cliente a un servidor con otra dirección pública.
Una clave de producción incluye 58 pares de divisas y cuesta 500 USD al mes por clave. El equipo de soporte gestiona manualmente la activación y la renovación después del pago.
Contacta con soporte para organizar el pago. Consulta la descripción del producto y la guía para pasar de una clave de prueba a producción antes de cambiar de acceso.
Preguntas frecuentes
¿Puedo conectarme gratis a una API forex WebSocket?
QUOTC ofrece una clave de prueba gratuita por cuenta. Proporciona 10 pares de divisas durante 14 días desde su creación, en lugar de acceso gratuito permanente.
¿Qué bibliotecas utilizan los ejemplos de Python y Node.js?
El ejemplo oficial de Python utiliza websockets con asyncio. El ejemplo de Node.js utiliza ws.
Ambos clientes completos están disponibles en la sección de ejemplos de la documentación.
¿Por qué se cierra la conexión con el código 1008?
Comprueba el estado de la clave, la IP registrada del servidor y el número de conexiones. La autenticación también debe enviarse dentro de los 10 segundos.
Detén los reintentos automáticos con la misma clave hasta resolver la causa.
¿Por qué las marcas de tiempo de las cotizaciones y la caducidad de la clave utilizan unidades diferentes?
El campo ts de las cotizaciones utiliza milisegundos Unix. El campo expiresAt de la autenticación utiliza segundos Unix.
Convierte cada uno según su definición y utiliza una zona horaria explícita.
¿Las respuestas pong indican que el flujo de cotizaciones funciona correctamente?
Confirman las respuestas al heartbeat, pero no la recepción de cotizaciones.
Supervisa las cotizaciones por separado. Recomendamos reconectar después de 10 segundos sin cotizaciones tras la autenticación y una suscripción válida.
Empieza tu integración: crea una cuenta en QUOTC y solicita una clave de prueba gratuita para 10 pares de divisas durante 14 días.