PHP ile Altın Fiyatı API'si: cURL, Guzzle ve WordPress Kısa Kodu

PHP ile altın fiyatı API'si: temel bilgiler

Bir altın fiyatı API'si, PHP kodunuza güncel altın fiyatını JSON olarak verir: ürün fiyatları, bir temadaki fiyat satırı veya günlük bir rapor için. Bu eğitim cURL ile sade PHP'yi, Guzzle HTTP istemcisini ve WordPress'i kapsıyor; WordPress'te WP-Cron ile yenilenen önbellekli bir [gold_price] kısa kodu, fiyatı herhangi bir yazıya veya sayfaya yerleştirir. Değerli metaller, endüstriyel metaller, enerji, para birimleri ve kripto paralar için bir JSON REST API'si olan MetalAPI'yi kullanıyor.

MetalAPI panelinden bir API anahtarına ihtiyacınız var. Anahtarlar mk_live_ ile başlar; Free plan, kredi kartı gerektirmeden günlük fiyat güncellemeleriyle ayda 100 istek içerir. Anahtarı kodunuzun dışında tutun: sade PHP için bir ortam değişkeninde, WordPress için wp-config.php dosyasında.

Her endpoint, https://metalapi.com/api/v1 altında bir GET isteğidir. Anahtar erişim loglarının dışında kalsın diye onu api_key sorgu parametresi yerine X-API-Key header'ında (veya Authorization: Bearer olarak) gönderin. Dokümantasyondaki örnek değerlerle bir /latest yanıtı:

{
  "success": true,
  "timestamp": 1792834892,
  "date": "2026-10-24",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319,
    "USDXAU": 3997.89,
    "EUR": 0.8925,
    "USDEUR": 1.1204
  },
  "rate_limit": { "...": "..." }
}

rates.USDXAU, bir troy ons altının dolar cinsinden fiyatıdır; rates.XAU ise bunun tersidir, yani dolar başına ons miktarıdır; bu nedenle onu asla fiyat olarak göstermeyin. rates.USDEUR, bir euronun dolar cinsinden fiyatıdır ve WordPress eklentisi dönüştürme için bunu kullanır. timestamp, fiyat verisinin Unix saniyesi cinsinden zamanıdır.

PHP'de cURL ile altın fiyatı nasıl alınır

cURL uzantısı neredeyse her PHP kurulumuyla birlikte gelir. Bu fonksiyon anahtarı bir header'da gönderir, zaman aşımlarını ayarlar ve ağ hatalarıyla API hatalarını istisnalara dönüştürür:

<?php
// curl uzantılı PHP 8+. Çalıştırma: METALAPI_KEY=mk_live_... php gold.php
function metalapi(string $path, array $params = []): array
{
    $ch = curl_init('https://metalapi.com/api/v1/' . $path . '?' . http_build_query($params));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT        => 10,
        CURLOPT_HTTPHEADER     => ['X-API-Key: ' . getenv('METALAPI_KEY')],
    ]);
    $body = curl_exec($ch);
    if ($body === false) {
        throw new RuntimeException('Network error: ' . curl_error($ch));
    }
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    $data = json_decode($body, true);
    if (empty($data['success'])) {
        $code = $data['error']['code'] ?? $status;
        $info = $data['error']['info'] ?? "HTTP $status";
        throw new RuntimeException("MetalAPI $code: $info", $code);
    }
    return $data;
}

$data = metalapi('latest', ['base' => 'USD', 'currencies' => 'XAU']);
printf("Gold: %.2f USD per troy oz\n", $data['rates']['USDXAU']);
printf("Time: %s UTC\n", gmdate('Y-m-d H:i', $data['timestamp']));

Örnek değerlerle Gold: 3997.89 USD per troy oz çıktısını verir. İstisna kodu, MetalAPI'nin hata kodudur: 104 hatasını (dakika başına limit) Retry-After saniye sonra, 500 veya 503 hatalarını ise geri çekilmeyle yeniden deneyin; ancak 102 (geçersiz anahtar), 105 (aylık kota tükendi) veya 106 (endpoint planınızda yok) gibi kodlarda nedeni düzeltin. Hata yönetimi rehberi tüm kodları listeler.

cURL yerine Guzzle kullanmak

Bir Composer projesinde Guzzle aynı işi daha az satırla yapar. base_uri sonundaki eğik çizgiyi koruyun ve latest gibi göreli yollar isteyin; çünkü Guzzle /latest yolunu alan adının köküne göre çözümler. Ayrıca http_errors seçeneğini kapatın; böylece hata yanıtları istisna fırlatmak yerine MetalAPI'nin JSON gövdesini döndürür:

