Paraşüt API ile Tahsilat ve Ödeme Kaydı: Faturaya Tahsilat Ekleme ve Geri Alma

Tahsilatta Rol Alan Kaynaklar

Önemli ilişki şudur: bir faturaya tahsilat eklediğinizde bir payment kaydı oluşur ve bu kayıt faturayı kapatan bir transaction'a bağlıdır. Tahsilatı geri alırken silinecek olan bu işlemdir, ödeme kaydı değil.

1. Adım: Kasa veya Banka Hesabını Bulun

Tahsilat isteğindeki account_id, paranın gireceği kasa veya banka hesabının kimliğidir. Hesapları GET /{company_id}/accounts ile listeleyin. Belgelenen filtreler filter[name], filter[currency], filter[bank_name], filter[bank_branch], filter[account_type] ve filter[iban]'dır.

curl -g "https://api.parasut.com/v4/{company_id}/accounts?filter[currency]=TRL&filter[account_type]=bank" \
  -H "Authorization: Bearer $PARASUT_TOKEN"

Ödeme sağlayıcınızdan (sanal POS, ödeme kuruluşu) gelen paralar için Paraşüt'te ayrı bir banka hesabı açmak mutabakatı kolaylaştırır. Hesap oluşturma POST /accounts ile yapılır:

{
  "data": {
    "type": "accounts",
    "attributes": {
      "name": "Sanal POS Tahsilatları",
      "currency": "TRL",
      "account_type": "bank",
      "bank_name": "Örnek Bank"
    }
  }
}

Hesap kimliğini bir kez bulup yapılandırmanızda saklayın; her tahsilatta listeleme yapmaya gerek yoktur.

2. Adım: Satış Faturasına Tahsilat Ekleyin

Tahsilat POST /{company_id}/sales_invoices/{id}/payments ile eklenir. data.type değeri payments'tır ve gövdede ilişki yoktur; hesap bilgisi account_id özniteliğiyle verilir.

curl -X POST "https://api.parasut.com/v4/{company_id}/sales_invoices/789/payments?include=transaction" \
  -H "Authorization: Bearer $PARASUT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "payments",
      "attributes": {
        "description": "Sipariş #10452 kredi kartı tahsilatı",
        "account_id": 123,
        "date": "2026-11-03",
        "amount": 1800
      }
    }
  }'

Dikkat edilecek ayrıntı: account_id bir öznitelik olduğu için JSON sayısı (integer) olarak gönderilir. İlişkilerdeki id değerlerinin string olması kuralı burada geçerli değildir, çünkü bu alan bir ilişki değildir.

Başarılı istek 201 döner ve yanıt bir payments kaydıdır. ?include=transaction eklerseniz oluşan işlemin kimliği de gelir; bu kimliği kendi siparişinizin yanına kaydedin, tahsilatı geri almanız gerekirse doğrudan kullanırsınız.

Kısmi Tahsilat ve Faturanın Ödeme Durumu

Bir faturaya birden fazla tahsilat ekleyebilirsiniz; örneğin peşinat ve kalan bakiye ya da taksitli havale. Faturadaki kalan tutarı ve durumu okumak için faturayı tekrar çekin. İlgili alanlar salt okunurdur ve fatura güncellerken gönderilmez:

Liste ucunda filtre değerleri öznitelik değerlerinden farklıdır: GET /sales_invoices için filter[payment_status] yalnızca overdue, not_due, unscheduled ve paid değerlerini kabul eder. Vadesi geçmiş faturaları bulmak için filter[payment_status]=overdue, kalan tutara göre sıralamak için sort=-remaining kullanabilirsiniz.

curl -g "https://api.parasut.com/v4/{company_id}/sales_invoices/789?include=payments,payments.transaction" \
  -H "Authorization: Bearer $PARASUT_TOKEN"

Faturaya bağlı tahsilatları ayrıca GET /sales_invoices/{id}/payments ile de listeleyebilirsiniz. Bu uçta sayfa boyutu 10000'e kadar çıkabilir ve include=transaction,transaction.debit_account gibi değerler desteklenir.

Dövizli Faturada Tahsilat

Paraşüt para birimleri için TRL, USD, EUR ve GBP kodlarını kullanır; TRY geçerli değildir. Tahsilatta para birimi alanı yoktur: tahsilatın hangi para biriminde yapıldığını seçtiğiniz hesabın (account_id) para birimi belirler.

• Tahsilat faturayla aynı döviz kuruyla yapılıyorsa exchange_rate göndermeyin ya da 1.0 gönderin.
• Tahsilat faturadan farklı bir döviz kuruyla yapılıyorsa (ör. USD fatura TL hesaba tahsil ediliyorsa) belgeye göre döviz kurunun TL karşılığını exchange_rate alanında belirtin.

