Nordlet

← Belgeler / Kılavuzlar

Banka ve ödeme içe aktarımları

camt.053 ekstreleri, Stripe CSV, PSP mutabakat uzlaştırması ve özel JSON akışları.

Tüm içe aktarımlar bir banka hesabına (bank/accounts/create) banka hareketi olarak düşer. Hareketler bir externalId taşır; aynı dosyanın yeniden içe aktarılması güvenlidir. (bankAccountId, externalId) ikilisi halihazırda mevcut olan satırlar atlanır ve skipped (atlanan) sayacında raporlanır. İçe aktarılan hareketler new (yeni) statüsünde başlar ve yalnızca eşleştirildiklerinde (bank/transactions/match, adaylar için bank/transactions/suggest-matches ile) defteri kekime (ledger) işlenir.

Web uygulaması aynı içe aktarımları Banka → Dosya içe aktar (dosya yükleme, şablon seçici) altında sunar.

Yanlış bir eşleştirme bank/transactions/unmatch (Banka → Hareketler bölümündeki Eşleştirmeyi kaldır seçeneği) ile geri alınır. İşlenmiş (posted) kayıtlar asla düzenlenmez veya silinmez: bir faturayla eşleştirilmiş ödeme veya bir içe aktarım şablonunun bir hesaba işlediği bir satır, her kalemi ters yönlü olan, date tarihli (varsayılan: bugün ve asıl kayıttan asla önceki bir tarih olmamak üzere) ters bir yevmiye işlemine (journal transaction) tabi tutulur. Faturanın ödenen tutarı ve ödeme durumu, ilgili banka satırının tutarı kadar geri alınır. Bir ödeme sağlayıcısı mutabakatına bağlı bir satır yalnızca ilişiğinden koparılır, çünkü mutabakat kaydı toplu işe (batch) aittir. Satır new statüsüne geri döner ve yeniden eşleştirilebilir. Ters kayıt tarihi açık bir muhasebe dönemi içinde yer almalıdır.

İçe aktarım şablonları

Bir içe aktarım şablonu bir veri kaynağını adlandırır, kaynağın sağladığı alanları listeler ve para taşıyan alanları defteri kebir hesaplarıyla eşleştirir. Şablonlar Banka → İçe aktarım şablonları üzerinden ve bank/import-templates/create|update|delete|get|list aracılığıyla yönetilir.

