DEV Community

Cover image for Plaid API Kullanımı (2026 Geliştirici Rehberi)
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Plaid API Kullanımı (2026 Geliştirici Rehberi)

Fintech uygulamaları artık nadiren sıfırdan başlar. Bir kullanıcı uygulamanıza bir vadesiz hesap bağladığında, büyük ihtimalle Plaid aracı olarak banka girişlerini arka ucunuzun kullanabileceği temiz JSON'a çevirir. Plaid API'si, Venmo, Robinhood ve Chime dahil binlerce uygulama için hesap bağlama, bakiye kontrolü, işlem geçmişi ve kimlik doğrulama sağlar.

Bugün Apidog'u deneyin

Bu kılavuz size Plaid API'sini bir geliştirici bakış açısından anlatır: anahtarları nasıl alacağınızı, Link token akışının baştan sona nasıl çalıştığını, bilmeniz gereken ürünleri ve üretimde işler ters gittiğinde yaygın hataların ne anlama geldiğini gösterir. Ayrıca, istek yüklerini tahmin etmeyi bırakmanız için her adımı Apidog ile nasıl test edeceğinizi de göreceksiniz. Ham doğruluk kaynağını istiyorsanız, okurken resmi Plaid belgelerini ikinci bir sekmede açık tutun.

Açık bankacılık kalabalık bir alandır ve Plaid birçok seçenekten biridir. Hala satıcıları karşılaştırıyorsanız, en iyi açık bankacılık API'leri hakkındaki özetimiz faydalı bir yardımcı olacaktır. Bu yazı için, Plaid'i seçtiğinizi ve yayınlamaya hazır olduğunuzu varsayın.

TL;DR (Çok Uzun; Okumadım)

  • Plaid, uygulamanızı ABD, Kanada ve Avrupa'daki 12.000'den fazla bankaya bağlayan bir finansal veri toplayıcısıdır.
  • Kutudan çıkar çıkmaz üç ortam elde edersiniz: sandbox (ücretsiz, sahte veriler), geliştirme (100 ücretsiz canlı Öğeler) ve üretim (çağrı başına ödeme).
  • Bağlama akışı dört adımlı bir el sıkışmadır: sunucu tarafında link_token oluşturma, istemci tarafında Plaid Link'i açma, public_token'ı access_token ile değiştirme ve ardından ürün uç noktalarını çağırma.
  • Çekirdek ürünler Kimlik Doğrulama (Auth), Bakiye (Balance), İşlemler (Transactions), Kimlik (Identity), Yatırımlar (Investments), Yükümlülükler (Liabilities) ve Gelir (Income)'dir. Bunları Öğe (Item) başına etkinleştirirsiniz.
  • En yaygın üretim hataları ITEM_LOGIN_REQUIRED ve INVALID_CREDENTIALS'tır. Webhook'lar bir Öğenin dikkat gerektirdiğini size bildirir.
  • Oran sınırları Öğe (Item) başına ve istemci başınadır. Okumalarınızı gruplandırın ve yoklama yapmak yerine webhook'ları dinleyin.

Plaid Nedir?

Plaid, uygulamanız ile kullanıcının bankası arasında yer alan ABD merkezli bir fintech altyapı şirketidir. Bir kullanıcı banka kimlik bilgilerini Plaid Link'e girdiğinde, Plaid bankaya bağlanır (mümkün olan yerlerde resmi açık bankacılık API'leri aracılığıyla veya mümkün olmayan yerlerde tersine mühendislikle tasarlanmış banka web siteleri aracılığıyla), istenen verileri çeker, normalleştirir ve hangi bankadan geldiğine bakılmaksızın size tutarlı bir JSON yanıtı sunar.

Kullanıcının banka kimlik bilgilerini asla görmez veya saklamazsınız. Plaid, Öğe (Item) olarak adlandırdığı bağlantıyı tutar ve size bu Öğeyi sorgulama iznini temsil eden bir access_token verir. Bir Öğe, bir finans kurumundaki bir kimlik bilgisi kümesine eşittir ve birden fazla hesap (vadesiz, tasarruf, kredi kartı) içerebilir.

Plaid, tüketici vadesiz ve tasarruf hesaplarını, kredi kartlarını, kredileri, yatırım hesaplarını ve bordro verilerini kapsar. Kendi başına para transferi yapmaz; ACH transferleri için genellikle Plaid Auth'u ayrı bir ödeme işlemcisiyle eşleştirirsiniz. En iyi ACH ödeme API'leri hakkındaki yazımız, bu eşleşmenin genellikle nasıl göründüğünü açıklar.

Kimlik Doğrulama ve Kurulum

Adım 1: Bir Plaid geliştirici hesabı oluşturun

