API v1 referansı

Genel bakış

Manilo API, iOS uygulamasında kullandığınız defterin aynısını programatik olarak yönetmeye yarayan bir JSON REST API'sidir — hesaplar, kategoriler, bütçeler, paylaşılan gruplar ve işlemler. İçe aktarıcılar, dışa aktarıcılar, senkronizasyon köprüleri ve panolar oluşturmak ya da kendi otomasyonlarınızı çalıştırmak için kullanın.

• Temel URL: https://api.manilo.app — önceki temel URL api.ledgy.app çalışmaya devam ediyor.
• Sürüm ön eki: bu belgedeki tüm uç noktalar /api/v1/ altında yer alır.
• Aktarım: Yalnızca HTTPS. HTTP istekleri kabul edilmez.
• Kodlama: JSON istek ve yanıt gövdeleri. UTF-8. camelCase özellik adları.
• Kimlik doğrulama: Authorization: Bearer … her istekte gereklidir.
• Cloud aboneliği: tüm v1 uç noktalarında gereklidir. Bkz. Abonelik kapısı.

Hızlı başlangıç

İlk kimlik doğrulamalı isteğinize üç adım.

1. Kişisel Erişim Belirteci oluşturun

1. Önce Manilo panelinize giriş yapın ve Ayarlar → API Erişimi bölümünü açın.
2. Ardından + Yeni belirteç düğmesine tıklayın.
3. Belirtece açıklayıcı bir ad verin (örn. "Zapier — haftalık dışa aktarım"), ihtiyacınız olan kapsamları seçin (bkz. Kapsamlar) ve isteğe bağlı olarak bir son kullanma tarihi belirleyin.
4. Belirteci kopyalayın. Yalnızca bir kez gösterilir. Belirteçler şu ön ekle başlar: lgpat_ — ardından 64 onaltılık karakter gelir.

Aynı sayfa, etkin belirteçlerinizi son kullanım zaman damgası ve izin sayısıyla birlikte listeler, "30 gün içinde sona eriyor" uyarısını gösterir ve çöp kutusu simgesiyle herhangi bir belirteci anında iptal etmenizi sağlar. Her hesapta aynı anda en fazla 25 etkin belirteç bulunabilir.

2. Bir istek yapın

# Replace lgpat_… with your token
curl "https://api.manilo.app/api/v1/accounts" \
  -H "Authorization: Bearer lgpat_a1b2c3d4e5…"

3. Yanıtı inceleyin

{
  "items": [
    {
      "id": "acc_01HK8V…",
      "name": "Wise EUR",
      "currencyCode": "EUR",
      "initialBalance": 1240.50,
      "icon": "wallet",
      "color": "#4A90E2",
      "order": 0,
      "createdAt": "2026-04-12T08:13:09Z",
      "updatedAt": "2026-05-01T17:02:31Z"
    }
  ],
  "totalCount": 1
}

Kimlik doğrulama

Uç noktaların tamamı /api/v1/ altındadır ve bunlara gönderilen her istek bir Authorization başlığı taşımalıdır. İki belirteç türü kabul edilir:

• Kişisel Erişim Belirteci (PAT) — panelin Ayarlar → API Erişimi sayfasından oluşturduğunuz, uzun ömürlü bearer belirteci. Biçim: lgpat_ + 64 onaltılık karakter. Kapsamlıdır, iptal edilebilir, isteğe bağlı olarak süresi dolar. Tüm üçüncü taraf entegrasyonları için önerilir.
• Oturum JWT'si — birinci taraf uygulamalara (iOS, panel) verilen kısa ömürlü belirteç. Kapsam kısıtlaması yoktur. Açık bir oturumdan birini elde edebiliyorsanız tek seferlik testler için kullanabilirsiniz, ancak desteklenen yol PAT'lerdir.

Başlık biçimi

Authorization: Bearer lgpat_a1b2c3d4e5f6…

Belirteç sınırları

• Her Manilo hesabı için en fazla 25 etkin PAT.
• Oluşturma sırasında isteğe bağlı bir son kullanma tarihi belirlenebilir. Süresi dolmuş belirteçler şunu döndürür: 401 Unauthorized.
• İptal edilen belirteçler anında çalışmayı durdurur — Manilo, belirtecin yalnızca SHA-256 özetini saklar, değerini asla saklamaz; bu nedenle sızdırılan bir belirteç kurtarılamaz, yalnızca iptal edilip yenisiyle değiştirilebilir.

Sık görülen kimlik doğrulama hataları

401

Eksik, bozuk, süresi dolmuş veya iptal edilmiş belirteç.

403

Belirteç geçerli, ancak istenen uç nokta PAT'inizde bulunmayan bir kapsam gerektiriyor ya da Cloud aboneliğiniz etkin değil.

Kapsamlar