POST /v1/bank/import-templates/create
{
  "name": "Stripe payments export",
  "type": "stripe",
  "fields": [
    { "name": "id" },
    { "name": "Created date (UTC)" },
    { "name": "Amount" },
    { "name": "Fee", "accountCode": "6800" },
    { "name": "Amount Refunded" }
  ],
  "metaFields": ["order_id"]
}
  • type değeri stripe, iso20022, bank_connection veya revolut değerlerinden biridir.
  • Her alanın bir name (ad) ve isteğe bağlı bir accountCode (hesap kodu) vardır. Yalnızca para taşıyan alanlar hesap kabul eder: Stripe Amount, Fee ve Amount Refunded; camt.053 Ntry/Amt; banka akışı transaction_amount.amount. Hesabın hesap planında (chart of accounts) mevcut olması gerekir (ledger/accounts/create ile oluşturun).
  • fields alanı atlanabilir; bu durumda türün standart alan listesine varsayılan olarak döner: Stripe Ödemeler → Dışa Aktar dosyasının sütun adları (formun varsayılan olarak işaretlenmemiş bıraktığı 19 adet Card … sütunu hariç), her ekstrenin taşıdığı camt.053 öğeleri (Stmt/Id, Stmt/Acct/Id/IBAN, Stmt/Bal/…, Ntry/Amt, Ntry/CdtDbtInd, Ntry/Sts, Ntry/BookgDt) veya PSD2 banka akışının işlem başına döndürdüğü öznitelikler. Dosyanızla eşleşmesi için girdi ekleyin veya çıkarın: içe aktarıcı ayrıca isteğe bağlı camt.053 öğeleri olan Ntry/ValDt, Ntry/NtryRef, Ntry/AcctSvcrRef, Ntry/AddtlNtryInf, TxDtls/Refs/EndToEndId, TxDtls/Refs/TxId, TxDtls/RltdPties/Dbtr/Nm, TxDtls/RltdPties/DbtrAcct/Id/IBAN, TxDtls/RltdPties/Cdtr/Nm, TxDtls/RltdPties/CdtrAcct/Id/IBAN, TxDtls/RmtInf/Ustrd ve TxDtls/AddtlTxInf alanlarını da okur.
  • Bir Stripe Customer Email alanı "createPartner": true değerini taşıyabilir. Bu durumda içe aktarım, mevcut hiçbir iş ortağının (partner) sahip olmadığı, dosyadaki her e-posta için bir müşteri (kişi türünde iş ortağı, müşteri olarak işaretlenmiş) oluşturur; isim olarak Customer Description (boş olduğunda e-posta) ve dosya içeriyorsa adres olarak Card Address … sütunlarını kullanır. Mevcut iş ortakları büyük/küçük harf duyarsız olarak e-posta adresine göre eşleştirilir. Yanıt, customersCreated alanında bu sayıyı bildirir.
  • metaFields (yalnızca Stripe) tahsilatlarınızın taşıdığı meta veri anahtarlarını listeler. Stripe her anahtarı bir <key> (metadata) sütunu olarak dışa aktarır; liste serbest biçimlidir ve uzun olabilir.
  • invoiceItemId (yalnızca Stripe, isteğe bağlı) bir katalog kalemi (catalog item) belirtir. Ayarlandığında, içe aktarımın oluşturduğu her fatura ve alacak dekontu satırı o kalemi referans alır (bunun muhasebe kaydını ve invoiceVatRatePercent boş olduğunda KDV oranını); satır metni yine de tahsilattan gelir.
  • companyMetaField (yalnızca Stripe) bu anahtarlardan birini şirket bayrağı olarak adlandırır. Bir tahsilat bu sütunda true, 1, yes, company, business veya b2b değerlerini taşıdığında, bunun için oluşturulan müşteri kişi yerine şirket türünde bir iş ortağı olur.
  • invoiceMetaField (yalnızca Stripe) bu anahtarlardan birini (örneğin bir sipariş numarasını) ve invoiceVatRatePercent ise bundan oluşturulan faturalar için KDV oranını adlandırır. İçe aktarım sırasında her tahsilat ve iade satırı o anahtarın değerine göre gruplandırılır:
    • mevcut bir satış faturasıyla eşleşen bir değer (harici referansı externalRef o değer olan bir satış siparişi - ecommerce/orders/create, herhangi bir kanal - veya tam numarası fullNumber o değer olan bir fatura) grubu ilgili faturaya bağlar;
    • faturası olmayan bir değer yeni bir fatura oluşturur: Customer Email adresinden alınan iş ortağı (createPartner için olduğu gibi eksikse oluşturulur), tahsilat başına bir satır (Checkout Line Item Summary veya metin olarak Description, invoiceVatRatePercent oranında KDV dahil fiyat olarak tahsilat tutarı), düzenleme tarihi = ilk tahsilat tarihi, şirket ve kart ülkesinden alınan KDV uygulaması. Fatura anında düzenlenir ve deftere işlenir, ayrıca stripe kanalına ve externalRef olarak o değere sahip bir satış siparişi kaydedilir, böylece sonraki içe aktarımlar oluşturmak yerine bağlama işlemi yapar;
    • gruptaki her tahsilat daha sonra faturaya bir ödeme olarak eşleştirilir (tahsilat işlenir); her iade, iade edilen tutar için faturaya karşılık düzenlenmiş bir alacak dekontu oluşturur ve iadeyi bununla eşleştirir. Sayılar invoicesCreated, invoicesLinked, creditNotesCreated ve paymentsMatched olarak döner; işlenemeyen gruplar (warnings içinde listelenen müşteri e-postası olmayan, para birimleri karışık, taslak halindeki veya halihazırda tamamen ödenmiş bağlı faturalar) new banka hareketi olarak bırakılır. Aynı şablonda Amount alanını da bir defteri kebir hesabıyla eşleştirmeyin: bir faturayla eşleştirilen tahsilat ikinci kez işlenmez, ancak eşleştirilmemiş olan işlenirdi.
  • Şablon adları şirket başına benzersizdir.
  • camt.053 ve banka bağlantısı şablonları, Stripe sütunları yerine ekstreden okunan aynı seçenekleri taşır:
    • Eksik iş ortaklarını oluştur (Create missing partners): Gelen para borçlu adı satırında (TxDtls/RltdPties/Dbtr/Nm, akışta debtor.name) createPartner seçeneği, gelen parayı gönderen her bilinmeyen ödeyici için bir müşteri oluşturur; giden para alacaklı adı satırında (TxDtls/RltdPties/Cdtr/Nm, akışta creditor.name) ise giden parayı alan her bilinmeyen alacaklı için bir tedarikçi oluşturur. İş ortakları IBAN (saklandığı yer partner_bank_accounts) ile, ardından tam ada göre tanınır; yeni bir iş ortağı, ad bir yasal tür (UAB, MB, SIA, GmbH, Ltd, …) içeriyorsa şirket, aksi takdirde kişidir. Sayı, customersCreated (dosya içe aktarımı) veya partnersCreated (akış senkronizasyonu) olarak döner.
    • Faturaları referansına göre bağla (Link invoices by reference): Bir havale veya referans satırına (TxDtls/RmtInf/Ustrd, TxDtls/RmtInf/Strd/CdtrRefInf/Ref, TxDtls/Refs/EndToEndId; akışta remittance_information, reference_number) ayarlanan invoiceMetaField, referansı, havalesi veya açıklaması açık bir düzenlenen satış faturasının (gelen para) veya kaydedilen alış faturasının (giden para) numarasını içeren her yeni banka satırını eşleştirir ve ödemeyi işler. Ödeyenin IBAN adresi bir iş ortağında kayıtlıysa veya ödeyenin adı bir iş ortağının adı ya da koduna eşitse, faturanın o iş ortağına ait olması gerekir. Bilinmeyen bir ödeyenden gelen ödeme, yalnızca faturanın kalan bakiyesine eşit olduğunda ve fatura numarası seri önekini içerdiğinde bağlanır; böylece bir tutar gibi çıplak bir sayı asla referans olarak alınmaz. Kalan bakiyeden büyük bir ödeme asla bağlanmaz. Bu kontrollerden geçmeyen satırlar manuel eşleştirme için yeni kalır ve uyarılarda (warnings) listelenir. advanceInvoices: true seçeneği ile bilinen bir iş ortağından gelen eşleşmemiş bir gelen ödeme, invoiceVatRatePercent veya invoiceItemId oranındaki tutar için düzenlenen bir avans faturası (advance türünde) oluşturur ve ödemeyi bununla eşleştirir; iş ortağı bilinmelidir, bu nedenle borçlu satırını da işaretleyin.
    • İşlem koduna göre muhasebe kuralları (Posting rules by transaction code): Ntry/Amt / transaction_amount.amount alanına ek olarak, alan listesinde kural satırları bulunur: Ntry/BkTxCd=CHRG, =INTR, =TAXE, Ntry/CdtDbtInd=DBIT, =CRDT (akış: bank_transaction_code=…, credit_debit_indicator=…). Bir satır, eşleştiği ilk kuralın hesabına işlenir: önce banka işlem kodu ailesi, ardından yönü, son olarak da düz tutar satırı. Kural satırları dosya ile karşılaştırılmaz.
    • Banka masrafları iş ortağı (Bank charges partner): …=CHRG kural satırındaki createPartner, bankanın adını taşıyan (ekstre Stmt/Acct/Svcr/FinInstnId/Nm, bağlantının bankası veya defteri kebir banka hesap adı) bir tedarikçi oluşturur ve her masrafı bu iş ortağına kaydeder.
    • Banka bağlantısı şablonları, akış hesapları başına bank/feeds/accounts/configure (uygulamada Banka → Bağlantılar) ile seçilir. Bu aynı zamanda syncSchedule (manual, daily, weekly, monthly) ayarını yapar: API, periyodu geçtiğinde takvimi olan hesapları kendi başına senkronize eder. Şablonlar her bank/feeds/sync işleminde uygulanır; senkronizasyon yanıtı daha sonra posted, partnersCreated, invoicesLinked, invoicesCreated, paymentsMatched ve warnings değerlerini bildirir.

