Hızlı başlangıç

Bu sayfa sizi sıfırdan ilk başarılı isteğe, ardından ilk belgeyi güvenle oluşturmaya götürür. Tüm örnekler doğrudan çalıştırılabilir; yalnız kimlik bilgilerini kendi değerlerinizle değiştirin.

Ön koşullar

SarrafPro hesabınızın Free dışında bir pakette ve aktif olması
Panelden üretilmiş bir API kullanıcısı: apiUserId ve secretKey
HTTP isteği atabileceğiniz bir araç (curl, Postman, kendi uygulamanız)

secretKey bir paroladır. Sunucu tarafında saklayın; tarayıcı, mobil uygulama veya herkese açık depo gibi istemci ortamlarına koymayın.

Adımlar

Kimlik doğrulamayı kurun

Tüm uçlar HTTP Basic kimlik doğrulaması kullanır: kullanıcı adı apiUserId, parola secretKey.

curl 'https://api.sarraf.pro/v1/customers?pageSize=1' \
  -u 'apiUserId:secretKey'

Başarılı cevap sabit zarf biçimindedir:

{
  "success": true,
  "data": [ { "id": "6a9c7e2bf2fb39feccb3480b", "idNo": "1976926558", "nameSurname": "ÖRNEK MÜŞTERİ" } ],
  "meta": { "requestId": "c6c85e42-dd06-4cb3-885b-c0ca551ee866", "timestamp": "2026-09-20T09:00:00.000Z", "page": 1, "limit": 1, "total": 114, "pages": 114 }
}

401 alıyorsanız anahtarın aktif ve geçerlilik süresinin dolmamış olduğunu doğrulayın.

Listeleri sayfalayın ve filtreleyin

Liste uçları page ve pageSize (en fazla 100) ile sayfalanır, sort ile sıralanır, kaynağa özel alanlarla filtrelenir.

curl 'https://api.sarraf.pro/v1/bank-transactions?incoming=true&pageSize=50&sort=transactionDate:desc' \
  -u 'apiUserId:secretKey'

Bilinmeyen bir filtre 400 döner — sözleşme sessizce genişlemez. Tüm ortak kurallar Genel Bakış sayfasındadır.

Değişenleri artımlı çekin

Her seferinde tüm veriyi çekmek yerine son senkron zamanınızdan sonrasını isteyin:

curl 'https://api.sarraf.pro/v1/customers?updatedSince=2026-09-01T00:00:00.000Z&sort=updatedAt:asc&pageSize=100' \
  -u 'apiUserId:secretKey'

Son sayfadaki updatedAt değerini saklayın ve bir sonraki turda updatedSince olarak gönderin.

Belge oluşturmadan önce hesaplatın

Fatura ve gider pusulası uçlarında yan etkisiz ön hesaplama vardır: kalemleri, tutarları ve belge türünü gösterir, hiçbir kayıt oluşturmaz.

curl -X POST 'https://api.sarraf.pro/v1/invoices/preview' \
  -u 'apiUserId:secretKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "source": "manual",
      "amount": 100000,
      "idNo": "11111111111",
      "nameSurname": "NİHAİ TÜKETİCİ",
      "paymentType": "bank"
    }
  }'

Dönen totals ve lines değerlerini doğrulayın.

Önce taslak, sonra gerçek belge

Aynı gövdeyi isDraft: true ile POST /v1/invoices ucuna gönderdiğinizde resmî fatura kesilmez; yalnız taslak oluşur ve DELETE /v1/invoices/{id} ile iptal edilebilir.

curl -X POST 'https://api.sarraf.pro/v1/invoices' \
  -u 'apiUserId:secretKey' \
  -H 'Content-Type: application/json' \
  -d '{ "data": { "source": "manual", "amount": 100000, "idNo": "11111111111", "paymentType": "bank", "isDraft": true } }'

Sonuçtan memnunsanız isDraft alanını kaldırarak gerçek belgeyi oluşturun. Başarılı cevap 201 döner ve invoiceId ile belge Faturalar ucundan okunabilir.

isDraft olmadan gönderilen istek gerçek mali belge üretir ve API’den geri alınamaz. Entegrasyonunuzu geliştirirken önce preview, sonra taslak akışını kullanın.

Fatura gönderimi 502 UPSTREAM_RESULT_UNCERTAIN döndürürse aynı isteği otomatik tekrar göndermeyin. Sağlayıcı belgeyi kabul etmiş olabilir. Cevaptaki traceId ve details[0].attemptId değerlerini saklayıp sonucu SarrafPro üzerinden doğrulayın.

Yazma isteklerinde gövde zarfı

Tüm POST uçlarında gövde data zarfı içinde gönderilir:

{ "data": { "source": "manual", "amount": 100000 } }

Zarf eksikse veya bilinmeyen bir alan gönderilirse istek 400 ile reddedilir.

Sonraki adımlar

Ortak sözleşme

Hata kodları, sayfalama, filtreleme ve alan disiplini.

Fatura işlemleri

Şablon seçimi, ön hesaplama, oluşturma ve taslak iptali.

Yardım

Sorun yaşarsanız hata cevabındaki traceId değerini paylaşmanız yeterlidir; istek kaydı bu kimlikle bulunur. Destek: destek@sarraf.pro

Başlangıç

API'ye Giriş

Müşteriler

Banka

Faturalar

Giderler

KMTS

Ön koşullar

Adımlar

Yazma isteklerinde gövde zarfı

Sonraki adımlar

Ortak sözleşme

Fatura işlemleri

Yardım

​Ön koşullar

​Adımlar

​Yazma isteklerinde gövde zarfı

​Sonraki adımlar

Ortak sözleşme

Fatura işlemleri

​Yardım

Ön koşullar

Adımlar

Yazma isteklerinde gövde zarfı

Sonraki adımlar

Yardım