PAT'ler varsayılan olarak reddet modelini izler. Bir belirteç yalnızca sahip olduğu kapsamı gerektiren uç noktaları çağırabilir; diğer her şey şunu döndürür: 403 Forbidden. Entegrasyonunuzun gerçekten ihtiyaç duyduğu en dar kapsam kümesini verin.

Kullanılabilir kapsamlar:

Aşağıda listelenen her uç nokta, gerektirdiği kapsamı küçük mor bir rozet olarak gösterir. :write kapsamları :read kapsamını içermez — ikisine de ihtiyacınız varsa ikisini de isteyin.

Abonelik kapısı

Salt okunur olanlar dahil tüm v1 uç noktaları, çağrıyı yapan kullanıcının etkin bir Manilo Cloud aboneliği olmasını gerektirir. Abonelik sona ermişse, süresi dolmuşsa veya hiç başlatılmamışsa API şu yanıtı verir:

HTTP/1.1 403 Forbidden
X-Subscription-Required: true
Content-Type: application/json

{ "error": "Active cloud subscription required" }

Yanıttaki X-Subscription-Required başlığı, istemcilerin abonelik engelini genel bir izin reddinden ayırt etmesini sağlar. Erişimi geri kazanmak için Cloud'u iOS uygulamasından ya da şu adresten yeniden etkinleştirin: dashboard.manilo.app/upgrade.

Hatalar

Hatalar standart HTTP durum kodlarını kullanır. Yanıt gövdesi tek alanlı bir JSON nesnesidir:

{ "error": "Human-readable message" }

İşlemeniz gereken durum kodları:

200

OK — kaynak döndürüldü ya da liste döndürüldü.

201

Created — yeni kaynak oluşturuldu. Location başlığı kanonik URL'yi gösterir.

204

No Content — silme başarılı; gövde yok.

400

Doğrulama başarısız — zorunlu alan eksik, değer aralık dışında ya da bozuk JSON.

401

Kimlik doğrulama başarısız — bkz. Kimlik doğrulama.

403

İzin reddedildi — kapsam yetersiz ya da abonelik etkin değil.

404

Kaynak bulunamadı ya da yetkilendirme nedeniyle gizlendi.

409

Çakışma — örneğin benzersizlik kısıtlaması ihlali.

5xx

Sunucu tarafında hata. Idempotent okumalar üstel geri çekilmeyle güvenle yeniden denenebilir.

Sayfalama ve filtreler

Liste uç noktaları varsayılan olarak eşleşen tüm öğeleri döndürür. Büyüyebilecek tek kaynak olan işlemler, imleç tabanlı sayfalamayı destekler.

İşlem imleci

curl "https://api.manilo.app/api/v1/transactions?limit=50&type=expense&dateFrom=2026-01-01" \
  -H "Authorization: Bearer lgpat_…"

Yanıt bir nextCursor alanı içerir. Sonraki sayfayı almak için bunu cursor sorgu parametresi olarak geri gönderin; nextCursor değeri null olduğunda sona ulaşmışsınız demektir.

• limit — sayfa boyutu, şu aralığa sıkıştırılır: 1..200. Varsayılan: 50.
• cursor — opak belirteç. Kara kutu olarak değerlendirin.
• type, dateFrom, dateTo, categoryId, accountId, groupId — isteğe bağlı filtreler; bkz. İşlemleri listele uç noktası.

Türler ve biçimler

• Kimlikler — opak dizeler. Bunları ayrıştırmayın; büyük/küçük harfe duyarlı UTF-8 tanımlayıcılar olarak değerlendirin.
• Zaman damgaları — UTC cinsinden ISO-8601, sonunda Z ile; örn. "2026-05-13T10:30:00Z".
• Tarihler (örn. işlem date alanı) — aynı ISO-8601 biçimi, ancak yalnızca tarih kısmı anlamlıdır.
• Para — en fazla 4 ondalık basamakla ana birim cinsinden JSON sayıları (örn. 12.50). Asla alt birim değil. Her zaman currencyCode ile birlikte kullanılır.
• Para birimi kodları — ISO-4217, tam olarak üç büyük harf (örn. "EUR", "USD", "GBP").
• Silme işlemleri — tüm silme işlemleri yumuşak silmedir. Silinen öğeler liste/getirme yanıtlarında görünmez; paylaşım tarafları ve geçmiş fişler korunur.
• Yan etkiler — bir hesabı, kategoriyi veya grubu silmek, bağlı işlemleri olduğu gibi bırakır; yalnızca referansları kaldırılır. Hesabı sil uç noktası açık bir strateji kabul eder.

Hesaplar

Hesaplar, bakiyeleri tutan kovalardır — bir banka hesabı, bir kredi kartı, bir nakit cüzdan, bir yatırım hesabı. Her işlem bunlardan birine (transferlerde ikisine) bağlıdır.

