Döviz kuru API'si ile çoklu para birimiyle faturalama nasıl kurulur (2026 Kılavuzu)

Çoklu para birimiyle faturalama çözülmüş bir sorun gibi görünür: bir para birimi seç, bir döviz kuruyla çarp, toplamı yazdır. Uygulamada ise herhangi bir faturalama sisteminin en hataya açık alanlarından biridir ve hatalar pahalıya patlar; çünkü alacaklarınızda, vergi beyanlarınızda ve müşterilerinizin gelen kutularında ortaya çıkar. Bir SaaS ürününe, serbest çalışan aracına, ajans platformuna veya B2B pazar yerine çoklu para birimiyle faturalama entegre eden bir geliştiriciyseniz, zor olan kısım çarpma değildir. Zor olan, hangi döviz kurunu kullanacağınıza, onu ne zaman kilitleyeceğinize ve mart ayında kestiğiniz bir faturanın temmuzda ödendiğinde hâlâ doğru şekilde mutabık kalması için nasıl saklayacağınıza karar vermektir.

Bu kılavuz, kurları getirmek, kilitlemek ve saklamak için bir döviz kuru API'si kullanan çalıştırılabilir kodla birlikte önemli olan mühendislik kararlarını adım adım ele alır. Odak özellikle döviz (FX) katmanındadır — çoğu faturalama eğitiminin atladığı kısım.

Çoklu para birimiyle faturalama neden basit para dönüşümünden fazlasıdır

Tek para birimli bir fatura bir anlık görüntüdür: miktar çarpı fiyat, artı vergi. Çoklu para birimli bir fatura ise belirli bir ana ilişkin bir sözleşmedir. Defterlerinizi USD ile tutarken bir müşteriye EUR ile fatura kestiğinizde, USD değeri kestiğiniz gün sabitlenen bir alacağı kaydediyorsunuzdur — müşteri gerçekten ödeyene kadar piyasa kuru hareket etmeye devam etse bile.

Bu boşluk, basit dönüşümün göz ardı ettiği üç somut sorun yaratır:

1. Hangi kur geçerli. Fatura tarihindeki kur mu, ödeme tarihindeki mi, yoksa "bugünkü" mü? Neredeyse hiçbir zaman aynı olmazlar ve muhasebe standartları (hem GAAP hem IFRS) yanıt konusunda nettir.
2. Denetlenebilirlik. Aylar sonra, tam olarak hangi kuru kullandığınızı ve nereden geldiğini kanıtlayabilmeniz gerekir. Sayıyı yeniden üretemiyorsanız "bir API'den aldık" yeterli değildir.
3. Kur kâr ve zararı. Fatura tarihindeki değer ile ödeme tarihindeki değer arasındaki fark, defter-i kebirinizde bir yere kaydedilmesi gereken gerçek bir kâr veya zarardır.

Bunu doğru yaparsanız çoklu para birimiyle faturalama en iyi anlamda sıkıcı hâle gelir. Yanlış yaparsanız finans ekibiniz her çeyreğin son haftasını kuruş peşinde koşarak geçirir.

Altın kural: döviz kurunu fatura tarihinde kilitleyin

Çoklu para birimiyle faturalamanın en önemli kuralı şudur: döviz kurunu fatura kesildiği anda dondurun ve asla yeniden hesaplamayın.

Hem GAAP hem IFRS, yabancı para cinsinden bir işlemi işlem tarihinde geçerli olan spot kurla kaydetmenizi gerektirir. Bir fatura için işlem tarihi, kesim tarihidir. Bir müşteriye 1 Temmuz'da fatura keser ama sisteminiz onu ancak 5 Temmuz'da işlerse, yine de 1 Temmuz kurunu kullanırsınız. Bu bir Finexly kuralı ya da tercih değildir — alacağın işlevsel (yerel) para biriminizdeki değerinin yasal olarak belirlenme biçimidir.

Yaygın bir anti-desen, müşteri faturayı her yenilediğinde değişen "canlı" bir dönüştürülmüş toplam göstermektir. Bunu asla yapmayın. Fatura, belirli bir tutara ilişkin sabit bir taleptir. Müşteri tutarı fatura para biriminde borçludur ve defterleriniz kilitli kurdan bir kayıt borçludur. Piyasa sonrasında ne isterse yapabilir.

Pratik sonuç: faturalama için para dönüşümü bir kez yazma işlemidir. Kuru bir kez getirir, faturayla birlikte saklar ve o belgenin ömrü boyunca değişmez olarak ele alırsınız.

Faturalama için bir döviz kuru API'si seçmek

Her FX veri kaynağı faturalamaya uygun değildir. Faturalama için şunları istersiniz:

