Cari Plus API Dokümantasyonu

Cari Plus nedir?

Cari Plus, işletmelerin cari hesaplarını, ürün ve stoklarını, satış ve giderlerini, tahsilat/ödemelerini ve e-belge süreçlerini (e-Fatura, e-Arşiv, e-İrsaliye) tek yerden yönettiği bir ön muhasebe ve işletme yönetimi uygulamasıdır.

API ile neler yapılabilir?

API, normalde panelde elle yaptığınız işlerin bir bölümünü kendi yazılımınızdan yapmanızı sağlar. Firmanızın verisine, panelin ekranlarından geçmeden erişirsiniz.

Bugün açık olan yüzeyle şunlar yapılabilir:

• Ürün ve stok senkronu. Ürünleri ve varyasyonlarını oluşturup güncelleyebilir, depo bazında stok durumunu okuyabilir ve stok hareketi yazabilirsiniz. Kendi e-ticaret siteniz veya pazaryeri panelinizle Cari Plus stoğunu aynı tutmak bu uçlarla yapılır. Bir ürünü vitrininizde gizlemek için is_web_visible alanını kullanın — ürünü Cari Plus'ta pasife almadan yalnız vitrin dışında tutar.

• Depo yönetimi. Depo/şube kayıtlarını ve depo içi raf/göz (lokasyon) hiyerarşisini oluşturup güncelleyebilir, arşivleyip geri yükleyebilirsiniz — stok hareketi yazarken zorunlu olan warehouse_id'yi bu uçlardan öğrenirsiniz.

• Cari hesap senkronu. Müşteri ve tedarikçi kayıtlarını oluşturabilir, güncelleyebilir, listeleyebilirsiniz. CRM'iniz veya sipariş sisteminiz yeni bir müşteri açtığında aynı kaydı Cari Plus'ta da açabilirsiniz.

• Satış faturası ve yaşam döngüsü. Taslak satış faturası oluşturabilir, güncelleyebilir, silebilir; ardından kesebilir (stok düşer, cari bakiyeye girer), iptal edebilir (stok geri gelir), iade damgası basabilir ve arşivleyip geri yükleyebilirsiniz. Kesim öncesi stok yeterliliğini yazma yapmadan önizleyen ayrı bir uç vardır.

• İhracat faturası ve serbest meslek makbuzu. Faturanın senaryosunu export ya da smm seçip teslim şekli, taşıma tipi, navlun/sigorta/FOB bedelleri ve kalem bazında GTİP/kap/menşe bilgisini yazabilirsiniz; belge aynı e-belge uçlarından gider, ayrı bir uç öğrenmeniz gerekmez. Perakende satış bu yüzeyin kapsamı DIŞINDADIR (kendi akışı vardır) ve API'den yazılmak istenirse 422 alır — bkz. Satış faturaları.

• E-belge gönderimi ve iptali. Faturayı e-Fatura/e-Arşiv olarak GİB'e gönderebilir, önce taslak açıp sonra gönderebilir, belgenin durumunu izleyebilir, PDF ve XML'ini indirebilirsiniz. Bu uçlar kendi yetkisini taşır (edocuments:read / edocuments:write) — sebebi aşağıda. Gönderim geri alınamaz, ama e-belgesi kesilmiş fatura artık iptal edilebilir: iptal ucu o durumda edocuments:write yetkisini ve Idempotency-Key başlığını ister. Bir uyarıyla: e-Fatura'da iptal karşı tarafın onayına bağlı olduğu için yalnız bir taleptir — 200 almanız belgenin GİB'de iptal olduğu anlamına gelmez, bkz. Satış faturaları.

• Tahsilat kaydı. Kesilen faturanın nakit veya havale tahsilatını kaydedebilir, düzeltebilir ve geri alabilirsiniz; firmanın kasa/banka hesaplarını da bu uçlardan listelersiniz. Bir tahsilat üç yere birden yazar — kasa/banka bakiyesine, faturaya ve cari hesaba — ve silindiğinde üçü de geri alınır. Bu uçlar kendi yetkisini taşır (collections:read / collections:write), invoices:* değil: sebebi para. Ayrıntı, fazla tahsilat ve nakit sınırı kuralları için bkz. Tahsilat.

• Gider kaydı ve yaşam döngüsü. Tedarikçi faturası, elektrik faturası, kırtasiye alımı gibi giderleri oluşturabilir, güncelleyebilir, listeleyebilir; ardından kesebilir (gider tedarikçi borcuna girer) ve iptal edebilirsiniz (borçtan çıkar); arşivleyip geri de yükleyebilirsiniz. Gider kategorilerini de bu uçlardan listelersiniz. POST her zaman taslak üretir ve DELETE arşivler, silmez — arşivlenen gider okunmaya devam eder. İki uyarıyla: gideri "mal alımı" olarak işaretlemek (expense_kind: goods_purchase) stok miktarını değiştirmez — envanteri artırmak için ayrıca stok hareketi yazmanız gerekir; ve kesim tek başına gideri "ödendi" yapmaz — durum issuedde kalır, kalanı kapatan bir ödeme kaydı gerekir. Bkz. Giderler.