POST /api/v1/accounts
{
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E"
}

{
  "id": "acc_01HK8V…",
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E",
  "iconColor": null,
  "shareInviteToken": null,
  "createdAt": "2026-05-13T10:30:00Z",
  "updatedAt": "2026-05-13T10:30:00Z"
}

Kategoriler

Kategoriler, bir işlemin ne için olduğunu etiketler (market, kira, serbest çalışma geliri). Sistem kategorileri salt okunurdur ve tüm kullanıcılar tarafından paylaşılır; kullanıcı kategorileri sizin yönetiminizdedir. Kategori grupları, ilişkili kategorileri bir arada toplar.

Kullanıcı kategorileri

Kategori grupları

Bütçeler

Bir bütçe, yinelenen bir dönem boyunca bir kategorideki harcamayı sınırlar (categoryId null olduğunda defterin tamamını sınırlar). Bir bütçeyi bir grupla paylaşmak için groupId alanını ayarlayın.

Gruplar

Gruplar paylaşılan defterlerdir — bir ev, bir gezi, ortak bir daire. Her üye aynı işlemleri görür; sahiplik kişisel kalır. Üyelik ve davetler iOS uygulamasında yönetilir; buradaki API yüzeyi kaynağın kendisidir.

İşlemler

İşlemler, defterin fiilleridir. Dört biçimde gelirler: income, expense, transfer (hesaptan hesaba) ve adjustment (tek seferlik yeniden dengeleme). Temel uç nokta gelir/gider oluşturur; transferlerin kendi uç noktası vardır; yüksek hacimli içe aktarıcılar için toplu varyantlar mevcuttur.

{
  "items": [ /* TransactionDto[] */ ],
  "totalCount": 317,
  "nextCursor": "eyJrIjoiMjAyNi0wNS0xM1QxMDoz…"
}

POST /api/v1/transactions
{
  "type": "expense",
  "amount": 8.50,
  "currencyCode": "EUR",
  "date": "2026-05-12T09:14:00Z",
  "accountId": "acc_01HK8V…",
  "categoryId": "cat_food_drinks",
  "payee": "Pret",
  "note": "Flat white"
}

Toplu işlemler

İçe aktarıcılar için tasarlandı. Her toplu istek en fazla 100 öğe ile sınırlıdır ve en iyi çaba ilkesiyle çalışır: tek bir hatalı satır diğerlerini geri almaz. Başarılı öğeler ve satır bazlı hatalar ayrı ayrı bildirilir; böylece yalnızca başarısız olanları yeniden deneyebilirsiniz.

{
  "items": [ /* successful TransactionDto[] */ ],
  "errors": [
    { "index": 3, "error": "Invalid currency code" }
  ]
}

{
  "deleted": 97,
  "notFound": [ "tx_old1", "tx_old2", "tx_old3" ]
}

İşlem nesnesi

Simgeler

Manilo, her yerde kullanılan özenle seçilmiş bir simge kümesi ve renk paletiyle gelir — hesaplar, kategoriler, gruplar. Kataloğu bir kez alın, önbelleğe koyun ve kaynak oluştururken tanımlayıcıları yeniden kullanın.

{
  "version": "2026.05.10",
  "library": "font-awesome-6",
  "categories": [
    {
      "id": "finance",
      "name": "Finance",
      "icons": [ "wallet", "credit-card", "piggy-bank" ]
    }
  ],
  "colors": [
    { "name": "Blue", "hex": "#4A90E2" },
    { "name": "Green", "hex": "#22C55E" }
  ]
}

Sürümleme

• v1 içinde kırıcı değişiklik yok. Yalnızca yeni uç noktalar, yeni isteğe bağlı alanlar ve yeni enum değerleri ekleyeceğiz. Bir alanın türü, null olabilirliği veya zorunluluğu değişmeyecek.
• Yeni enum değerleri kırıcı değildir. Bilinmeyen type, source veya action değerlerini çökmek yerine "gösterme" olarak ele alın — ürün büyüdükçe bunları ekleyeceğiz.
• Tarih sürümlü kırıcı değişiklikler (gerekirse) /api/v2/ altında yayımlanacak; en az 6 ay boyunca paralel kullanılabilirlik ve v1 yanıtlarında bir kullanımdan kaldırma başlığı ile birlikte.

Destek

Bir hata mı buldunuz, bir uç nokta mı istiyorsunuz ya da belgelenmemiş bir şeyle mi karşılaştınız? Yardım merkezini açın ya da şuraya e-posta gönderin: support@manilo.app — bir sorun bildirirken lütfen istek kimliğini (yanıttaki X-Request-Id başlığında yer alır) ekleyin.

Güvenlik açısından hassas bildirimler için (belirteç sızıntısı, izin atlatma, yetkisiz okuma) şu adrese yazın: security@manilo.app.