format yerine bank/statements/import endpoint'ine templateId geçirin: şablonun türü ayrıştırıcıyı (parser) seçer ve dosya, şablonda listelenen her alanı içermelidir. Herhangi birinden yoksun bir dosya, HTTP 422 ve eksik sütun veya öğe adlarıyla reddedilir. Meta veri alanlarının bulunması zorunlu değildir. Banka bağlantısı şablonları canlı bir PSD2 akışını tanımlar ve dosya içe aktarımı için kullanılamaz.

Bir ISO 20022 şablonu MT940 dosyalarını da okur: {1: veya :20: ile başlayan (veya "format": "mt940" ile gönderilen) bir dosya MT940 olarak ayrıştırılır ve şablonun referans eşleştirme ile muhasebe kuralları satırlarına uygulanır. MT940 için öğe kontrolü atlanır ve MT940 herhangi bir ISO 20022 banka işlem kodu taşımadığından Ntry/BkTxCd=… kuralları asla MT940 satırlarına uygulanmaz; bunun yerine Ntry/CdtDbtInd=… kurallarını kullanın.

Bir banka hesabı tek bir para birimi barındırır. Farklı bir para birimindeki bir ekstre HTTP 422 ile reddedilir (aynı IBAN için birkaç para biriminde ekstreler içeren bir camt.053 dosyasında yalnızca hesabın para birimindeki ekstre içe aktarılır); bank/transactions/import endpoint'ine hesabınkinden farklı bir currency ile gönderilen bir satır da aynı şekilde reddedilir.

accountCode değerine sahip bir alandan üretilen her hareket, içe aktarım anında tek bir dengeli yevmiye işlemi olarak işlenir: gelen para, banka hesabının defteri kebir hesabını borçlandırır ve eşleştirilen hesabı alacaklandırır; giden para, eşleştirilen hesabı borçlandırır ve banka hesabının defteri kebir hesabını alacaklandırır. Tutar, hareket tarihinde baz para birimine dönüştürülür. Banka hareketi daha sonra bu yevmiye işlemiyle (matchedDocumentType = journal_transaction) matched (eşleştirilir) ve artık fatura eşleştirmesi için sunulmaz. Yanıt, posted sayacında bu sayıyı bildirir. Eşlenmemiş alanlardaki hareketler new olarak kalır ve daha önce olduğu gibi faturalarla eşleştirilir; örneğin Fee alanını PSP masraf gider hesabıyla eşleştirin ve tahsilatların hâlâ satış faturalarıyla eşleştirilebilmesi için Amount alanını eşlenmemiş bırakın.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "templateId": "…",
  "content": "id,Created date (UTC),Amount,…"
}

