Paraşüt API ile Dövizli Fatura, Döviz Kuru ve Dövizli Tahsilat

Para birimi kodları: TRL, USD, EUR, GBP

Paraşüt API para birimi için yalnızca dört değer kabul eder: TRL, USD, EUR ve GBP. Bu enum satış faturası, alış faturası, teklif, banka gideri, maaş, kasa/banka hesabı ve çek gibi kaynaklarda aynıdır.

// Dış sistemden gelen kodu Paraşüt enum'una çevir
const PARASUT_CURRENCIES = ['TRL', 'USD', 'EUR', 'GBP'] as const;
type ParasutCurrency = typeof PARASUT_CURRENCIES[number];

export function toParasutCurrency(code: string): ParasutCurrency {
  const c = code.trim().toUpperCase();
  const mapped = c === 'TRY' ? 'TRL' : c;
  if (!(PARASUT_CURRENCIES as readonly string[]).includes(mapped)) {
    throw new Error(`Paraşüt bu para birimini desteklemiyor: ${code}`);
  }
  return mapped as ParasutCurrency;
}

Bu dört kodun dışında bir para biriminde satış yapıyorsanız (ör. pazaryerinden gelen başka bir döviz), kaydı Paraşüt'e hangi para birimiyle aktaracağınızı mali müşavirinizle belirlemeniz gerekir; API başka kod kabul etmez. WooCommerce tarafındaki para birimi ayarları için WooCommerce Türkiye ayarları yazısına bakabilirsiniz.

exchange_rate alanı nerede, ne işe yarar?

Dövizli bir belgede currency ile birlikte exchange_rate (döviz kuru) gönderebilirsiniz. Paraşüt'ün fatura rehberi bu alanı "TRL dışı dövizler için kur" olarak tanımlar. Alanın bulunduğu başlıca gövdeler:

Belge, dövizli bir faturada exchange_rate gönderilmezse hangi kurun kullanılacağını açıklamaz. Bu yüzden dövizli belgelerde kuru kendiniz belirleyip açıkça göndermeniz, sonucu öngörülebilir kılar. Hangi kuru (alış veya satış, hangi tarih) kullanacağınız ise bir muhasebe kararıdır.

Teklifte ayrıca display_exchange_rate_in_pdf alanı vardır; kurun teklif PDF'inde gösterilip gösterilmeyeceğini belirler. Teklif akışının tamamı teklif ve proforma yazısında.

USD satış faturası örneği

curl -X POST "https://api.parasut.com/v4/$COMPANY_ID/sales_invoices" \
  -H "Authorization: Bearer $PARASUT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "sales_invoices",
      "attributes": {
        "item_type": "invoice",
        "issue_date": "2026-11-03",
        "due_date": "2026-12-03",
        "currency": "USD",
        "exchange_rate": 41.25
      },
      "relationships": {
        "contact": { "data": { "type": "contacts", "id": "CONTACT_ID" } },
        "details": { "data": [ {
          "type": "sales_invoice_details",
          "attributes": { "quantity": 1, "unit_price": 1000, "vat_rate": 20 },
          "relationships": { "product": { "data": { "type": "products", "id": "PRODUCT_ID" } } }
        } ] }
      }
    }
  }'

Örnekteki 41.25 yalnızca yer tutucudur; gerçek değeri aşağıdaki exchange_rates ucundan alın. item_type seçimi (ör. invoice ya da export), vat_rate değeri ve faturanın e-Fatura mı e-Arşiv mi olacağı vergi mevzuatına bağlıdır; bunlar API belgesinin konusu değildir. Faturanın genel yapısı için fatura kesme yazısına, resmileştirme için e-Fatura ve e-Arşiv yazısına bakın.

exchange_rates: TCMB kurunu API'den çekmek

GET /{company_id}/exchange_rates verilen tarih için USD, EUR ve GBP kurlarını döner. Tarih filter[date] parametresiyle YYYY-MM-DD biçiminde verilir; verilmezse bugün kullanılır. Her para birimi için istenen tarihe eşit ya da ondan önceki en son TCMB kuru gelir.

