Cómo añadir un widget del precio del oro en vivo a tu sitio web

Qué vas a insertar

Un widget de MetalAPI es un pequeño tablero de precios que MetalAPI aloja por ti. Lo configuras una vez en el panel, pegas un fragmento de dos líneas en tu página y los visitantes ven los precios actuales del oro, la plata, el platino, el paladio, los metales industriales, la energía, las divisas o las criptomonedas. El widget se muestra dentro de un iframe servido desde metalapi.com. No hay código de backend que escribir, ninguna clave API en tu HTML y nada que actualizar por tu parte cuando se mueven los precios.

Por eso un widget es la opción más rápida para sitios de contenido, joyerías y tiendas de metales de inversión, páginas de noticias y blogs que quieren mostrar el precio actual junto a su propio contenido. Si necesitas el precio dentro de tu propio marcado o en un cálculo, la API REST encaja mejor. La última sección de este artículo trata ese caso.

El tráfico de los widgets lo sirve el endpoint de widgets de MetalAPI, no tu clave API, así que las visitas a la página no consumen tu cuota mensual de solicitudes. Tu plan determina cuántos widgets puedes guardar y lo recientes que son sus precios; ambas cosas se explican más abajo.

Crea el widget en el panel

Los widgets están incluidos en todos los planes, también en Free. Crea una cuenta, abre Widgets en el panel y haz clic en New widget. El editor muestra una vista previa en vivo junto al formulario, así que puedes probar opciones antes de guardar:

Hay dos detalles fáciles de pasar por alto. Si dejas la unidad en onza troy, los metales industriales se muestran en su unidad de mercado habitual, así que el cobre aparece por libra mientras que el oro sigue por onza troy. Y una unidad en gramos o kilogramos solo convierte los metales: las divisas, la energía y las criptomonedas mantienen sus propias unidades. Si no tienes claro qué unidad de peso esperan tus visitantes, la guía de conversión de unidades explica las diferencias.

Al guardarlo, el widget recibe un ID público como w_abc123. El código de inserción solo hace referencia a ese ID; la configuración se queda en los servidores de MetalAPI. Si más adelante cambias los símbolos, los colores o el diseño, todas las páginas que insertan el widget muestran la nueva versión en su siguiente carga, sin cambiar el fragmento de tu sitio. La lista de widgets también tiene un interruptor Live para desactivar un widget sin borrarlo, y un contador de visualizaciones por widget.

El código de inserción, línea a línea

Después de guardar, el editor muestra el código de inserción:

<div id="metalapi-widget-w_abc123"></div>
<script src="https://metalapi.com/js/widget.js" data-widget="w_abc123" async></script>

El script es un pequeño cargador de unos 4 KB sin comprimir. Lee data-widget, busca el elemento con el id metalapi-widget-<id> y lo rellena con un iframe que carga https://metalapi.com/embed/<id>. Si falta el contenedor, el cargador crea uno justo antes de la etiqueta script. El widget, dentro del marco, comunica su altura con postMessage y el cargador ajusta el iframe a ella, así que una tabla que pasa de tres filas a seis nunca muestra una barra de desplazamiento.

El cargador solo se ejecuta una vez por página, aunque la etiqueta script aparezca varias veces. Para mostrar varios widgets en una página, incluye el script una sola vez y marca cada contenedor con un atributo data-metalapi-widget en lugar de un id:

<div data-metalapi-widget="w_abc123"></div>
<div data-metalapi-widget="w_def456"></div>

<script src="https://metalapi.com/js/widget.js" async></script>

El cargador busca estos contenedores una sola vez, cuando la página ha terminado de cargarse. No ve los contenedores que el JavaScript del cliente añada después, por ejemplo tras un cambio de ruta en una aplicación de una sola página. En ese caso, o si no puedes añadir scripts, inserta el marco directamente:

<iframe
  src="https://metalapi.com/embed/w_abc123"
  title="Live gold price"
  loading="lazy"
  style="border:0;width:100%;height:220px"
></iframe>

Sin el cargador, el iframe no puede ajustar su tamaño, así que dale una altura adecuada al diseño que hayas elegido. Las páginas que todavía usan el antiguo fragmento new MetalAPIWidget({...}) del generador de widgets anterior siguen funcionando: los widgets guardados se muestran por su ID, y cualquier clave API que quede en un fragmento antiguo se ignora.

HTML simple, WordPress y Shopify

HTML simple. Pega el fragmento donde deba aparecer el widget, por ejemplo en una barra lateral o en la parte superior de una página de precios. Gracias al atributo async, el cargador nunca bloquea el resto de la página mientras se descarga.

WordPress. En el editor de bloques, añade un bloque HTML personalizado (Custom HTML) y pega el fragmento. Para mostrar el widget en todas las páginas, colócalo en un widget de HTML personalizado dentro de una zona de widgets de la barra lateral o del pie de página, o en los archivos de plantilla de tu tema. Algunas configuraciones, como las redes multisitio o los planes de alojamiento restringidos, eliminan las etiquetas <script> del contenido. Si el widget no aparece después de publicar, revisa el código fuente de la página. Si falta la etiqueta script, usa la versión con iframe, que no necesita ningún script.

Shopify. En el editor de temas (Tienda online → Temas → Personalizar), añade una sección o un bloque Liquid personalizado (Custom Liquid) en la plantilla donde deba ir el widget y pega el fragmento. Para mostrarlo solo en las páginas de producto, añade el bloque a la plantilla de producto. También puedes colocar el fragmento directamente en un archivo de sección cuando editas el código del tema.