ISO 20022 camt.053 (açık bankacılık XML)

Litvanya bankaları (Swedbank, SEB, Luminor, Šiaulių bankas, …) internet bankacılıklarından hesap ekstrelerini ISO 20022 camt.053 XML formatında (genellikle ekstre dışa aktarma/indirme altında "ISO XML" veya "camt.053" formatında) indirmenize izin verir. Aynı format PSD2 hesap bilgi API'leri tarafından da döndürülür.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "camt053",
  "content": "<?xml version=\"1.0\"…>…"
}
  • Bir dosya birkaç ekstre içerebilir; her ekstrenin IBAN adresi banka hesabının IBAN adresiyle eşleşmelidir (IBAN'ı olmayan ekstreler veya IBAN'ı olmayan hesaplar olduğu gibi kabul edilir).
  • İşlem referansları (AcctSvcrRef/NtryRef, içerik özetine (content hash) geri dönerek) externalId olur.
  • Yanıt, ekstre başına meta verileri yansıtır: ekstre kimliği, dönem, açılış/kapanış bakiyeleri, işlem sayısı.
  • Karşı taraf adı, IBAN ve ödeme amacı, eşleştirme için girdi başına çıkarılır.

Zıt yöndeki ödemeler bank/payments/export aracılığıyla pain.001 olarak dışa aktarılır.