plaid.com adresinden kaydolun ve e-postanızı doğrulayın. Plaid Kontrol Paneli'ne, halihazırda sağlanmış üç ortamla birlikte yönlendirileceksiniz:

  • Sandbox: sahte kurumlar, sahte kullanıcılar, ücretsiz. Giriş yapmak için user_good / pass_good kullanın.
  • Geliştirme (Development): gerçek banka bağlantıları, 100 canlı Öğeyle sınırlı, ücretsiz.
  • Üretim (Production): gerçek bağlantılar, sınırsız, kullanıma göre faturalandırma.

Adım 2: Anahtarlarınızı Alın

Kontrol Paneli'nden Ekip Ayarları (Team Settings) > Anahtarlar (Keys) bölümüne gidin. İki değere ihtiyacınız var:

  • client_id: tüm ortamlarda aynı
  • secret: ortama göre farklı (sandbox, geliştirme, üretim)

Bunları ortam değişkenlerinde saklayın. Kesinlikle git'e işlemeyin.

Adım 3: SDK'yı Yükleyin

Resmi Node.js SDK'sı github.com/plaid/plaid-node adresinde bulunur.

npm install plaid

Adım 4: İstemciyi Başlatın

import { Configuration, PlaidApi, PlaidEnvironments } from 'plaid';

const config = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});

const client = new PlaidApi(config);

Ortam değiştirirken PlaidEnvironments.sandbox'ı .development veya .production ile güncelleyin.

Temel Uç Noktalar

Her Plaid entegrasyonunda şu dört adımı uygulayın:

Adım 1: Sunucu tarafında link_token oluşturun

const response = await client.linkTokenCreate({
  user: { client_user_id: 'user_123' },
  client_name: 'Your App',
  products: ['auth', 'transactions'],
  country_codes: ['US'],
  language: 'en',
});

const linkToken = response.data.link_token;

Curl alternatifi:

curl -X POST https://sandbox.plaid.com/link/token/create \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "secret": "YOUR_SANDBOX_SECRET",
    "user": { "client_user_id": "user_123" },
    "client_name": "Your App",
    "products": ["auth", "transactions"],
    "country_codes": ["US"],
    "language": "en"
  }'

Adım 2: Plaid Link'i istemcide açın

link_token'ı ön uca aktarın ve Plaid Link SDK'sına iletin. Kullanıcı bankasını seçer, giriş yapar ve Plaid, onSuccess callback'ine bir public_token döndürür.

Adım 3: public_token'ı access_token ile değiştirin

const exchange = await client.itemPublicTokenExchange({
  public_token: publicToken,
});

const accessToken = exchange.data.access_token;
const itemId = exchange.data.item_id;

accessToken'ı sunucu tarafında kullanıcıya bağlı olarak güvenli şekilde saklayın. Bu uzun ömürlüdür ve sonraki API çağrıları için kullanılır.

Adım 4: Ürün uç noktalarını çağırın

const accounts = await client.accountsGet({ access_token: accessToken });
const balance = await client.accountsBalanceGet({ access_token: accessToken });

Bilmeniz Gereken Temel Ürün Uç Noktaları

  • Kimlik Doğrulama (Auth): ACH için hesap ve yönlendirme numaralarını döndürür (/auth/get).
  • Bakiye (Balance): Anlık bakiyeleri döndürür (/accounts/balance/get).
  • İşlemler (Transactions): 24 aya kadar temizlenmiş işlem verileri (/transactions/sync).
  • Kimlik (Identity): Hesap sahibinin bilgileri (/identity/get). Sadece KYC ihtiyacı için en iyi KYC API'leri özetimize bakabilirsiniz.
  • Yatırımlar (Investments): Yatırım portföyü ve işlemleri (/investments/holdings/get).
  • Yükümlülükler (Liabilities): Öğrenci kredisi, kredi kartı, ipotek ayrıntıları (/liabilities/get).
  • Gelir (Income): Bordro verileri (/credit/payroll_income/get).

Plaid API'sini Apidog ile Test Etme

Plaid'i uçtan uca test etmek zordur çünkü Link adımı tarayıcıda gerçekleşir. Ancak, Plaid'in sunucu tarafı uç noktalarına geçerli yüklerle erişmek, hata senaryolarını görmek ve çalışan istekleri ekip içinde paylaşmak için pratik bir yol gereklidir. Apidog bu konuda öne çıkar.

Plaid'in OpenAPI şemasını Apidog'a aktararak, her uç noktayı tiplenmiş, örnek gövdeler ve doğru kimlik doğrulama başlıklarıyla hazır alırsınız. Sandbox ortam değişkenlerinizi (client_id, secret, access_token) tanımlayın ve tek tıklamayla üretime geçin. Zincirleme isteklerle (linkTokenCreate → sandboxPublicTokenCreate → itemPublicTokenExchange → accountsGet) tüm el sıkışma akışını tarayıcı olmadan doğrulayabilirsiniz.