Otros creadores de sitios web. Los creadores con un elemento HTML o de inserción funcionan igual, por ejemplo el code embed de Webflow o un bloque de código de Squarespace. Algunos creadores envuelven el HTML personalizado en un iframe propio, y el ajuste automático de tamaño no puede atravesarlo. En ese caso, dale una altura fija al elemento de inserción.

Límites del plan, actualidad y marca

Un widget guardado muestra precios tan recientes como permite el plan de su propietario y consulta los datos nuevos por sí solo. El intervalo de consulta sigue el intervalo de actualización del plan, pero nunca es inferior a 30 segundos ni superior a 15 minutos:

En Free y Lite, el widget busca datos nuevos con más frecuencia de la que cambian los precios, así que recoge cada actualización sin recargar la página. Cada widget muestra en la parte inferior la hora de sus datos en UTC, para que los visitantes vean lo actuales que son los precios. La lista completa de funciones por plan está en la página de precios.

Rendimiento y desplazamientos del diseño

Un widget añade muy poco peso a una página:

• Script no bloqueante. El cargador se carga con async y se sirve con una caché de navegador de una hora, así que los visitantes que vuelven normalmente no lo descargan de nuevo.
• Marcos diferidos. El cargador crea el iframe con loading="lazy", así que un widget situado muy abajo en la página solo se descarga cuando el visitante se acerca a él.
• Aislamiento. El widget se ejecuta dentro de su propio marco. Tus hojas de estilo no pueden romperlo y su código no puede tocar tu página.
• La caché de página es segura. El fragmento nunca cambia y los precios se cargan dentro del marco. Los plugins de caché de WordPress, la CDN de Shopify o cualquier otra caché de página completa pueden conservar tu HTML todo el tiempo que quieran sin congelar el precio.

Lo único que hay que prever es el desplazamiento del diseño (layout shift). El marco empieza con 120 píxeles y luego crece hasta la altura real del widget, lo que puede empujar hacia abajo el contenido que tiene debajo. Reserva el espacio de antemano con una altura mínima en el contenedor, usando la altura que ves en la vista previa del editor:

<div id="metalapi-widget-w_abc123" style="min-height:240px"></div>
<script src="https://metalapi.com/js/widget.js" data-widget="w_abc123" async></script>

Una cinta de cotizaciones necesita mucho menos espacio que una tabla de ocho metales, así que usa un valor para cada widget en lugar de uno común para todo el sitio.

Cuándo usar la API en su lugar

Un widget es un componente terminado. Usa la API cuando necesites algo que un widget no hace:

• Precios en tu propio HTML. El texto de un iframe pertenece a otro documento, así que es posible que los buscadores no lo traten como parte de tu página. Si el precio debe formar parte del contenido de tu página, genéralo en el servidor.
• Tu propio diseño. Los widgets ofrecen cuatro diseños, un tema y un color de acento. Para cualquier cosa más allá, escribe tu propio marcado.
• Cálculos. Los precios de productos basados en el peso y la pureza, los presupuestos de recompra y las conversiones pertenecen a tu servidor. El tutorial de la calculadora de precios de joyería muestra uno paso a paso.
• Datos en tu aplicación. Los gráficos, el historial y los precios almacenados necesitan los endpoints historical y timeframe que se describen en la documentación de la API.

Llama a la API desde tu servidor y guarda cada respuesta en caché durante el intervalo de actualización de tu plan. En WordPress, un shortcode con una caché de transients hace ambas cosas en pocas líneas:

<?php
// En wp-config.php: define('METALAPI_KEY', 'mk_live_...');
add_shortcode('gold_price', function ($atts) {
    $a = shortcode_atts(['currency' => 'USD', 'unit' => 'troy_oz'], $atts);
    $currency = strtoupper(preg_replace('/[^A-Za-z]/', '', $a['currency']));
    $unit = sanitize_key($a['unit']);
    $cache_key = "metalapi_xau_{$currency}_{$unit}";

    $data = get_transient($cache_key);
    if ($data === false) {
        $url = add_query_arg(
            ['base' => $currency, 'currencies' => 'XAU', 'unit' => $unit],
            'https://metalapi.com/api/v1/latest'
        );
        $res = wp_remote_get($url, ['headers' => ['X-API-Key' => METALAPI_KEY], 'timeout' => 10]);
        if (is_wp_error($res)) return '';
        $data = json_decode(wp_remote_retrieve_body($res), true);
        if (empty($data['success'])) return '';
        set_transient($cache_key, $data, 10 * MINUTE_IN_SECONDS); // el intervalo de actualización de tu plan
    }

    $price = $data['rates'][$currency . 'XAU'] ?? null;
    if ($price === null) return '';
    return sprintf(
        '<span class="gold-price">%s %s / %s</span>',
        esc_html(number_format_i18n($price, 2)),
        esc_html($currency),
        esc_html(str_replace('_', ' ', $unit))
    );
});

Úsalo en cualquier entrada o página como [gold_price currency="EUR" unit="gram"]. La clave de la respuesta es la divisa base seguida del símbolo, así que rates.EURXAU es el precio de un gramo de oro en euros. Cada fallo de caché cuesta una solicitud, así que un transient de 10 minutos usa como máximo unas 4500 solicitudes al mes por cada combinación de divisa y unidad que muestres, lo que cabe en el plan Standard.

Si tienes que llamar a la API desde el navegador, restringe primero la clave a tus propios dominios, como se describe en la guía de autenticación. Aun así, para mostrar un precio sin más, el widget sigue siendo la opción más sencilla: sin clave, sin caché que gestionar y nada que mantener cuando cambies los símbolos más adelante.