Revolut Business CSV

Bir Revolut Business hesabının işlem ekstresini CSV olarak indirin ve yerleşik şablon olan Revolut Business (templateId: "builtin-revolut") ile içe aktarın. Her şirkette bu şablon oluşturulmadan mevcuttur: bank/import-templates/list-builtin listeler, bank/import-templates/get döndürür, bank/import-templates/update ve bank/import-templates/delete ise HTTP 400 ile reddeder. Uygulamada Banka → İçe aktarım şablonları altında ilk sırada listelenir; açıldığında ayarları gösterilir ve kaydetmek kendi değiştirebileceğiniz bir şirket şablonu oluşturur.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "templateId": "builtin-revolut",
  "content": "Date started (UTC),Date completed (UTC),ID,Type,State,…"
}
  • Yalnızca State = COMPLETED olan satırlar içe aktarılır. Diğer satırlar (örneğin PENDING) dışarıda bırakılır ve warnings içinde sayılır; bunlar, tamamlandıkları sonraki bir dosya içe aktarımıyla içe aktarılır.
  • Her satır; Date completed (UTC) tarihine, Total amount tutarına, Payment currency para birimine, ID değerine externalId olarak ve Description değerine açıklamaya sahip bir banka hareketine dönüşür.
  • Giden paranın karşı tarafı Beneficiary name ve Beneficiary iban alanlarıdır; lehtarı olmayan bir kart ödemesi için Description içindeki üye iş yeridir (merchant). Gelen paranın karşı tarafı Sender name ve Sender account alanlarıdır.
  • Satırlar hesap ve para birimine göre gruplandırılır. International account number banka hesabının IBAN adresiyle eşleşmelidir ve yalnızca banka hesabının para birimindeki satırlar içe aktarılır.
  • İçe aktarıcı her satır için bir önceki satırın bakiyesi ile Total amount toplamının Balance değerine eşit olup olmadığını kontrol eder ve eşit olmadığı her satırı warnings içinde listeler.
  • Dosya şu sütunları içermelidir: Date completed (UTC), ID, Type, State, Description, Payment currency, Total amount, Reference, Sender name ve Beneficiary name.

Her içe aktarımda yerleşik şablon:

  • yukarıda Eksik iş ortaklarını oluştur bölümünde açıklandığı gibi, gelen paranın her bilinmeyen göndereni için bir müşteri ve giden paranın her bilinmeyen lehtarı veya kart üye iş yeri için bir tedarikçi oluşturur;

  • Reference veya Description alanı açık bir satış veya alış faturasının numarasını içeren her satırı eşleştirir ve yukarıdaki Faturaları referansına göre bağla kontrolleriyle ödemeyi işler;

  • faturanın eşleşmediği satırları Type değerine göre bir muhasebe kuralının hesabına işler:

    Type Muhasebe kuralı Varsayılan hesap Romanya hesap planı İşlem
    FEE bank.fees 6800 627 kuralın hesabını borçlandır, banka hesabının defteri kebir hesabını alacaklandır; iş ortağı: banka hesabının adını taşıyan bir tedarikçi
    CARD_PAYMENT bank.cardPayments 6209 628 KDV hariç olmak üzere, kuralın hesabını borçlandır, banka hesabının defteri kebir hesabını alacaklandır
    TOPUP bank.topUps 3010 1012 banka hesabının defteri kebir hesabını borçlandır, kuralın hesabını alacaklandır

    TRANSFER gibi diğer türdeki satırlar eşleştirme için new statüsünde kalır.

Hesapları ledger/posting-rules/update ile değiştirin; yerleşik şablon sonraki içe aktarımdan itibaren yeni hesapları kullanır. Bir muhasebe kuralı kapatılamaz: kart ödemelerini veya yüklemelerini deftere işlemeden içe aktarmak için Type=CARD_PAYMENT veya Type=TOPUP satırı olmayan revolut türünde bir şirket şablonu oluşturun ve onunla içe aktarın. Bu şekilde işlenen bir kart ödemesi, söz konusu fatura daha sonra kaydedildiğinde tedarikçinin faturasıyla eşleştirilmez; ikisinden birini işleyin, ikisini birden değil.