Apidog'un mock sunucusu, arka uç tamamlanmadan önce ön uç ekibinizin /accounts/get yanıtlarını görebilmesini sağlar. Başka bir araçtan geçiş yapacaksanız, 2026'da Postman olmadan API testi rehberimizi inceleyin. Başlamak için Apidog'u indirin ve Plaid şemasına yönlendirin.

Yaygın Hatalar ve Oran Sınırları

Plaid hataları error_type, error_code ve error_message ile döner. Üretimde aşağıdaki dört hata için özel kontrol ekleyin:

  • INVALID_CREDENTIALS: Kullanıcı bankada yanlış parola girdi. Tekrar denemeleri için Link güncelleme moduna yönlendirin.
  • ITEM_LOGIN_REQUIRED: Banka oturumu geçersiz kılındı (parola değişikliği, MFA rotasyonu vb). Yeniden kimlik doğrulama için Link'i güncelleme modunda tetikleyin. Bunu çoğunlukla webhook ile öğrenirsiniz.
  • RATE_LIMIT_EXCEEDED: Oran sınırına ulaşıldı. Geri çekilin ve jitter ile yeniden deneyin.
  • PRODUCT_NOT_READY: Veri henüz hazır değil. INITIAL_UPDATE webhook'u sonrasında tekrar deneyin.

Webhook'lar

link_token oluştururken bir webhook URL'si gönderin. Plaid, güncellemeleri POST olarak bu URL'ye iletir. Dikkat etmeniz gerekenler:

  • SYNC_UPDATES_AVAILABLE: Yeni işlemler geldi.
  • ITEM: LOGIN_REQUIRED: Yeniden kimlik doğrulama gerektirir.
  • ITEM: ERROR: Kalıcı hata.

Her webhook isteğinde JWT imzasını doğrulamadan işlem yapmayın.

Oran Sınırları

Plaid; Öğe (Item) ve uç nokta başına oran sınırı uygular. Örneğin, /accounts/balance/get üretimde Öğe başına dakikada yaklaşık 5 çağrı ile sınırlıdır. Yoğun uç noktalarda, istemci başına toplam sınırlar da olabilir. En iyi uygulama: webhook'ları kullanın, bakiyeleri birkaç dakika önbelleğe alın ve asla kullanıcıya dönük bir istekten direkt Plaid'e çağrı yapmayın.

Plaid Fiyatlandırması

Plaid, üretimde kademeli ve çağrı başına ödeme modeli uygular. Temel olarak:

  • Sandbox: ücretsiz, sınırsız.
  • Geliştirme (Development): 100 Öğeye kadar ücretsiz.
  • Üretim (Production):
  • Kimlik Doğrulama (Auth): Bağlı hesap başına yaklaşık 1,50 USD (tek seferlik).
  • Bakiye (Balance): Çağrı başına fiyatlandırma.
  • İşlemler (Transactions): Öğe başına aylık ücret (~0,30 USD civarı).
  • Kimlik (Identity): Çağrı başı.
  • Yatırımlar/Yükümlülükler/Gelir: Öğe başına ayrı ücretler.

Daha yüksek hacimlerde özel fiyat sunulabiliyor. En güncel bilgiler için Plaid ürünleri sayfasını inceleyin.

Sıkça Sorulan Sorular (SSS)

Bir access_token ne kadar süreyle geçerlidir?

Kullanıcı erişimi iptal edene veya banka oturumu geçersiz kılana kadar sınırsızdır. Şifreli saklayın, kendi tarafınızda süresini bitirmeyin.

Plaid'i sadece kimlik doğrulama için kullanabilir miyim?

Plaid Identity ile mümkündür; ancak asıl amacınız KYC ise, özel bir doğrulama ürünü daha iyi olabilir. Stripe Identity API'si ile ilgili rehberimiz bu karşılaştırmaları içerir.

Plaid ABD dışındaki ülkeleri destekliyor mu?

Evet. ABD, Kanada, Birleşik Krallık ve AB'nin çoğunu kapsar. Ülke desteği ürüne göre değişir; /link/token/create çağrısında country_codes parametresini ayarlayın.

Kullanıcı banka parolasını değiştirirse ne olur?

Öğe ITEM_LOGIN_REQUIRED durumuna geçer ve webhook ile bilgilendirilirsiniz. Plaid Link'i güncelleme modunda başlatın; kullanıcı yeniden doğrulama yapar ve access_token değişmez.

Link akışını gerçek bir tarayıcı olmadan test edebilir miyim?

Evet. /sandbox/public_token/create uç noktası ile Link'i atlayıp test için kullanılabilir bir public_token alırsınız. Otomatik entegrasyon testleri için kullanışlıdır.

Yerel geliştirme ortamında Plaid ile çalışmak için öneriniz?

Bir sandbox secret ile .env dosyanızı yapılandırın, ortamı PlaidEnvironments.sandbox olarak ayarlayın. Webhook almak için ngrok veya Cloudflare Tunnel gibi tünelleme araçlarını kullanın.

Top comments (0)