• Fatura kestiğiniz her para biriminin kapsanması (Finexly 170'ten fazla para birimini kapsar).
• Hangi kotasyonu kullandığınızı kanıtlayabilmeniz için her kurun üzerinde güvenilir bir "geçerlilik tarihi" zaman damgası.
• Tarihe göre geçmiş kurlar, çünkü geriye dönük ve düzeltilmiş faturalar kaçınılmazdır.
• Fatura hacmindeki bir sıçramanın faturalamayı bozmaması için öngörülebilir istek limitleri ve fiyatlar. Ödeme yolunuza bir bağımlılık kurmadan önce fiyat planlarını inceleyin.

Temel bir güncel kur isteği şöyle görünür:

curl "https://api.finexly.com/v1/latest?base=USD&symbols=EUR&access_key=YOUR_API_KEY"

Ve yanıt size bir kur ile yanına saklayacağınız zaman damgasını verir:

{
  "success": true,
  "base": "USD",
  "timestamp": 1753660800,
  "rates": {
    "EUR": 0.9213
  }
}

Herhangi bir şeyi bağlamadan önce kurları etkileşimli olarak keşfetmek isterseniz, döviz çevirici hızlı bir kontroldür. Finexly'nin diğer sağlayıcılarla nasıl karşılaştırıldığına daha geniş bir bakış için döviz API'lerini karşılaştırın.

Fatura kurunu getirmek ve kilitlemek

İşte bir faturanın kurunu getiren ve kalıcılaştırmanız gereken her şeyi döndüren küçük bir Python yardımcısı: kur, kaynak zaman damgası ve dönüştürülmüş toplam. Yalnızca bir sayı değil, kuru ve meta verileri döndürdüğüne dikkat edin.

import os
import time
import requests
from decimal import Decimal, ROUND_HALF_UP

API_KEY = os.environ["FINEXLY_API_KEY"]
BASE_URL = "https://api.finexly.com/v1/latest"

def lock_invoice_rate(home_currency, invoice_currency):
    """Fetch and lock the FX rate to convert an invoice total
    (in invoice_currency) back into home_currency for the books."""
    resp = requests.get(BASE_URL, params={
        "base": invoice_currency,
        "symbols": home_currency,
        "access_key": API_KEY,
    }, timeout=10)
    resp.raise_for_status()
    data = resp.json()
    if not data.get("success"):
        raise RuntimeError("Rate lookup failed")

    rate = Decimal(str(data["rates"][home_currency]))
    return {
        "rate": rate,                       # invoice_currency -> home_currency
        "rate_base": invoice_currency,
        "rate_quote": home_currency,
        "source": "finexly",
        "as_of": data["timestamp"],         # store the source timestamp
        "locked_at": int(time.time()),      # when WE locked it
    }

def home_value(amount_invoice_ccy, rate):
    """Convert an invoice-currency amount into home currency."""
    return (Decimal(str(amount_invoice_ccy)) * rate).quantize(
        Decimal("0.01"), rounding=ROUND_HALF_UP
    )

Kritik ayrıntı, lock_invoice_rate'in fatura oluşturulurken bir kez çalışması ve çıktısının fatura kaydına yazılmasıdır. Önbellekleme, yeniden deneme ve 429 yanıtlarını zarifçe ele alma gibi üretim konuları için önbellekleme ve hata işleme kılavuzumuzdaki desenleri izleyin — geçici bir API aksaklığının fatura kesmeyi engellemesini istemezsiniz.

Döviz kurunu faturayla birlikte saklamak

Kur her fatura için değişmez olduğundan, onu üzerine yazabileceğiniz paylaşılan bir "güncel kur" tablosunda değil, fatura üzerinde saklayın. Asgari bir şema şöyle görünür:

CREATE TABLE invoices (
  id              BIGSERIAL PRIMARY KEY,
  issue_date      DATE        NOT NULL,
  invoice_ccy     CHAR(3)     NOT NULL,   -- what the customer is billed in
  home_ccy        CHAR(3)     NOT NULL,   -- your functional currency
  total_invoice   NUMERIC(18,2) NOT NULL, -- total in invoice_ccy
  fx_rate         NUMERIC(18,8) NOT NULL, -- invoice_ccy -> home_ccy, LOCKED
  fx_source       TEXT        NOT NULL,   -- e.g. 'finexly'
  fx_as_of        TIMESTAMPTZ NOT NULL,   -- the rate's source timestamp
  total_home      NUMERIC(18,2) NOT NULL  -- total_invoice * fx_rate, at issue
);

Bu şemayı denetime uygun kılan üç şey vardır. Birincisi, fx_rate sekiz ondalık basamak kullanır — döviz kurları bir para tutarının iki ondalığından çok daha fazla hassasiyete ihtiyaç duyar ve erken kesme, yuvarlama kayması getirir. İkincisi, fx_as_of sayının nereden ve ne zaman geldiğini kaydeder, böylece herhangi bir denetçi onu geçmiş verilere karşı yeniden üretebilir. Üçüncüsü, total_home kesim anında hesaplanır ve saklanır, böylece altı ay sonra çalıştırılan bir rapor hiçbir zaman tahmin yürütmek zorunda kalmaz.

Müşteriye şeffaflık için kilitli kuru faturanın kendisine yazdırın: ödenecek tutar, para birimi, kullanılan kur ve uygulandığı tarih. Bu, tam da ödeme farklı bir kurla geldiğinde belirsizliği ortadan kaldırdığı için yaygın olarak önerilen bir en iyi uygulamadır.

Geriye dönük faturalar: bugünün değil, geçmiş kurları kullanın

Er ya da geç geçmiş tarihli bir fatura keseceksiniz — bir düzeltme, geç bir kayıt veya daha erken bir yürürlük tarihi belirten bir sözleşme. Mart faturası için bugünün kurunu kullanmak düpedüz yanlıştır ve bir denetimden geçemez. Bunun yerine, faturanın gerçek tarihine ait kuru bir geçmiş uç noktasından getirin:

def lock_historical_rate(home_currency, invoice_currency, invoice_date):
    """invoice_date as 'YYYY-MM-DD'. Returns the locked rate for a
    backdated or corrected invoice."""
    resp = requests.get("https://api.finexly.com/v1/historical", params={
        "date": invoice_date,
        "base": invoice_currency,
        "symbols": home_currency,
        "access_key": API_KEY,
    }, timeout=10)
    resp.raise_for_status()
    data = resp.json()
    rate = Decimal(str(data["rates"][home_currency]))
    return {"rate": rate, "as_of": invoice_date, "source": "finexly"}

Kural canlı durumla aynıdır — bir kez kilitle, sonsuza dek sakla — ama sorguladığınız tarih faturanın kesim tarihidir, güncel gün değil. Tarihli kurlarla çalışmanın daha derin bir işlenişi için geçmiş döviz kuru API'si kılavuzuna bakın.

Yuvarlama ve hassasiyet, doğru şekilde

Parayla ilgili hatalar neredeyse her zaman yuvarlama hatalarıdır. İki kural sizi beladan uzak tutar.

Para için asla kayan nokta kullanmayın. Kayan nokta aritmetiğinde 0.1 + 0.2, 0.3 değildir ve bu küçücük hatalar fatura satırları boyunca birikir. Bir ondalık tür kullanın: Python'da Decimal, Java'da BigDecimal, C#'ta decimal veya JavaScript'te tamsayı-kuruş gösterimi.

Yuvarlamanın nerede olacağına karar verin. Kuru tam hassasiyete (8+ ondalık) yuvarlayın, ancak tutarları para biriminin alt birimine yuvarlayın — USD veya EUR için iki ondalık, JPY veya KRW için sıfır ondalık, bazıları için üç. Sık yapılan bir hata, iki ondalığı sabit kodlayıp ¥1,234.56 tutarında bir fatura kesmektir; bu geçerli bir yen tutarı değildir. Ondalık sayısını, ISO 4217 alt birim verilerini kullanarak para biriminden türetin.

Satır kalemli faturalar için her satırı yuvarlayıp sonra toplamayı tercih edin ve yazdırılan satırların yazdırılan toplamı vermesi için yuvarlanmış toplamla mutabık kalın. Hangi kuralı seçerseniz seçin, onu faturalama, ödemeler ve raporlama genelinde tutarlı biçimde uygulayın.

Ödeme anında kur kâr ve zararını tanımak

İşte kilitli kurun karşılığını verdiği yer burasıdır. Müşteri ödediğinde, banka hesabınıza gerçekte ulaşanı ödeme tarihi kuruyla yerel para biriminize geri çevirirsiniz. Bununla fatura tarihindeki yerel değer arasındaki fark, gerçekleşmiş bir kur kâr veya zararıdır.

// Amounts kept as Decimal-like strings; use a money library in production.
function realizedFxGainLoss(invoice, paymentRate) {
  // invoice.totalInvoice: amount billed, in the invoice currency
  // invoice.fxRate:       LOCKED rate at issue (invoice_ccy -> home_ccy)
  // paymentRate:          rate on the day the payment settled

  const homeAtIssue   = invoice.totalInvoice * invoice.fxRate;
  const homeAtPayment = invoice.totalInvoice * paymentRate;

  const gainLoss = homeAtPayment - homeAtIssue;
  return {
    homeAtIssue:   round2(homeAtIssue),
    homeAtPayment: round2(homeAtPayment),
    fxGainLoss:    round2(gainLoss),        // > 0 gain, < 0 loss
  };
}

function round2(n) { return Math.round(n * 100) / 100; }

paymentRate'i fatura kurunu kilitlediğiniz yöntemin aynısıyla getirirsiniz — takas tarihinde bir latest çağrısı ya da sonradan mutabakat yapıyorsanız bir historical çağrısı. fxGainLoss'u ayrılmış bir "kur kâr/zarar" hesabına kaydedin. Piyasa kesim ile ödeme arasında hareket ettiğinde defterlerinizi dengede tutan tek kayıt budur ve manuel çoklu para birimi faturalamanın yanlış yaptığı mutabakat işi tam olarak budur. Bunu otomatik hatlara kuran işletmeler, çoklu para birimli SaaS faturalama kılavuzumuzda anlatılan aynı kur altyapısına yaslanabilir.

Alacak dekontları, geri ödemeler ve yinelenen faturalar

Üç sınır durumu eksiksiz bir sistemi tamamlar:

• Alacak dekontları ve geri ödemeler, orijinal faturayı orijinal kilitli kuruyla tersine çevirmelidir — güncel kurla değil. Bir geri ödeme, ilk işlemin geri sarılmasıdır, bu yüzden alacaklandırdığınız faturanın fx_rate değerini yeniden kullanın. Gerçek geri ödeme tarihindeki kalıntı fark, bir başka küçük kur kâr/zarar kaydı olur.
• Yinelenen faturaların her biri, kendi kesim tarihinde kendi kilitli kurunu alır. Aylık faturalanan 12 aylık bir abonelik, on iki kurlu on iki fatura üretir. Sözleşme açıkça sabitlemedikçe yıl için tek bir kur kilitlemeyin.
• Sözleşmeyle sabitlenen kurlar zaman zaman piyasayı geçersiz kılar — bazı kurumsal sözleşmeler bir dönem için sabit bir kur belirtir. Manuel bir geçersiz kılma alanını destekleyin, ancak yeniden üretilebilir kalması için onu aynı denetim meta verileriyle saklayın.

Sıkça sorulan sorular

Bir faturada hangi döviz kurunu kullanmalıyım? Faturanın kesim tarihinde geçerli olan spot kuru kullanın, sonra kilitleyin. Hem GAAP hem IFRS, yabancı para işlemlerinin işlem tarihi kuruyla kaydedilmesini gerektirir ve fatura tarihi o tarihtir. Müşteri faturayı görüntülediğinde veya ödediğinde yeniden hesaplamayın.

Döviz kurunu mu yoksa yalnızca dönüştürülmüş tutarı mı saklamalıyım? İkisini de saklayın — ayrıca kurun kaynağını ve zaman damgasını. Yalnızca dönüştürülmüş toplamı saklamak, sonradan denetlemeyi veya kur kâr/zararını doğru hesaplamayı imkânsız kılar. Kur, "geçerlilik tarihi" zaman damgası ve kaynak birlikte, herkesin sayıyı yeniden üretmesini sağlar.

Geçmiş tarihli bir faturayı nasıl ele alırım? Bugünün kurunu kullanmak yerine gerçek kesim tarihi için bir geçmiş döviz kuru sorgulayın. Bir kez kilitle, sonsuza dek sakla kuralı aynıdır; yalnızca aradığınız tarih değişir.

Bir faturada kur kâr veya zararına ne yol açar? Fatura tarihi ile ödeme tarihi arasında piyasanın hareket etmesi. Defterleriniz alacağı fatura tarihi kuruyla kaydetti, ancak nakit ödeme tarihi kuruyla değerlenmiş olarak gelir. Fark, gerçekleşmiş bir kur kâr veya zararıdır ve ayrılmış bir defter-i kebir hesabına kaydedilir.

Çoklu para birimiyle faturalama kurmak için ücretli bir döviz API'sine ihtiyacım var mı? Ücretsiz bir katmanda başlayabilirsiniz. Finexly'nin ücretsiz döviz kuru API'si erken aşama hacimleri için canlı ve geçmiş kurları kapsar ve yalnızca fatura hacminiz büyüdükçe yükseltirsiniz.

Başlayın

Çoklu para birimiyle faturalama tek bir disipline indirgenir: kuru fatura tarihinde kilitleyin, onu eksiksiz denetim meta verileriyle saklayın ve farkı ödemede mutabık kılın. Bunu yapın, uluslararası faturalama çeyrek sonu yangın söndürme telaşı olmaktan çıksın.

Kurmaya hazır mısınız? Ücretsiz Finexly API anahtarınızı alın — kredi kartı gerekmez. Ücretsiz planda 170'ten fazla para birimi için canlı ve geçmiş kurlarla başlayın ve fatura hacminiz büyüdükçe ölçeklenin.