revolut türündeki bir şirket şablonu aynı sütunları kullanır ve Type=FEE, Type=CARD_PAYMENT, Type=TRANSFER ve Type=TOPUP kural satırlarıyla satırları türüne göre işleyebilir. "format": "revolut-csv" ile ve şablonsuz içe aktarmak, satırları bu adımların hiçbirini uygulamadan içe aktarır.

Stripe CSV

Stripe kontrol panelinden dışa aktarın (raporlardan herhangi biri çalışır):

  • Raporlar (Reports) → Bakiye (Balance) → Etkinlikten ayrıntılı bakiye değişimi (Itemized balance change from activity) (önerilen): sütunlar balance_transaction_id, created_utc, currency, gross, fee, net, reporting_category, description.
  • Ödemeler (Payments) → Dışa Aktar (Export): sütunlar id, Created (UTC), Amount, Fee, Currency, Description, Customer Description.
POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "stripe-csv",
  "content": "balance_transaction_id,created_utc,currency,gross,fee,net,…"
}

Stripe için özel bir banka hesabı oluşturun (örn. adı "Stripe", muhasebe hesabı 2710 veya kendi alt hesabı) - Stripe bakiyesi bir banka hesabı gibi davranır: tahsilatlar içeri akar, ücretler düşülür, ödemeler (payouts) bakiyeyi gerçek bankanıza aktarır.

