La API de Alertas de Tipo de Cambio (FX Rate Alerts) de Cobre proporciona un mecanismo de notificación en tiempo real que permite a los clientes monitorear movimientos de tipos de cambio extranjeros y recibir alertas instantáneas cuando las condiciones del mercado cumplen umbrales predefinidos.

Esta función empodera a los equipos de tesorería y finanzas para capturar oportunidades de mercado favorables, gestionar el riesgo de divisas de manera proactiva, y optimizar el cronograma de pagos transfronterizos automatizando el monitoreo de tipos de cambio en múltiples pares de divisas.

Las Alertas de Tipo de Cambio siguen un ciclo de vida claro impulsado por condiciones configurables, monitoreo en tiempo real, y notificaciones webhook, asegurando que los clientes nunca pierdan movimientos críticos del mercado.

Crear Alertas de Tipo de Cambio

Los clientes crean Alertas de Tipo de Cambio definiendo condiciones de monitoreo para pares de divisas específicos. Una vez que una alerta está activa, la plataforma de Cobre monitorea continuamente las tasas de cambio en tiempo real y dispara notificaciones cuando se cumplen las condiciones.

Condiciones de Alerta Soportadas:

Por encima: Disparar cuando la tasa de cambio supera un umbral máximo

Por debajo: Disparar cuando la tasa de cambio cae por debajo de un umbral mínimo

Dentro del rango: Disparar cuando la tasa de cambio entra en un rango especificado

Para recibir notificaciones de alerta, los clientes deben suscribirse al evento:

alerts.fx_rate.triggered – Notificación cuando se cumple una condición de alerta

Una vez suscrito, los clientes recibirán un webhook cada vez que se dispare una alerta.

Ciclo de Vida de Alertas de Tipo de Cambio

Creación
El cliente crea una alerta mediante POST /v1/alerts con parámetros de condición y fecha de vencimiento.

Monitoreo Activo
Cobre monitorea las tasas de cambio en tiempo real para todas las alertas activas (active_status: true).

Evento Disparador
Cuando la tasa de mercado cumple la condición de alerta, se envía un webhook con la tasa de cambio que la disparó.

Desactivación
Los clientes pueden desactivar alertas mediante DELETE /v1/alerts/{id}, lo que establece active_status: false.

Las alertas desactivadas permanecen en el sistema con fines de auditoría pero no dispararán notificaciones. Las alertas también expiran automáticamente según su fecha valid_until.

Notificación de Disparo de Alerta

Los clientes reciben notificaciones de alerta a través de la API de Notificaciones cuando están suscritos a alerts.fx_rate.triggered. Más información: Notificaciones y Suscripciones

Metadatos de Alerta

El objeto metadata contiene la configuración de la alerta y la tasa de cambio que la disparó, cuando corresponda.

Campos de Metadatos

Campo	Descripción
`currency_pair`	Par de divisas siendo monitoreado (p. ej., `usd/cop`, `usd/mxn`)
`condition`	Tipo de condición de alerta: `above`, `below`, o `within_range`
`max_rate`	Umbral de tasa máxima (utilizado para condiciones `above` y `within_range`)
`min_rate`	Umbral de tasa mínima (utilizado para condiciones `below` y `within_range`)
`fx_rate`	La tasa de cambio actual que disparó la alerta (solo presente en notificaciones de disparo)

El campo fx_rate solo se incluye en cargas webhook alerts.fx_rate.triggered y representa la tasa de mercado en el momento en que se cumplió la condición de alerta.

Catálogo de Condiciones de Alerta

Las alertas pueden configurarse con tres tipos de condiciones diferentes según su estrategia de monitoreo.

Condición Por Encima

Condición Por Debajo

Condición Dentro del Rango

Lógica de Disparo: La alerta se dispara cuando current_rate > max_rate

Caso de Uso: Notificar cuando una divisa se fortalece más allá de un umbral

Campos Requeridos:

condition: "above"

max_rate: Umbral numérico

Ejemplo:

{
  "metadata": {
    "condition": "above",
    "currency_pair": "usd/cop",
    "max_rate": 3500
  }
}