<?php
// composer require guzzlehttp/guzzle
require __DIR__ . '/vendor/autoload.php';

$client = new GuzzleHttp\Client([
    'base_uri'    => 'https://metalapi.com/api/v1/',
    'timeout'     => 10,
    'http_errors' => false,
    'headers'     => ['X-API-Key' => (string) getenv('METALAPI_KEY')],
]);

$res  = $client->get('latest', ['query' => ['base' => 'EUR', 'currencies' => 'XAU', 'unit' => 'gram']]);
$data = json_decode((string) $res->getBody(), true);

if (empty($data['success'])) {
    $code = $data['error']['code'] ?? $res->getStatusCode();
    throw new RuntimeException("MetalAPI $code: " . ($data['error']['info'] ?? $res->getReasonPhrase()), $code);
}
printf("Gold: %.2f EUR per gram\n", $data['rates']['EURXAU']);

Zaman aşımları ve diğer ağ hataları yine de bir ConnectException fırlatır; bu nedenle bir hatanın sayfayı bozmaması gereken yerlerde onu yakalayın.

WordPress'te altın fiyatı: önbellekli bir [gold_price] kısa kodu

WordPress içinde bunun yerine yerleşik HTTP API'deki wp_remote_get() fonksiyonunu kullanın. İki tasarım kuralı kısa kodu hızlı ve ucuz tutar:

• Sayfa oluşturulurken API'yi çağırmayın. Eklenti fiyatları, WP-Cron'un arka planda yenilediği bir transient'te tutar. Ziyaretçiler yalnızca transient bulunmadığında, örneğin etkinleştirmenin hemen ardından bir istek tetikler.
• Tüm para birimlerini tek bir çağrıda isteyin. Baz USD ve currencies=XAU,EUR,GBP ile yanıt, altının ve her para biriminin dolar fiyatını aynı anlık görüntüden içerir; dolayısıyla euro cinsinden altın USDXAU ÷ USDEUR olur, gram fiyatları da troy ons başına 31,1034768 gramdan hesaplanır. Yenileme başına tek bir istek her para birimini ve birimi kapsar.

Transient'ler süreleri dolmadan kaybolabilir, örneğin kalıcı bir nesne önbelleği onları çıkardığında; bu nedenle eklenti son geçerli fiyatları ayrıca bir option'da saklar. Bir yenileme başarısız olursa hatayı loglar ve bu kopyayı beş dakika boyunca sunar. Önce anahtarı wp-config.php dosyasına, düzenlemeyi bırakmanızı söyleyen satırın üstüne ekleyin:

define( 'METALAPI_KEY', 'mk_live_your_key_here' );

Ardından eklentiyi wp-content/plugins/metalapi-gold-price/metalapi-gold-price.php olarak kaydedin ve Eklentiler (Plugins) bölümünden etkinleştirin:

<?php
/**
 * Plugin Name:  MetalAPI Gold Price
 * Description:  [gold_price] kısa kodu; bir transient'te önbelleğe alınır ve WP-Cron ile yenilenir.
 * Requires PHP: 8.0
 */
defined( 'ABSPATH' ) || exit;

const MGP_INTERVAL   = 600;              // saniye. Standard: 600, Lite: 3600, Free: 86400
const MGP_CURRENCIES = [ 'EUR', 'GBP' ]; // USD dışında, kısa kodlarınızın kullandığı her para birimi
const MGP_GRAMS      = [ 'troy_oz' => 31.1034768, 'gram' => 1, 'kilogram' => 1000 ];