Kur kaynağı ve dövizli fatura ayrıntıları için Paraşüt API döviz kuru ve dövizli fatura yazısına bakın. Kur farkının muhasebe yorumu için mali müşavirinize danışın.

Tahsilatı Geri Alma: DELETE /transactions/{id}

Yanlış tutar girildiğinde ya da ödeme iade edildiğinde tahsilatı geri almanız gerekir. Paraşüt'ün açık kuralı şudur: fatura tahsilatını DELETE /payments/{id} ile silmeye çalışmayın; doğru yol tahsilatın işlemini DELETE /{company_id}/transactions/{transaction_id} ile silmektir. Başarıda 204 döner.

• Önce işlemi bulun: GET /sales_invoices/{id}/payments?include=transaction ya da GET /sales_invoices/{id}?include=payments.transaction.
• Ödeme kaydının relationships.transaction.data.id değeri silinecek işlemin kimliğidir.
• DELETE /transactions/{id} çağırın, ardından faturayı tekrar okuyup remaining ve payment_status değerlerini kontrol edin.

DELETE /payments/{id} ucu yalnızca contact_debit (cariden faturasız tahsilat), employee_debit ve check_out (verilen çek) işlemlerine bağlı ödemeleri siler. Diğer ödemelerde 401 döner. Bu 401 bir oturum sorunu değildir; token yenileyip tekrar denemek işe yaramaz.

// parasut.ts: tüm örneklerde kullanılan küçük istemci
const BASE = `https://api.parasut.com/v4/${process.env.PARASUT_COMPANY_ID}`;

