GeliştiriciBeta

Muhasefy API

Muhasefy API; faturalarınızı, cari kayıtlarınızı, işlemlerinizi ve hesaplarınızı kendi sistemlerinize programatik olarak bağlamanız için tasarlanmıştır. Bu rehber, API hazır olduğunda nasıl çalışacağını ve isteklerin nasıl yapılandırılacağını açıklar.

Erken erişim için: api@muhasefy.com

Genel Bakış

Muhasefy API, REST mimarisine dayanan, tahmin edilebilir kaynak yollarına sahip bir arayüzdür. Tüm istekler ve yanıtlar JSON biçimindedir; standart HTTP yöntemlerini (GET, POST) ve standart HTTP durum kodlarını kullanır. API üzerinden faturalarınızı, müşteri ve tedarikçi kayıtlarınızı, işlemlerinizi ve hesaplarınızı okuyabilir; yeni kayıtlar oluşturabilirsiniz.

API'yi kullanarak kendi e-ticaret altyapınızı, iç uygulamalarınızı veya otomasyonlarınızı Muhasefy ile bağlayabilirsiniz. Verileriniz her zaman size aittir ve programatik olarak taşınabilir kalır.

Beta ve Erken Erişim

API şu anda Beta aşamasındadır ve uç noktalar henüz herkese açık değildir.

Bu sayfa, API genel kullanıma açıldığında nasıl çalışacağını şeffaf biçimde paylaşmak için hazırlanmıştır. Aşağıdaki yollar, alan adları ve örnek yanıtlar tasarım niteliğindedir; genel kullanıma açılana kadar değişebilir. Üretim ortamınızı bu sürüme göre kurmadan önce erken erişim programına katılmanızı öneririz.

Erken erişim, geri bildirim ve API erişim anahtarları için api@muhasefy.com adresinden bizimle iletişime geçebilirsiniz. API erişimi şu an Kurumsal Enterprise planı kapsamında planlanmaktadır.

Kimlik Doğrulama

Muhasefy API, kimlik doğrulama için gizli API anahtarları kullanır. Anahtarınızı her isteğin Authorization başlığında Bearer şeması ile gönderirsiniz. Geçerli bir anahtar olmadan yapılan istekler 401 Unauthorized yanıtı alır.

API anahtarınız bir parola gibidir. Gizli tutun; istemci tarafı kodda, herkese açık depolarda veya tarayıcıda paylaşmayın. Anahtarın sızdığından şüphelenirseniz hemen yenileyin.

Örnek - kimlik doğrulamalı istek

curl https://muhasefy.com/api/v1/invoices \
  -H "Authorization: Bearer mhsfy_sk_canli_xxxxxxxxxxxxxxxx"

Temel URL ve Sürümleme

Tüm API istekleri aşağıdaki temel URL üzerinden ve HTTPS ile yapılır. Şifrelenmemiş (HTTP) istekler kabul edilmez.

https://muhasefy.com/api/v1

Sürüm, URL içinde yer alır (örneğin /v1). Geriye dönük uyumluluğu bozan değişiklikler yeni bir sürüm numarasıyla yayımlanır; mevcut sürümünüz etkilenmez. Küçük ve uyumlu iyileştirmeler mevcut sürüm içinde yapılabilir.

İstek ve Yanıt Formatı

İstek gövdeleri ve yanıtlar UTF-8 kodlu JSON biçimindedir. Gövde gönderen isteklerde Content-Type başlığını application/json olarak ayarlayın. Tarihler ISO 8601 biçiminde (örneğin 2026-06-17), tutarlar ondalık sayı olarak ve para birimleri ISO 4217 kodlarıyla (örneğin TRY, USD, EUR) gösterilir.

Listeleme uç noktaları, kayıtların data dizisinde döndüğü bir liste nesnesi (object: "list") verir. Tekil kayıtlar ise ilgili kaynak nesnesini döndürür. Her nesne, türünü belirten bir object alanı içerir.

AuthorizationBearer API anahtarınız (zorunlu)

Content-Typeapplication/json (gövdeli isteklerde)

Acceptapplication/json

Kaynaklar

Aşağıda API ile erişebileceğiniz temel kaynaklar, uç noktaları ve örnek istek ile yanıtları yer alır. Örneklerdeki kimlikler ve değerler yalnızca gösterim amaçlıdır.