Esquema de Solicitud para Crear Alertas

Al crear una nueva Alerta de Tipo de Cambio, envíe la siguiente carga:

{
  "type": "fx_rate",
  "alias": "Nombre de Mi Alerta",
  "metadata": {
    "condition": "above|below|within_range",
    "currency_pair": "usd/cop",
    "max_rate": 3500,
    "min_rate": 3400
  },
  "valid_until": "2026-12-31T23:59:59Z"
}

Descripciones de Campos

Campo	Tipo	Requerido	Descripción
`type`	string	Sí	Debe ser `"fx_rate"`
`alias`	string	No	Nombre amigable para la alerta
`metadata.condition`	string	Sí	Uno de: `above`, `below`, `within_range`
`metadata.currency_pair`	string	Sí	Par de divisas a monitorear (p. ej., `usd/cop`)
`metadata.max_rate`	number	Condicional	Requerido para `above` y `within_range`
`metadata.min_rate`	number	Condicional	Requerido para `below` y `within_range`
`valid_until`	string	Sí	Marca de tiempo ISO 8601 - fecha de vencimiento de la alerta

Mejores Prácticas

Configuración de Alertas

Establezca umbrales realistas basados en volatilidad histórica y sus ventanas de ejecución

Use condiciones within_range para estrategias de ejecución oportunistas

Establezca fechas valid_until apropiadas para evitar que se acumulen alertas antiguas

Gestión de Webhooks

Implemente verificaciones de idempotencia usando el event_id para manejar entregas webhook duplicadas

Almacene el valor fx_rate de alertas disparadas para auditoría y toma de decisiones

Configure monitoreo para fallos en la entrega de webhooks

Gestión de Alertas

Revise regularmente y desactive alertas que ya no sean relevantes

Use valores descriptivos en alias para identificar alertas en su equipo

Monitoree el campo updated_at para rastrear cuándo fueron modificadas las alertas por última vez

Seguridad

Valide todas las firmas de webhook antes de procesar

Use puntos finales HTTPS para la entrega de webhooks

Rote su event_signature_key periódicamente

Casos de Uso Comunes

Rate Lock Timing

Cobertura de Riesgo

Ventana de Oportunidad

Escenario: Ejecutar un pago grande USD/COP cuando la tasa caiga por debajo de 4000

Configuración:

{
  "type": "fx_rate",
  "alias": "Ventana de Ejecución de Pago",
  "metadata": {
    "condition": "below",
    "currency_pair": "usd/cop",
    "min_rate": 4000
  },
  "valid_until": "2026-06-30T23:59:59Z"
}

Flujo de Trabajo:

La alerta se dispara cuando USD/COP < 4000

Webhook recibido con fx_rate: 3985.50

Iniciar automáticamente solicitud de rate lock mediante API de Crear una Cotización FX

Ejecutar pago Cross Border a la tasa bloqueada

Pares de Divisas Soportados

Las Alertas de Tipo de Cambio actualmente soportan los siguientes pares de divisas:

Par de Divisas	Descripción
`usd/cop`	Dólar estadounidense a Peso colombiano
`cop/usd`	Peso colombiano a Dólar estadounidense
`usd/mxn`	Dólar estadounidense a Peso mexicano
`mxn/cop`	Peso mexicano a Peso colombiano

Pares de divisas adicionales pueden ser soportados en el futuro. Contacte a su representante de Cobre para solicitudes de pares de divisas personalizados.

Gestión de Errores

Escenarios de Error Comunes

Estado HTTP	Error	Resolución
`400 Bad Request`	Tipo de condición inválido	Use `above`, `below`, o `within_range`
`400 Bad Request`	Campos de tasa requeridos faltantes	Incluya `max_rate` para `above`, `min_rate` para `below`, ambos para `within_range`
`400 Bad Request`	Par de divisas inválido	Use solo pares de divisas soportados
`401 Unauthorized`	Autenticación inválida	Verifique sus credenciales de API y encabezado de autorización
`404 Not Found`	ID de alerta no existe	Verifique el ID de alerta de su lista de alertas
`422 Unprocessable Entity`	Fecha `valid_until` inválida	Asegúrese de que la fecha sea en el futuro y esté correctamente formateada