function mgp_refresh(): ?array {
    if ( ! defined( 'METALAPI_KEY' ) ) {
        return null;
    }
    $url  = add_query_arg(
        [ 'base' => 'USD', 'currencies' => implode( ',', [ 'XAU', ...MGP_CURRENCIES ] ) ],
        'https://metalapi.com/api/v1/latest'
    );
    $res  = wp_remote_get( $url, [ 'timeout' => 8, 'headers' => [ 'X-API-Key' => METALAPI_KEY ] ] );
    $data = is_wp_error( $res ) ? null : json_decode( wp_remote_retrieve_body( $res ), true );

    if ( empty( $data['success'] ) ) {
        error_log( 'MetalAPI refresh failed: ' . ( is_wp_error( $res ) ? $res->get_error_message() : wp_remote_retrieve_body( $res ) ) );
        $last = get_option( 'mgp_prices_last' );
        if ( $last ) {
            set_transient( 'mgp_prices', $last, 5 * MINUTE_IN_SECONDS ); // bekle, son geçerli fiyatları koru
        }
        return $last ?: null;
    }

    $per_oz = [ 'USD' => $data['rates']['USDXAU'] ];
    foreach ( MGP_CURRENCIES as $cur ) {
        if ( ! empty( $data['rates'][ "USD$cur" ] ) ) {
            $per_oz[ $cur ] = $data['rates']['USDXAU'] / $data['rates'][ "USD$cur" ];
        }
    }
    $prices = [ 'per_oz' => $per_oz, 'time' => $data['timestamp'] ];
    set_transient( 'mgp_prices', $prices, 2 * MGP_INTERVAL ); // bir cron çalışmasının gecikmesini tolere eder
    update_option( 'mgp_prices_last', $prices, false );       // transient silinirse yedek
    return $prices;
}

function mgp_prices(): ?array {
    return get_transient( 'mgp_prices' ) ?: mgp_refresh();
}

add_shortcode( 'gold_price', function ( $atts ): string {
    $a    = shortcode_atts( [ 'currency' => 'USD', 'unit' => 'troy_oz', 'decimals' => 2 ], $atts, 'gold_price' );
    $cur  = strtoupper( $a['currency'] );
    $unit = strtolower( $a['unit'] );
    $p    = mgp_prices();
    if ( ! $p || ! isset( $p['per_oz'][ $cur ] ) || ! array_key_exists( $unit, MGP_GRAMS ) ) {
        return '';
    }
    $price = $p['per_oz'][ $cur ] / MGP_GRAMS['troy_oz'] * MGP_GRAMS[ $unit ];
    return sprintf(
        '<span class="gold-price">%s %s / %s</span> <small>%s</small>',
        esc_html( number_format_i18n( $price, absint( $a['decimals'] ) ) ),
        esc_html( $cur ),
        esc_html( str_replace( '_', ' ', $unit ) ),
        esc_html( wp_date( get_option( 'date_format' ) . ' ' . get_option( 'time_format' ), $p['time'] ) )
    );
} );

// WP-Cron: her aralıkta bir kez arka planda yenile.
add_filter( 'cron_schedules', function ( array $schedules ): array {
    $schedules['mgp_interval'] = [ 'interval' => MGP_INTERVAL, 'display' => 'MetalAPI refresh' ];
    return $schedules;
} );
add_action( 'mgp_refresh_event', 'mgp_refresh' );

register_activation_hook( __FILE__, function (): void {
    if ( ! wp_next_scheduled( 'mgp_refresh_event' ) ) {
        wp_schedule_event( time(), 'mgp_interval', 'mgp_refresh_event' );
    }
} );
register_deactivation_hook( __FILE__, function (): void {
    wp_clear_scheduled_hook( 'mgp_refresh_event' );
} );

Kısa kodu herhangi bir yazıda, sayfada veya Kısa kod (Shortcode) bloğunda [gold_price] ya da [gold_price currency="EUR" unit="gram"] olarak kullanın. Örnek kurlarla ikincisi 114,72 EUR / gram gösterir: 3.997,89 ÷ 1,1204 troy ons başına 3.568,27 euro eder; bunu 31,1034768'e bölmek gram fiyatını verir. MGP_CURRENCIES listesinde olmayan bir para birimi hiçbir şey yazdırmaz; bu nedenle kısa kodlarınızın kullandığı her para birimini listeye ekleyin.

WP-Cron ile altın fiyatlarını yenilemek

Etkinleştirme kancası (activation hook), yenilemeyi cron_schedules üzerinden kaydedilen özel aralıkla zamanlar; devre dışı bırakma ise onu kaldırır. MGP_INTERVAL değerini planınızın güncelleme aralığına ya da kota gerektiriyorsa daha uzun bir süreye ayarlayın:

WP-Cron gerçek bir zamanlayıcı değildir: zamanı gelen olayları biri siteyi ziyaret ettiğinde çalıştırır; bu nedenle ziyaretçisi az bir sitede yenileme gecikebilir. Transient'in iki katı ömrü ve saklanan kopya bunu telafi eder. Kesin zamanlama için wp-config.php dosyasına define( 'DISABLE_WP_CRON', true ); satırını ekleyin ve zamanı gelen olayları sistem cron'undan WP-CLI ile çalıştırın:

*/10 * * * * cd /var/www/html && wp cron event run --due-now > /dev/null 2>&1

Sayfa önbelleğini de hesaba katın: tam sayfa önbelleği, kısa kodun çıktısını sayfayla birlikte saklar; bu nedenle ziyaretçiler fiyatı sayfanın önbelleğe alındığı andaki haliyle görür. Fiyat içeren sayfaların önbellek ömrünü yenileme aralığınıza eşit veya daha kısa tutun.

Kodsuz bir widget ne zaman daha iyi bir seçimdir

Fiyatın HTML'inizin bir parçası olması gerektiğinde veya PHP'nin sayıya ihtiyaç duyduğunda (örneğin ürünleri yeniden fiyatlandırmak için) doğru araç kısa koddur. Yalnızca fiyat göstermek istiyorsanız bir MetalAPI widget'ı daha basittir:

• API anahtarı ve PHP gerekmez. Widget'ı panelde oluşturur ve gömme kodunu bir Özel HTML (Custom HTML) bloğuna yapıştırırsınız. Sembollerde veya düzende sonradan yapılan değişiklikler sitenizde düzenleme gerektirmez.
• Kota harcamaz. Widget sayfa görüntülemeleri aylık isteklerinizi kullanmaz ve her plan widget içerir: Free planda 1, Lite'ta 3, Standard'da 10.
• Sayfa önbelleğiyle sorunsuz çalışır. Fiyatlar bir iframe içinde yüklenir; bu nedenle önbelleğe alınmış bir sayfa onları asla dondurmaz.

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

Barındırma sağlayıcınız <script> etiketlerini temizliyorsa gömme kodunun iframe sürümünü kullanın. Web sitenize canlı altın fiyatı widget'ı nasıl eklenir yazısı oluşturucuyu, WordPress'e yerleştirmeyi ve plan limitlerini ele alır; widget sayfası ise düzenleri gösterir.

Sonraki adımlar

Ücretsiz bir hesap oluşturun, anahtarınızı wp-config.php dosyasına ekleyin ve eklentiyi MGP_INTERVAL değeri 86400 olacak şekilde kurun: günlük yenileme, Free planın aylık 100 isteğinden 31'ini kullanır. Daha güncel fiyatlara ihtiyaç duyduğunuzda aralığı yeni planınızın güncelleme aralığına ayarlayın ve planları fiyatlandırma sayfasında karşılaştırın. Node.js backend'leri için JavaScript ile altın fiyatı API'si aynı kalıpları Express ve Next.js ile gösterir.

Sık sorulan sorular

WordPress'te API anahtarını nerede saklamalıyım?

wp-config.php dosyasında bir sabit olarak veya orada okunan bir ortam değişkeninde. Sıklıkla Git'e giren tema dosyalarında ya da her ziyaretçinin okuyabildiği JavaScript'te asla saklamayın. PHP istekleri Origin veya Referer header'ı göndermez; bu nedenle alan adıyla sınırlandırılmış bir anahtar bile sunucudan çalışır.

Kısa kod neden bütün hafta sonu aynı altın fiyatını gösteriyor?

Spot altın New York saatiyle cuma 17:00'den pazar 17:00'ye kadar işlem görmez; bu nedenle API, piyasalar yeniden açılana kadar son fiyatı döndürür. Free planda ise fiyatlar zaten günde yalnızca bir kez değişir.

Eklenti kaç API isteği kullanır?

Kaç ziyaretçiniz, sayfanız veya kısa kodunuz olursa olsun yenileme başına bir istek; çünkü tek bir çağrı her para birimini döndürür ve birimler yerel olarak dönüştürülür: 10 dakikalık aralıkla ayda yaklaşık 4.500 istek.

Altın fiyatını WooCommerce ürün fiyatlarında kullanabilir miyim?

Evet. mgp_prices() fonksiyonunu PHP'den, örneğin bir woocommerce_product_get_price filtresinde çağırın ve gram fiyatını ürünün ağırlığı ve saflığıyla çarpın. Faturaların sonradan değişmemesi için her siparişte kullanılan altın fiyatını saklayın.

WordPress'te cURL veya Guzzle'a ihtiyacım var mı?

Hayır. wp_remote_get(), kullanılabilir bir aktarım yöntemi seçen ve proxy ayarlarına uyan WordPress HTTP API'sini kullanır. cURL'ü veya Guzzle'ı sade PHP ve Laravel ya da Symfony gibi framework'ler için kullanın.