Faturalar

Satış, alış, ihracat ve proforma faturalarınızı listeleyin, tek bir faturayı getirin veya yeni fatura oluşturun. Faturalar kendi vergi kimliğiniz altında düzenlenir.

GET/v1/invoicesFaturaları listeler

GET/v1/invoices/{id}Tek bir faturayı getirir

POST/v1/invoicesYeni fatura oluşturur

İstek - faturaları listele

curl https://muhasefy.com/api/v1/invoices \
  -H "Authorization: Bearer mhsfy_sk_canli_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Yanıt - 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "inv_8Hk2Qp",
      "object": "invoice",
      "invoice_number": "MUH2026000042",
      "type": "sales",
      "status": "sent",
      "client_id": "cli_3Fa9Lt",
      "issue_date": "2026-06-15",
      "due_date": "2026-06-30",
      "currency": "TRY",
      "subtotal": 10000.00,
      "tax_total": 2000.00,
      "total": 12000.00,
      "paid_amount": 0,
      "created_at": "2026-06-15T09:21:00Z"
    }
  ],
  "has_more": false,
  "total_count": 1
}

İstek - yeni fatura oluştur

curl https://muhasefy.com/api/v1/invoices \
  -H "Authorization: Bearer mhsfy_sk_canli_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sales",
    "client_id": "cli_3Fa9Lt",
    "issue_date": "2026-06-17",
    "due_date": "2026-07-01",
    "currency": "TRY",
    "items": [
      {
        "description": "Danışmanlık hizmeti",
        "quantity": 1,
        "unit_price": 10000,
        "tax_rate": 20
      }
    ]
  }'

Müşteriler

Cari müşteri kayıtlarınızı yönetin. Müşteri adı, vergi kimliği, vergi dairesi ve iletişim bilgileriyle birlikte listeleme, getirme ve oluşturma işlemleri.

GET/v1/clientsMüşterileri listeler

GET/v1/clients/{id}Tek bir müşteriyi getirir

POST/v1/clientsYeni müşteri oluşturur

İstek - müşterileri listele

curl https://muhasefy.com/api/v1/clients \
  -H "Authorization: Bearer mhsfy_sk_canli_xxxxxxxxxxxxxxxx"

Yanıt - 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "cli_3Fa9Lt",
      "object": "client",
      "name": "Örnek Teknoloji A.Ş.",
      "email": "muhasebe@ornek.com",
      "phone": "+90 212 000 00 00",
      "tax_number": "1234567890",
      "tax_office": "Beşiktaş",
      "city": "İstanbul",
      "created_at": "2026-05-02T12:00:00Z"
    }
  ],
  "has_more": false,
  "total_count": 1
}

Tedarikçiler

Cari tedarikçi kayıtlarınızı yönetin. Müşteri kaynağıyla aynı yapıya sahiptir; alış ve tedarik süreçlerinizdeki firmaları temsil eder.

GET/v1/vendorsTedarikçileri listeler

GET/v1/vendors/{id}Tek bir tedarikçiyi getirir

POST/v1/vendorsYeni tedarikçi oluşturur

İstek - tedarikçileri listele

curl https://muhasefy.com/api/v1/vendors \
  -H "Authorization: Bearer mhsfy_sk_canli_xxxxxxxxxxxxxxxx"

Yanıt - 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "ven_7Qm4Rb",
      "object": "vendor",
      "name": "Örnek Tedarik Ltd. Şti.",
      "email": "siparis@ornektedarik.com",
      "phone": "+90 216 000 00 00",
      "tax_number": "9876543210",
      "tax_office": "Kadıköy",
      "city": "İstanbul",
      "created_at": "2026-04-18T10:45:00Z"
    }
  ],
  "has_more": false,
  "total_count": 1
}

İşlemler

Kasa ve banka hesaplarınızdaki gelir ve gider hareketlerini listeleyin veya yeni hareket kaydı oluşturun. Her işlem bir hesaba bağlıdır.

GET/v1/transactionsİşlemleri listeler

GET/v1/transactions/{id}Tek bir işlemi getirir

POST/v1/transactionsYeni işlem oluşturur

İstek - işlemleri listele