Límites de Tasa

La creación de alertas está sujeta a límites de cuenta.

Acciones realizadas en Alertas de Tipo de Cambio

➕ Crear Una Alerta

🔍 Obtener Todas las Alertas

📄 Obtener Alerta por ID

🗑️ Desactivar Una Alerta

Descripción: Crear una nueva alerta de monitoreo de tipo de cambio con condiciones personalizadas.

Qué esperar después de la acción:
Un objeto Alert recién creado con estado active_status: true e ID de alerta único.

Notificación Webhook:
Los suscriptores a alerts.fx_rate.created reciben una notificación inmediata.

📘 Más información: 🔗 Crear Una Alerta

Cómo Comenzar

Suscribirse a notificaciones de alerta

Suscribirse a alerts.fx_rate.triggered.

Crear su primera alerta

Enviar una solicitud POST a /v1/alerts con su condición deseada y par de divisas.

Monitorear entregas de webhook

Configurar un punto final de webhook para recibir notificaciones cuando se disparen alertas.

Verificar firmas de webhook

Validar webhooks entrantes usando el encabezado event_signature y la event_signature_key de su suscripción.

Tomar acción en alertas

Cuando una alerta se dispare, usar el valor fx_rate para decidir si bloquear tasas, ejecutar pagos o ajustar estrategias de cobertura.

Gestionar ciclo de vida de alertas

Listar, recuperar y desactivar alertas según las condiciones del mercado cambien.

Qué Esperar Después de Usar Esta API

Gestión proactiva del riesgo de FX

Reaccionar inmediatamente a movimientos de mercado favorables o desfavorables sin monitoreo manual.

Cronograma optimizado de pagos transfronterizos

Ejecutar transacciones a las tasas más ventajosas recibiendo notificaciones instantáneas.

Reducción de gastos operacionales

Automatizar monitoreo de divisas en lugar de verificar manualmente las tasas durante todo el día.

Cobertura de cartera multidivisa

Configurar alertas en múltiples pares de divisas (USD/COP, USD/MXN, MXN/COP, etc.) simultáneamente.

Pista de auditoría y cumplimiento

Mantener un historial completo de configuraciones de alertas y eventos de disparo para reportes de tesorería.

Integración con flujos de trabajo de negociación

Usar disparos de alertas como señales para iniciar bloqueos de tasa, solicitudes de cotización o ejecuciones de pago a través de otras APIs de Cobre.

Alertas FX

Crear Alertas de Tipo de Cambio#

Ciclo de Vida de Alertas de Tipo de Cambio#

Notificación de Disparo de Alerta#

Metadatos de Alerta#

Campos de Metadatos#

Catálogo de Condiciones de Alerta#

Esquema de Solicitud para Crear Alertas#

Descripciones de Campos#

Mejores Prácticas#

Configuración de Alertas#

Gestión de Webhooks#

Gestión de Alertas#

Seguridad#

Casos de Uso Comunes#

Pares de Divisas Soportados#

Gestión de Errores#

Escenarios de Error Comunes#

Límites de Tasa#

Acciones realizadas en Alertas de Tipo de Cambio#

Cómo Comenzar#

Qué Esperar Después de Usar Esta API#

Crear Alertas de Tipo de Cambio

Ciclo de Vida de Alertas de Tipo de Cambio

Notificación de Disparo de Alerta

Metadatos de Alerta

Campos de Metadatos

Catálogo de Condiciones de Alerta

Esquema de Solicitud para Crear Alertas

Descripciones de Campos

Mejores Prácticas

Configuración de Alertas

Gestión de Webhooks

Gestión de Alertas

Seguridad

Casos de Uso Comunes

Pares de Divisas Soportados

Gestión de Errores

Escenarios de Error Comunes

Límites de Tasa

Acciones realizadas en Alertas de Tipo de Cambio

Cómo Comenzar

Qué Esperar Después de Usar Esta API