• Gider ödemesi kaydı. Kesilmiş bir giderin nakit veya havale ödemesini kaydedebilir, düzeltebilir ve geri alabilirsiniz; kalanı aşan bir ödemenin fazlası tedarikçi carisine avans olarak yazılır. Bu uçlar kendi yetkisini taşır (expense_payments:read / expense_payments:write), expenses:* değil — sebebi tahsilattakiyle aynı: kasadan para çıkar. Bkz. Gider ödemeleri.

• Teklif kaydı. Taslak teklif oluşturabilir, güncelleyebilir, listeleyebilir, arşivleyip geri yükleyebilirsiniz; kalemin bağlanabileceği hizmet kataloğunu da (GET /v1/services) buradan listelersiniz. POST her zaman taslak üretir ve teklifi onaya göndermek, onaylamak, reddetmek ya da faturaya dönüştürmek bu sürümde yoktur — bugün yalnız panelden yapılabilir; status yine de okunur, siz tetikleyemeseniz de panelden ya da müşterinin kendi kararıyla ilerleyebilir. reserve_stock bayrağı stoğun ne zaman hareket edeceğini belirler (rezerve mi, doğrudan mı düşer); bu API'den yazılan bir teklif, bayrak ne olursa olsun, tek başına hiçbir stok hareketi üretmez — teklifler bu yüzden Stok'ta yalnız reserved alanı üzerinden görünür. Bkz. Teklifler.

• Gelen e-faturaları çekme, kabul/red, PDF/XML. GİB'in gelen kutusunu senkronlayıp yeni gider(ler) üretebilir; belirli koşulları sağlayan (e-Fatura + TİCARİ FATURA profili + daha önce yanıtlanmamış) faturalara GİB'e kabul/red uygulama yanıtı gönderebilir, PDF/XML indirebilir ve "işlendi" olarak işaretleyebilirsiniz. Bkz. Giderler → Gelen e-faturalar.

• Kendi raporlarınız. Cari ve ürün verisini çekip kendi tarafınızda raporlayabilir, veri ambarınıza aktarabilirsiniz. Listelerin tamamı sayfalıdır ve son değişiklik zamanına göre artımlı çekilebilir — her seferinde her şeyi indirmeniz gerekmez.

API panelin yerini almaz; onun yanında çalışan, daha dar kapsamlı bir yüzeydir. Bir anahtar yalnız bağlı olduğu firmanın verisini görür ve yalnız kendisine verilen yetkiler kadarını yapabilir.

Taban adres

https://api.cariplus.com.tr/v1

