API, iki programın birbiriyle konuşma yoludur. Bir API anahtarı oluşturup yazılımcınıza verdiğinizde, web siteniz ya da kullandığınız başka bir program OKZEN CARİ’deki bilgilerinize bu anahtarla bağlanır: ör. sitenizden gelen siparişte müşteriyi ekler ve borcunu yazar, ürün fiyatlarını ve stoğu okur. Anahtar bir şifre gibidir; program yalnız sizin seçtiğiniz izinlerle çalışır ve yaptığı her kayıt İşlem geçmişi’ne yazılır. Bu bölümü kullanmıyorsanız hiçbir şey yapmanız gerekmez.
Anahtar oluşturma (işletme sahibi)
- Menüden Ayarlar’ı açın. İşletme sekmesinin altındaki Gelişmiş bölümünü açıp API anahtarları’na basın. İlk anahtarı oluşturduktan sonra Ayarlar’ın üstünde API sekmesi de çıkar.
- Anahtar oluştur’a basın. Anahtarın adı’na anahtarı hangi programın kullanacağını yazın (ör. “Web sitem”); listede ve işlem geçmişinde bu adla görünür.
- İzinler’de programın neye ulaşacağını seçin: Müşteriler ve tedarikçiler, Ürünler, Stok, Faturalar ve Kasa için Okuma ya da Yazma. Yalnız gerekenleri işaretleyin; ör. bir e-ticaret sitesi için müşterilerde yazma, ürünlerde ve stokta okuma yeter.
- Şifreniz’e panele girerken kullandığınız şifreyi yazın; iki adımlı doğrulama açıksa İki adımlı doğrulama kodu da sorulur. Sonra Anahtarı oluştur’a basın.
- Açılan kutuda anahtar yalnız bu bir kez gösterilir: Kopyala’ya basıp yazılımcınıza güvenli bir yoldan iletin. Sayfayı yenilediğinizde anahtar bir daha görünmez; kaybederseniz o anahtarı iptal edip yenisini oluşturursunuz.
İzinler: program neyi görür, neyi yazar?
| Müşteriler ve tedarikçiler | Okuma: kişiler, hesap hareketleri ve bakiyeler. Yazma: kişi ekleme ve düzenleme; veresiye yazma, ödeme alma, mal alma ve ödeme yapma (paneldeki Veresiye yaz, Ödeme al, Mal al, Ödeme yap ile aynı kayıt, aynı kurallar). |
|---|---|
| Ürünler | Okuma: ürünler ve satış fiyatları (alış fiyatı hariç). Yazma: ürün ekleme ve düzenleme (ad, fiyat, barkod). Stok miktarı buradan değişmez. |
| Stok | Okuma: stok miktarları; birden çok deponuz varsa depo depo. |
| Faturalar | Okuma: satış ve alış faturaları, satırları ve e-Arşiv / e-Fatura durumu. |
| Kasa | Okuma: kasa ve banka hesapları, hareketleri. Yazma: programın yazdığı ödemeyi kasaya da işleme. |
İki ek izin hassastır ve hiçbir zaman kendiliğinden işaretli gelmez: Veresiye limitini aşmayı onaylama (müşterinin veresiye limiti dolmuşsa program yine de yazabilir; sizin onayınız sayılır) ve Alış fiyatı (maliyet) (ürünün son alış fiyatı da programa gider). Gerekmiyorsa işaretlemeyin.
Fatura oluşturma, stok hareketi yazma ve bildirim (webhook) izinleri panelde “yakında” olarak yazar; bugün API ile fatura kesilmez.
Anahtarlar listesi ve iptal
- Her anahtarın satırında adı, izinleri ve Son kullanım zamanı (hiç kullanılmadıysa “Henüz kullanılmadı”) yazar. Anahtarın kendisi listede görünmez, yalnız ilk birkaç harfi durur.
- Satırdaki ⋯ menüsü izinlerin tam listesini ve İptal et’i gösterir. İptal geri alınamaz: o anahtarı kullanan program hemen bağlantısını kaybeder. Gerekirse yeni anahtar oluşturup programa verirsiniz.
- İptal ettikleriniz İptal edilen anahtarlar bölümünde iptal tarihiyle durur.
- Şifrenizi değiştirdiğinizde ya da Güvenlik’te Diğer tüm cihazlardan çıkış yap’a bastığınızda bütün anahtarlar güvenliğiniz için kendiliğinden iptal olur; listede nedeni yazar. Bağlantıyı sürdürmek için yeni anahtar oluşturup yazılımcınıza verin.
- Programın API ile yaptığı her kayıt İşlem geçmişi’nde “API: anahtarın adı” olarak görünür. Anahtarın oluşturulması ve iptali de işlem geçmişine yazılır; anahtarın kendisi hiçbir yere yazılmaz.
Güvenlik: anahtarı şifre gibi saklayın
- Anahtarı yalnız işi yapacak yazılımcıya verin; e-postada, mesaj gruplarında ya da ekran görüntüsünde paylaşmayın.
- Anahtar web sayfasının içine ya da telefon uygulamasına gömülmez; yalnız sitenizin sunucusunda saklanır. Tarayıcıdan gelen istek kabul edilmez.
- Her program için ayrı anahtar oluşturun; biri sızarsa yalnız onu iptal edersiniz.
- Anahtarın başkasının eline geçtiğinden şüpheleniyorsanız hemen İptal et’e basın, sonra yenisini oluşturun.
- Yazılımcınızla çalışmayı bıraktıysanız ya da program artık kullanılmıyorsa anahtarını iptal edin.
Yazılımcınız için
Ayrıntılı Türkçe belge panelde, API belgesi düğmesinin arkasındadır: panel.okzencari.com/api_belgesi.php. Bu sayfa giriş gerektirir: işletme sahibinin hesabıyla açılır (personel ve giriş yapmamış kişi açamaz). Yazılımcınız giriş yapamıyorsa belgeyi siz açıp paylaşabilir ya da aşağıdaki makine okunur belgeyi verebilirsiniz.
| Taban adres | https://panel.okzencari.com/api/v1 (yalnız HTTPS, JSON, UTF-8) |
|---|---|
| Kimlik | Her istekte “Authorization: Bearer <anahtar>” başlığı (bu başlığı düşüren sunucular için “X-Api-Key” de olur). Sunucudan sunucuya kullanılır; tarayıcıdan çapraz köken (CORS) isteği kabul edilmez. |
| Belge (OpenAPI 3) | https://panel.okzencari.com/api/v1/openapi.json — giriş istemez; Swagger gibi araçlarla açılır. |
| Okuma uçları | GET /me (bağlantı denemesi), /customers, /suppliers, /contacts/{id}, /contacts/{id}/balance, /contacts/{id}/transactions, /products, /products/{id}, /products/{id}/stock, /stock, /invoices, /invoices/{id}, /cash-accounts, /cash-accounts/{id}/transactions |
| Yazma uçları | POST /contacts (kişi ekle), POST veya PATCH /contacts/{id}, POST /contacts/{id}/transactions (veresiye, ödeme, mal alma, ödeme yapma; Idempotency-Key başlığı zorunlu, aynı istek iki kez kaydedilmez), POST /products, POST veya PATCH /products/{id} |
| Yakında | Fatura oluşturma, stok hareketi yazma, bildirimler (webhook). |
| Sınırlar | Anahtar başına dakikada 60, saatte 2.000 istek (aşılınca 429 ve Retry-After). Sayfa başına en çok 200 kayıt; eşitleme için updated_since. Hatalar Türkçe açıklamalı JSON döner. |
Bölüm paketinizde açık değilse ilgili uçlar çalışmaz (ör. ürünler bölümü kapalıysa ürün uçları). Üyelik süreniz dolmuşsa program okumaya devam eder ama yazamaz.
Sık sorulan sorular
Personelim anahtar oluşturabilir mi?
Hayır. API anahtarlarını yalnız işletme sahibi oluşturur ve iptal eder; personel bu sayfayı ve API belgesini açamaz. Oluştururken şifreniz (iki adımlı doğrulama açıksa kodu da) her seferinde yeniden sorulur.
Anahtarın süresi dolar mı?
Anahtarın bir bitiş tarihi yoktur; siz İptal et diyene kadar ya da şifrenizi değiştirene veya Diğer tüm cihazlardan çıkış yap’a basana kadar çalışır. Üyelik süreniz dolarsa anahtarlar bilgilerinizi okumaya devam eder ama kayıt yazamaz; kullanılmayan anahtarı yine iptal edebilirsiniz.
Anahtarı kaybettim, tekrar görebilir miyim?
Hayır; anahtar güvenliğiniz için yalnız oluşturulduğu an bir kez gösterilir ve panelde saklanmaz. Eskisini iptal edip yeni bir anahtar oluşturun, yazılımcınıza yenisini verin.
Kaç anahtar oluşturabilirim?
Aynı anda en çok 10 etkin anahtar olabilir. Kullanılmayanı iptal edince yenisine yer açılır.
Program veresiye limitini aşabilir mi?
Program paneldeki kurallarla çalışır: kara listedeki müşteriye hiç veresiye yazamaz, limiti dolan müşteriye de yazamaz. Limit aşımını yalnız anahtara Veresiye limitini aşmayı onaylama izni verdiyseniz ve program bunu açıkça istediğinde yazar; bu kayıt işlem geçmişine sizin onayınız olarak geçer.
API ile fatura kesilir mi?
Bugün hayır. Program faturaları okuyabilir; fatura oluşturma panelde “yakında” olarak yazar. Trendyol ve WooCommerce siparişleri için hazır bağlantı: Trendyol ve WooCommerce entegrasyonu.
İpuçları
- Her programa ayrı, yalnız gereken izinleri olan bir anahtar verin.
- Arada bir listeye bakın: uzun süredir “Henüz kullanılmadı” ya da eski bir son kullanım görünen anahtarı iptal edin.