İçe aktarım davranışı:

  • Her bakiye işlemi brüt tutar için tek bir banka hareketine dönüşür (externalId = bakiye işlem kimliği).
  • Sıfır olmayan bir ücret (fee), zıt işaretli ikinci bir harekete dönüşür (externalId = <id>:fee, karşı taraf "Stripe") - böylece ücretler gelirlerden ayrı olarak masraf olarak eşleştirilebilir/işlenebilir. İadeler üzerinden iade edilen ücretler pozitif tutarlar olarak içeri girer.
  • Ödeme (Payout) satırları tekli negatif hareketler olarak içe aktarılır; bunları gerçek banka hesabı ekstrenizdeki ilgili gelen işlemle eşleştirin.
  • Sıfır tutarlı satırlar atlanır; tarih created_utc (UTC) değerinden alınır.
  • Para hareket ettirmeyen ödeme dışa aktarma satırları atlanır: Captured = false (yetkilendirmeler/geciktirilmiş tahsilatlar) ve Status Failed/Canceled (Başarısız/İptal Edildi).
  • Sıfır olmayan bir İade Edilen Tutar (Amount Refunded) üçüncü bir negatif harekete dönüşür (externalId = <id>:refund, tarihi Refunded date (UTC) - böylece ödeme satırlarına gömülü kısmi ve tam iadeler kaybolmaz.

PSP mutabakat uzlaştırması (Stripe payout raporları)

Toplu bir ödemeyi (lump-sum payout) temelindeki siparişlere, iadelere, ücretlere ve ters ibrazlara (chargebacks) ayırmak için, düz ekstre içe aktarımı yerine mutabakat endpoint'lerini kullanın. İki Stripe dışa aktarımı kabul edilir (otomatik olarak algılanır):

  • Raporlar (Reports) → Ödemeler (Payouts) → Ödeme mutabakatı, ayrıntılı (Payout reconciliation, itemized) (rapor türleri payout_reconciliation.itemized.* veya payout_reconciliation.by_id.itemized.*) - tam, bakiye işlemi başına bir satır; canlı hesaplarda tercih edilir.
  • Ödemeler (Payments) → Dışa Aktar (Export - birleştirilmiş ödemeler) - tahsilat düzeyinde dışa aktarım; mutabakatın kullanılamadığı test/sandbox modunda çalışır. Tahsil edilen ödemeler Transfer sütunundaki ödeme kimliğine göre gruplandırılır; tahsil edilmemiş/başarısız satırlar atlanır (skippedNotSettled); sıfır olmayan bir Amount Refunded tutarı, tahsilatın ödeme grubunda sentetik bir iade satırına dönüşür - bu bir yaklaşımdır, çünkü iade gerçekte daha sonraki bir ödemede mutabakata varılmış olabilir. Eşleştirme referansları tahsilat kimliğinden, PaymentIntent ID, Invoice Number, Client Reference ID ve her … (metadata) sütunundan (örn. meta verideki bir sipariş numarası) gelir.

Tek bir CSV birçok ödemeyi kapsayabilir. Stripe ayrıntılı raporu bölüm başına bir dosya olarak indirir (…_charge_…, …_refund_…, …_fee_…); hepsini içe aktarın: halihazırda içe aktarılmış bir ödemenin satırları, henüz işlenmemiş olması koşuluyla mevcut grupla birleşir (updated sayacında raporlanır) ve toplu iş toplamları yeniden hesaplanır.

POST /v1/bank/settlements/import
{
  "bankAccountId": "…",
  "provider": "stripe",
  "content": "balance_transaction_id,created_utc,…,reporting_category,…,automatic_payout_id,…"
}

İçe aktarım davranışı:

  • Satırlar brüt/ücret/net toplamlarıyla (satır net toplamı = bankanıza gelen tutar) automatic_payout_id değerine göre mutabakat gruplarına (settlement batches) - ödeme başına bir grup - ayrılır. Bir ödemeyi yeniden içe aktarmak atlanır (skipped sayacı). Henüz bir ödemeye atanmamış satırlar ve payout satırlarının kendisi atlanır ve ayrı olarak sayılır.
  • Her tahsilat/iade/itiraz satırı, sırasıyla şunlar kullanılarak bir satış faturasıyla otomatik olarak eşleştirilir: bir e-ticaret siparişinin externalRef değeri (order_id, payment_intent_id, source_id, charge_id veya herhangi bir *_metadata[...] sütunundan herhangi bir değer), bu sütunlarda görünen bir fatura fullNumber değeri ve - iadeler ve ters ibrazlar için - önceden eşleştirilmiş bir tahsilatın charge_id değeri (aynı dosya veya önceki içe aktarımlar).
  • bank/settlements/list / bank/settlements/get ile inceleyin; kalanları bank/settlements/match { lineId, invoiceId } (veya eşleştirmeyi kaldırmak için invoiceId: null) ile düzeltin.

POST /v1/bank/settlements/post { id, date?, commissionPercent? } tüm grubu tek bir dengeli yevmiye işlemi olarak işler ve eşleştirilen faturaları mutabık kılar (paidAmount/paymentStatus, sale_invoice.paid Webhook'ları):

  • Net ödeme için banka hesabı genel muhasebesini (GL) borçlandırın; kesilen ücretler ve ücret satırları için PSP ücretlerini (settlements.fees, varsayılan 6800) borçlandırın.
  • Eşleştirilen tahsilat başına ticari alacakları alacaklandırın; iadeler ve ters ibrazlar bunu tersine çevirir. Uygulama, her faturanın kalan tutarıyla sınırlıdır - herhangi bir fazlalık bir uyarı ile şüpheli hesapta (suspense account) son bulur.
  • Eşleştirilmemiş tahsilatlar: commissionPercent ayarlanmışsa komisyon gelirine (settlements.commissionRevenue, varsayılan 5001) ve satıcı borcuna (settlements.sellerPayable, varsayılan 4499) - toplanan paranın çoğunlukla satıcılara ait olduğu pazaryeri akışına - bölünür. Bu olmadan, settlements.suspense (varsayılan 4440, alınan avanslar) hesabına park edilirler.
  • platform_earning satırları (Stripe Connect uygulama ücretleri) komisyon gelirine işlenir; transfer satırları (bağlı satıcılara yapılan ödemeler) satıcı borcunu azaltır.
  • Dört hesabın tümü muhasebe kuralları (ledger/posting-rules) aracılığıyla şirket bazında geçersiz kılınabilir (overridable).
  • Tahsilatı, ücreti veya iadesi Stripe ödemeleri dışa aktarımı (bank/statements/import) aracılığıyla başka bir banka hesabına zaten içe aktarılmış olan bir satır, ücretlere, alacaklara veya şüpheli hesaba kaydedilmez. Bunun yerine net tutarı ilgili banka hesabının defteri kebir hesabına alacak kaydedilir, böylece Stripe banka hesabı ödeme ödeme tasfiye edilir. summary.clearedAmount bu şekilde taşınan toplam tutardır; tutarı o hesabın tuttuğu tutardan farklı olan bir satır warnings içinde adlandırılır. Kaydedilecek hiçbir şey kalmazsa, grup journalTransactionId alanı boş (null) olarak işlenir.

bank/settlements/list ve /get endpoint'leri grup başına clearedNet, clearingDifference (ödeme satırları eksi diğer banka hesabının bunlar için tuttuğu tutarlar; mutabık olduklarında sıfır) ve clearingOpenCount (farkı veya işlenmemiş hareketi olan satırlar) değerlerini döndürür; /get satır başına clearingBankAccountId, clearingBooked, clearingDifference ve clearingUnposted değerlerini döndürür. Tek bir tahsilatın iade satırları birlikte karşılaştırılır, çünkü ödemeler dışa aktarımı yalnızca iade edilen toplamı barındırır. Ödemesi işlendikten sonra içe aktarılan bir Stripe ödemeleri dışa aktarımı, söz konusu ödemenin hareketlerini atlar ve bunu warnings içinde adlandırır.

Komisyonun üzerindeki KDV ayrıca faturalandırılır (satıcıya bir komisyon faturası düzenleyin); bölünme yalnızca toplanan nakdi tahsis eder.

Farklı para birimindeki ödemeler

Yevmiye her zaman şirketin baz para biriminde yazılır, ancak farklı bir para birimindeki bir ödeme otomatik olarak işlenir - manuel giriş gerekmez:

  • Grup, deftere işleme tarihinin (date, ödeme tarihine, ardından bugüne geri dönerek) kuru üzerinden çevrim yapar. Kur, resmi kurdan en az onun kadar güncel olduğunda şirketin o para birimi için kendi kuru (reference/exchange-rates/set), aksi takdirde o tarihteki veya o tarihten önceki en son resmi kurdur. Tarihte veya öncesinde kur olmadığında çağrı 422 ile başarısız olur ve reference/exchange-rates/sync değerini adlandırır.
  • Her hesap, ticari alacaklar (accounts receivable) hariç -ki bu, her faturanın düzenlendiği fxRate kurundan mahsup edilir- o grup kuru üzerinden çevrim yapar. İki kur arasındaki kalıntı, yevmiyenin yine de denkleşmesi için gerçekleşmiş bir kur farkı olarak bank.fxGain (varsayılan 5803) veya bank.fxLoss (varsayılan 6803) hesabına işlenir.
  • Yanıt summary, kullanılan fxRate kurunu ve ortaya çıkan exchangeDifference tutarını döndürür ve grup işlendiği kuru korur. Kendi para birimi grup para biriminden farklı olan eşleştirilmiş bir faturanın mutabakatı yapılmaz: tutarı bir uyarı ile şüpheli hesaba gider.
  • Tek bir içe aktarım sınırı kalır: satırları birkaç para birimini karıştıran tek bir ödeme 422 ile reddedilir, para birimi söz konusu ödeme için halihazırda saklanan gruptan farklı olan bir yeniden içe aktarım da aynı şekilde reddedilir.

Manuel / özel akışlar

Başka herhangi bir şey düz JSON olarak gönderilebilir:

POST /v1/bank/transactions/import
{
  "bankAccountId": "…",
  "transactions": [
    { "date": "2026-07-01", "amount": "-25.00", "currency": "EUR",
      "counterpartyName": "…", "description": "…", "externalId": "unique-ref-1" }
  ]
}

Yeniden içe aktarımları idempotente (tekrarlanabilir ve güvenli) tutmak için işlem başına kararlı bir externalId sağlayın.