Panelin alan adından ayrıdır ve yalnız /v1/* altındaki uçları servis eder; başka bir yol 404 not_found döner.

Ayakta olduğunu doğrulamak için kimlik doğrulama gerekmez:

curl -s https://api.cariplus.com.tr/v1/ping
# {"data":{"status":"ok","version":"v1"}}

Hızlı başlangıç

1. API anahtarı oluşturun

Panelde Ayarlar → API Anahtarları sekmesinden yeni bir anahtar oluşturun. client_secret yalnız oluşturma anında bir kez gösterilir — o ekranı kapatmadan kaydedin.

2. Token alın

curl -s -X POST https://api.cariplus.com.tr/v1/auth/token \
  -d "client_id=<client_id>" \
  -d "client_secret=<client_secret>"

{
  "data": {
    "access_token": "9f3c...",
    "refresh_token": "a1b2...",
    "expires_in": 3600,
    "token_type": "Bearer"
  }
}

3. İsteklerinizi token ile gönderin

curl -s https://api.cariplus.com.tr/v1/me \
  -H "Authorization: Bearer <access_token>"

/v1/me anahtarın hangi firmaya bağlı olduğunu ve hangi yetkilere sahip olduğunu döner:

{
  "data": {
    "company": {"id": 34, "name": "Örnek A.Ş."},
    "credential": {"id": 12, "name": "Muhasebe Entegrasyonu", "client_id": "..."},
    "scopes": ["current_accounts:read", "products:read"]
  }
}

Token ömrü, yenileme ve IP kısıtlaması için bkz. Kimlik doğrulama.

Modüller

Modül	Uçlar	Yetkiler
Cari hesaplar	/v1/current-accounts/*	current_accounts:read, current_accounts:write
Stok — Ürünler	/v1/products/*	products:read, products:write
Stok — Varyasyonlar	/v1/products/{id}/variations, /v1/variations/*	products:read, products:write
Stok — Stok hareketleri	/v1/products/{id}/stock, /stock-movements	stock:read, stock:write
Stok — Depolar	/v1/warehouses/*, /v1/warehouse-locations/*	warehouses:read, warehouses:write
Satış faturaları	/v1/sales-invoices/*	invoices:read, invoices:write
E-Belge	/v1/sales-invoices/{id}/edocument-*	edocuments:read, edocuments:write
Tahsilat	/v1/invoice-collections/*, /v1/company-accounts	collections:read, collections:write
Giderler	/v1/expenses/*, /v1/expense-categories	expenses:read, expenses:write
Gider ödemeleri	/v1/expense-payments/*	expense_payments:read, expense_payments:write
Teklifler	/v1/quotes/*	quotes:read, quotes:write
Teklifler → Hizmetler	/v1/services	services:read

Stok kendi yetkisini taşır: ürün oluşturabilen bir anahtar, stock:write verilmedikçe stok hareketi yazamaz. Depo yönetimi de kendi yetkisini taşır (warehouses:*) — ne ürün ne stok yetkisi yeterlidir. Satış faturası da kendi yetkisini taşır (invoices:*); POST YALNIZ taslak üretir, durumu değiştiren her fiil (kesim/iptal/iade/arşiv) AYRI bir uçtur ve scope'un ÜZERİNE ayrı bir izin ister — bkz. Satış faturaları.

E-belge gönderimi de ayrı bir yetki çiftidir (edocuments:read / edocuments:write), invoices:* DEĞİL. Sebebi para: GİB'e belge göndermek firmanın e-belge kontörünü harcar. Stok senkronu yapsın diye invoices:write verdiğiniz bir anahtarın, siz istemeden firmanın e-belge kredisini harcayabilmesi doğru olmazdı. Bu yüzden anahtara e-belge yetkisini yalnız gerçekten belge göndermesini istediğinizde verin — durumu izlemek, PDF/XML indirmek için edocuments:read tek başına yeter.

Aynı gerekçe iptalde de geçerlidir: faturanın e-belgesi varsa POST /v1/sales-invoices/{id}/cancel de edocuments:write ister. E-belgesi olmayan faturada bu uç eskisi gibi yalnız invoices:write ile çalışır.

Tahsilat da ayrı bir yetki çiftidir (collections:read / collections:write), invoices:* DEĞİL. Sebebi yine para: bir tahsilat kaydı firmanın kasasına/bankasına para yazar ve müşterinin cari alacağını düşürür. Stok senkronu yapsın diye invoices:write verdiğiniz bir anahtarın firmanın kasasına hareket yazabilmesi doğru olmazdı. collections:read kasa/banka hesap listesini de kapsar — company_account_id olmadan tahsilat yapılamadığı için ikisi tek bir yetenektir.

Giderler de kendi yetki çiftini taşır (expenses:read / expenses:write). expenses:read gider kategorisi listesini de kapsar — expense_category_id gider dışında hiçbir yerde kullanılmadığı için ikisi tek bir yetenektir. Gideri kesmek, iptal etmek, arşivlemek ve arşivden geri yüklemek scope'un üzerine ayrı ayrı panel izni ister — yalnız kesme yetkisi verilmiş bir kullanıcı iptal edemez.

Gider ödemesi de ayrı bir yetki çiftidir (expense_payments:read / expense_payments:write), expenses:* DEĞİL — sebebi tahsilattakiyle aynı: bir ödeme kaydı kasadan/bankadan para çıkarır. Bkz. Gider ödemeleri.

Teklifler de kendi yetki çiftini taşır (quotes:read / quotes:write). Kalemin bağlanabileceği hizmet kataloğu (GET /v1/services) bu çiftin parçası DEĞİLDİR — kendi services:read scope'una sahiptir; hizmetler panelde kendi izin ailesine bağlıdır ve hem üründen hem tekliften tamamen ayrı bir modüldür. POST her zaman taslak üretir; teklifi onaya göndermek, onaylamak, reddetmek ve faturaya dönüştürmek bu sürümde yoktur (yukarıya bakın). Bkz. Teklifler.

Sürüm politikası

Taban yol sürüm taşır (/v1) ve şu sözü verir:

• Yeni alan eklenebilir. Yanıtlara zamanla yeni alanlar eklenir; entegrasyonunuz tanımadığı alanları yok saymalıdır.

• Alan kaldırılmaz, bir alanın anlamı değiştirilmez. Böyle bir değişiklik gerekirse yeni bir sürüm (/v2) açılır ve /v1 çalışmaya devam eder.