curl "https://api.parasut.com/v4/$COMPANY_ID/exchange_rates?filter[date]=2026-11-03" \
  -H "Authorization: Bearer $PARASUT_TOKEN" -H "Accept: application/json"

• Yanıt sayfalanmaz ve meta içermez.
• Henüz kur kaydı yoksa id boş ve kurlar 0 gelir; bu durumda kuru faturaya yazmayın.
• Geçersiz tarih biçiminde gövdesiz 400, 2000 yılından önceki tarihlerde 404 döner.
• TRL için kayıt dönmez; enum yalnızca USD, EUR ve GBP içerir.
• date alanı istenen tarihten önce olabilir (ör. hafta sonu). Hangi kurun kullanıldığını loglamak için bu alanı saklayın.

type Rate = { attributes: { date: string; currency: 'USD' | 'EUR' | 'GBP'; buying_rate: string; selling_rate: string } };

export async function getRate(token: string, date: string, currency: 'USD' | 'EUR' | 'GBP') {
  const url = `https://api.parasut.com/v4/${process.env.PARASUT_COMPANY_ID}/exchange_rates?filter[date]=${date}`;
  const res = await fetch(url, { headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' } });
  if (!res.ok) throw new Error(`exchange_rates ${res.status}`);
  const body = (await res.json()) as { data: Rate[] };
  const row = body.data.find((r) => r.attributes.currency === currency);
  const selling = Number(row?.attributes.selling_rate);   // string gelir, sayıya çevir
  if (!row || !Number.isFinite(selling) || selling === 0) throw new Error('Kur henüz yok');
  return { rate: selling, rateDate: row.attributes.date };
}

Dövizli tahsilat ve ödeme

Fatura tahsilatı (POST /sales_invoices/{id}/payments) ve alış faturası ödemesi (POST /purchase_bills/{id}/payments) aynı PaymentFormAttributes gövdesini kullanır. Döviz açısından iki alan önemlidir:

Yani tahsilatın para birimini gövdede ayrı bir alanla değil, seçtiğiniz kasa veya banka hesabıyla belirlersiniz. Hesapların para birimi accounts kaydındaki currency alanındadır ve hesap listesi filter[currency] ile süzülebilir. Örneğin USD faturayı USD hesabına tahsil ediyorsanız exchange_rate göndermeyebilirsiniz; farklı bir kurla tahsil ediyorsanız kurun TL karşılığını yazarsınız. Bu tanımı kendi senaryolarınızda staging hesabında doğrulayın.

{
  "data": {
    "type": "payments",
    "attributes": {
      "account_id": 789,
      "date": "2026-12-03",
      "amount": 1200,
      "description": "SWIFT tahsilatı"
    }
  }
}

Çalışana ödeme ucunda (employee_debit_transactions) kural daha açıktır: TL dışı hesaplarda exchange_rate ya da target_amount zorunludur, aksi hâlde 422 "Döviz kuru doldurulmalı" döner. Kasa veya banka hesapları arasında farklı para birimiyle transfer için POST /accounts/money_transfers uç noktası source_amount (kaynak hesabın para biriminde) ve target_amount (hedef hesabın para biriminde) alanlarını ister; aynı para birimindeki hesaplarda iki tutar eşit olmalıdır. Tahsilat ve ödemenin genel akışı tahsilat ve ödeme kaydı yazısında.

TL karşılıkları ve dövizli bakiyeler

API dövizli kayıtlarda TL karşılıklarını hazır hesaplanmış alanlarla döner. Bunlar salt okunurdur; göndermeyin, yalnızca okuyun:

• Satış ve alış faturasında remaining_in_trl; her iki listede de sort=remaining_in_trl kullanılabilir.
• Teklif listesinde sıralama için net_total_in_trl.
• Caride ve çalışanda para birimi bazında trl_balance, usd_balance, eur_balance, gbp_balance.
• İşlem (transactions) kaydında amount_in_trl, debit_currency ve credit_currency.
• Üründe list_price_in_trl ve buying_price_in_trl; satış ve alış dövizi currency ve buying_currency alanlarındadır.

Ürün ve stok tarafı için ürün, stok ve depo yönetimi yazısına, cari bakiyeleri için cari hesap yazısına bakabilirsiniz.

Sık yapılan hatalar

Hata yanıtlarını errors[].source.pointer ile ayırt etmek ve 422 ile 429'u doğru ele almak için hata kodları ve rate limit yazısına bakın.

Kısaca çek ve senet kaydı

Paraşüt'te çek ve senetler aynı kaynakta tutulur: /{company_id}/checks. Oluşturma gövdesinde net_total (0'dan büyük), currency, issue_date ve due_date zorunludur; description, serial_number, bank_identifier ve yalnızca bank_identifier: OTHER ile birlikte bank_name isteğe bağlıdır.

• Alınan çek için issued_by, verilen çek için given_to ilişkisinden tam olarak biri gönderilir (ikisi birden ya da hiçbiri 400 döner).
• İsteğe bağlı payable ilişkisi çeki bir satış faturasına (sales_invoices) ya da fişe (purchase_bills) öncelikli eşleştirir.
• Alınan çeki tedarikçiye ciro etmek için PATCH /checks/{id}/transfer kullanılır; date ve given_to zorunludur.
• Çeki tahsil etmek veya ödemek için POST /checks/{id}/payments yalnızca date ve account_id alır. Hesabın para birimi çekin para birimiyle aynı olmalı ve hesapta banka entegrasyonu olmamalıdır.
• Liste filter[currency], filter[item_type] ve operatörlü tarih filtrelerini (filter[due_date][lteq]=2026-11-30 gibi) destekler; page[size] en fazla 10000'dir.

{
  "data": {
    "type": "checks",
    "attributes": {
      "net_total": 5000,
      "currency": "USD",
      "issue_date": "2026-11-03",
      "due_date": "2027-01-15",
      "bank_identifier": "OTHER",
      "bank_name": "Örnek Bank",
      "serial_number": "123456"
    },
    "relationships": {
      "issued_by": { "data": { "type": "contacts", "id": "CONTACT_ID" } },
      "payable": { "data": { "type": "sales_invoices", "id": "INVOICE_ID" } }
    }
  }
}

Belgeye göre çek oluşturulduğunda remaining_in_trl o günkü kurla hesaplanır. Dövizli bir çeki tahsil ederken çekle aynı para biriminde bir hesap seçmeniz gerektiğini unutmayın.

Sık Sorulan Sorular

Paraşüt API TRY kabul ediyor mu?

Hayır. Türk lirası için TRL kullanılır; enum değerleri TRL, USD, EUR ve GBP'dir.

exchange_rates ucu hangi kuru döner?

USD, EUR ve GBP için TCMB kurunu döner: istenen tarihe eşit ya da ondan önceki en son kur. Hem buying_rate hem selling_rate string olarak gelir; hangisini kullanacağınız muhasebe tercihinizdir.

Dövizli faturaya TL hesabından tahsilat girebilir miyim?

Tahsilatın hangi para birimiyle yapılacağını account_id ile seçtiğiniz hesap belirler. Faturadan farklı bir kurla tahsilatta exchange_rate alanına kurun TL karşılığı yazılır. Senaryonuzu canlıya almadan önce staging hesabında deneyin.

exchange_rate göndermezsem ne olur?

Belge bu durumda hangi kurun uygulanacağını açıklamaz. Öngörülebilir sonuç için dövizli belgelerde kuru kendiniz belirleyip gönderin.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Paraşüt entegrasyonu genel rehberi · Paraşüt API ile fatura kesme · Paraşüt API tahsilat ve ödeme · Paraşüt API alış faturası ve gider kaydı · E-ticaret siparişini Paraşüt'e aktarma · Pazaryeri entegrasyonu rehberi