curl https://muhasefy.com/api/v1/transactions \
  -H "Authorization: Bearer mhsfy_sk_canli_xxxxxxxxxxxxxxxx"

Yanıt - 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "txn_5Lp1Vd",
      "object": "transaction",
      "account_id": "acc_9Zx7Nf",
      "type": "income",
      "amount": 12000.00,
      "currency": "TRY",
      "description": "Fatura tahsilatı",
      "transaction_date": "2026-06-16",
      "created_at": "2026-06-16T14:30:00Z"
    }
  ],
  "has_more": false,
  "total_count": 1
}

Hesaplar

Kasa ve banka hesaplarınızı listeleyin veya tek bir hesabın güncel bakiyesini ve bilgilerini getirin. Hesaplar işlemlerin bağlandığı temel kayıtlardır.

GET/v1/accountsHesapları listeler

GET/v1/accounts/{id}Tek bir hesabı getirir

İstek - hesapları listele

curl https://muhasefy.com/api/v1/accounts \
  -H "Authorization: Bearer mhsfy_sk_canli_xxxxxxxxxxxxxxxx"

Yanıt - 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "acc_9Zx7Nf",
      "object": "account",
      "name": "Ana Vadesiz TL",
      "type": "bank",
      "currency": "TRY",
      "balance": 152340.75,
      "bank_name": "Örnek Bank",
      "iban": "TR00 0000 0000 0000 0000 0000 00",
      "created_at": "2026-01-15T08:00:00Z"
    }
  ],
  "has_more": false,
  "total_count": 1
}

Hata Formatı

Bir istek başarısız olduğunda API, uygun bir HTTP durum kodu ve gövdesinde tutarlı bir hata nesnesi döndürür. Hata nesnesi; hatanın türünü (type), makine tarafından okunabilir bir kodu (code), açıklayıcı bir mesajı (message) ve ilgiliyse soruna yol açan alanı (param) içerir.

Örnek - hata yanıtı (404)

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "Belirtilen fatura bulunamadı.",
    "param": "id"
  }
}

HTTP durum kodları

200OKİstek başarıyla tamamlandı.

201CreatedKaynak başarıyla oluşturuldu.

400Bad Requestİstek hatalı veya eksik biçimlendirilmiş.

401UnauthorizedAPI anahtarı eksik veya geçersiz.

403ForbiddenBu işlem için yetkiniz yok.

404Not Foundİstenen kaynak bulunamadı.

422UnprocessableDoğrulama hatası, alan değerlerini kontrol edin.

429Too Many RequestsHız sınırı aşıldı, kısa süre sonra tekrar deneyin.

500Server ErrorBeklenmeyen bir sunucu hatası oluştu.

Sayfalama

Listeleme uç noktaları imleç (cursor) tabanlı sayfalama kullanır. limit parametresiyle sayfa başına kayıt sayısını belirleyebilirsiniz (varsayılan 25, en fazla 100). starting_after parametresine bir önceki sayfanın son kaydının kimliğini vererek sonraki sayfayı alırsınız.

Yanıttaki has_more alanı, getirilebilecek başka kayıt olup olmadığını belirtir. total_count alanı ise ölçüte uyan toplam kayıt sayısını verir.

Örnek - sayfalı listeleme

curl "https://muhasefy.com/api/v1/invoices?limit=50&starting_after=inv_8Hk2Qp" \
  -H "Authorization: Bearer mhsfy_sk_canli_xxxxxxxxxxxxxxxx"

Hız Sınırı

API, kötüye kullanımı önlemek ve kararlılığı korumak için hız sınırı uygular. Sınırlar planınıza göre belirlenir ve genel kullanıma açılışta kesinleşecektir. Her yanıt, mevcut kullanımınızı gösteren hız sınırı başlıkları içerir.

Sınırı aşan istekler 429 Too Many Requests yanıtı alır. Bu durumda X-RateLimit-Reset başlığında belirtilen ana kadar bekleyip isteği yeniden denemeniz beklenir.

Örnek - hız sınırı başlıkları

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1750000000

API erişimi mi istiyorsunuz?

Erken erişim programına katılmak, geri bildirim paylaşmak veya API erişim anahtarı talep etmek için bize ulaşın. Sorularınız için iletişim formunu da kullanabilirsiniz.

api@muhasefy.com İletişime geçin