export async function parasut(method: string, path: string, body?: unknown) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.PARASUT_TOKEN}`,
      'Content-Type': 'application/vnd.api+json',
      Accept: 'application/json',
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  if (res.status === 204 || res.status === 304) return null; // gövdesiz yanıtlar
  const json = await res.json();
  if (!res.ok) {
    // Hata metnine değil, durum koduna ve errors[].source.pointer alanına bakın
    throw Object.assign(new Error(`Paraşüt HTTP ${res.status}`), { status: res.status, errors: json.errors });
  }
  return json;
}

import { parasut } from './parasut';

// Faturadaki belirli bir tahsilatı geri alır
export async function tahsilatiGeriAl(faturaId: number, odemeId: string) {
  const sonuc = await parasut('GET', `/sales_invoices/${faturaId}/payments?include=transaction`);
  const odeme = sonuc.data.find((p: any) => p.id === odemeId);
  const islemId = odeme?.relationships?.transaction?.data?.id;
  if (!islemId) throw new Error('Tahsilatın işlemi bulunamadı');

  await parasut('DELETE', `/transactions/${islemId}`); // 204, gövdesiz

  const fatura = await parasut('GET', `/sales_invoices/${faturaId}`);
  return {
    kalan: fatura.data.attributes.remaining,
    durum: fatura.data.attributes.payment_status,
  };
}

Faturasız Tahsilat: Cariden Tahsilat

Bazen para faturadan önce gelir (avans) ya da müşteri birden fazla faturayı tek havaleyle öder. Bu durumda cari bazında tahsilat kullanılır: POST /{company_id}/contacts/{id}/contact_debit_transactions. Burada data.type değeri transactions'tır ve gövde fatura tahsilatıyla aynı alanlara ek olarak payable_ids alır.

{
  "data": {
    "type": "transactions",
    "attributes": {
      "description": "Ekim ayı toplu havale",
      "account_id": 123,
      "date": "2026-11-03",
      "amount": 5400,
      "payable_ids": [789, 790]
    }
  }
}

payable_ids, tahsilatın öncelikli olarak eşleşmesini istediğiniz satış faturası kimlikleridir. Tedarikçiye faturasız ödeme için eşi olan contact_credit_transactions ucu vardır; orada payable_ids alış faturası kimliklerini alır. Cari kaydının kendisi için cari hesap oluşturma yazısına bakın.

Müşterinin alacak bakiyesini açık bir faturayla eşleştirmek için POST /sales_invoices/{id}/match ucu da vardır. Eşleşecek kayıt yoksa gövdesiz 304 döner; bu bir hata değildir.

Peşin Satış Faturası

Satış faturası şemasında payment_account_id, payment_date ve payment_description alanları bulunur. Bunlar yalnızca peşin satış faturalarında ödeme oluşturmak veya güncellemek içindir. Normal faturada bu alanları göndermeyin; tahsilatı yukarıdaki payments ucuyla ayrı bir istekte ekleyin.

Kasa ve Banka Hesabında Diğer İşlemler

• POST /accounts/{id}/debit_transactions ve credit_transactions: hesaba doğrudan para girişi ve çıkışı. data.type transactions, zorunlu alanlar date ve amount, isteğe bağlı description. Para birimi alanı yoktur.
• POST /accounts/money_transfers: iki hesap arası transfer. source_account_id, target_account_id, source_amount, target_amount ve date zorunludur; aynı para birimindeki hesaplarda iki tutar eşit olmalıdır.
• POST /accounts/{id}/adjust_balance: hesabın bakiyesini bir tarihte belirli tutara sabitler. Geri almak için oluşan balance_adjustment işlemini DELETE /transactions/{id} ile silin. Banka entegrasyonu olan hesaplarda kullanılamaz.
• GET /accounts/{account_id}/transaction_history_items: hesabın yürüyen bakiyeli ekstresi. Yalnızca hesabın kendi para birimindeki bakiye dolu gelir.

Bir işlemin ayrıntısını GET /transactions/{id}?include=debit_account,credit_account,payments ile okuyabilirsiniz. İşlem kaydında transaction_type, date, debit_amount, credit_amount, debit_currency, credit_currency ve amount_in_trl alanları bulunur.

Mükerrer Tahsilatı Önlemek

Satış faturası oluşturmada external_reference_key ile idempotans sağlanabilir, ancak tahsilat ucunda belgelenmiş bir idempotans anahtarı yoktur. Zaman aşımı ya da 5xx sonrasında isteği körü körüne tekrarlarsanız aynı ödeme iki kez işlenebilir. Güvenli bir akış:

• Tahsilatı göndermeden önce kendi veritabanınızda "gönderiliyor" durumunda bir kayıt açın.
• Başarılı yanıtta dönen ödeme ve işlem kimliklerini bu kayda yazın.
• Belirsiz sonuçta (zaman aşımı, 500, 503) tekrar denemeden önce GET /sales_invoices/{id}/payments ile aynı tarih ve tutarda bir tahsilatın oluşup oluşmadığını kontrol edin.
• 403 (yetki veya paket sorunu) ve 422 (doğrulama hatası) yanıtlarını tekrar denemeyin; nedenini errors[].source.pointer üzerinden kullanıcıya gösterin.

Webhook tarafında tahsilat için ayrı bir model yoktur; sales_invoice update event'i de yalnızca e-Fatura veya e-Arşiv belgesi olan faturalar için gönderilir. Paraşüt arayüzünde elle girilen tahsilatları yakalamak için faturaları periyodik olarak okumanız gerekir. Hata yönetimi ayrıntıları için hata kodları ve rate limit, webhook kapsamı için Paraşüt webhook kurulumu yazısına bakın.

Sık Sorulan Sorular

Tahsilatı silmek için hangi ucu kullanmalıyım?

Fatura tahsilatlarında DELETE /{company_id}/transactions/{id}. İşlem kimliğini ödeme kaydının transaction ilişkisinden alırsınız. DELETE /payments/{id} yalnızca contact_debit, employee_debit ve check_out işlemlerine bağlı ödemelerde çalışır, diğerlerinde 401 döner.

payment_status alanını kendim paid yapabilir miyim?

Hayır. payment_status, remaining ve remaining_in_trl salt okunurdur. Durum, eklenen tahsilatlara göre Paraşüt tarafından hesaplanır.

Alış faturasına ödeme nasıl eklenir?

Aynı gövdeyle POST /{company_id}/purchase_bills/{id}/payments ucuna. Ayrıntılar alış faturası ve gider kaydı yazısında.

Kredi kartı komisyonunu nasıl kaydederim?

Paraşüt'te banka giderleri için ayrı bir bank_fees kaynağı vardır. Komisyonun muhasebe kaydının nasıl yapılacağını mali müşavirinizle netleştirin; API tarafında tahsilatı brüt ya da net tutarla kaydetme kararı sizin muhasebe politikanıza bağlıdır.

Pazaryeri hak edişlerini nasıl eşleştiririm?

Toplu gelen hak edişlerde cari bazında tahsilat (contact_debit_transactions) ve payable_ids ile ilgili faturaları önceliklendirmek pratik bir yöntemdir. Genel kurgu için pazaryeri entegrasyonu rehberine ve e-ticaret siparişini Paraşüt'e aktarma yazısına bakabilirsiniz.

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 · Cari hesap ve müşteri oluşturma · Döviz kuru ve dövizli fatura · Alış faturası ve gider kaydı · Hata kodları ve rate limit · API rate limiting stratejileri