Qando API'si nedir?
Qando Public API'si, kendi yazılımınızı Qando'ya bağlamanızı sağlayan bir REST arayüzüdür. Siparişlerinizi kendi muhasebe programınıza aktarabilir, ürün ve stoklarınızı kendi ERP'nizden besleyebilirsiniz. Tüm istekler HTTPS üzerinden yapılır, istek ve yanıt gövdeleri JSON biçimindedir.
Temel adres:
``https://api.qando.com.tr/api/v1``
Adım 1 — Panelden API anahtarı üretin
API erişimi kullanıcı parolanızla değil, API anahtarıyla yapılır. Bunun sebebi pratik: bir entegrasyona panel parolanızı gömmek, parolayı değiştirdiğinizde entegrasyonun durması ve sızıntı hâlinde hesabın tamamının açılması demektir. API anahtarı ise tek başına iptal edilebilir ve yalnızca verdiğiniz yetkilerle sınırlıdır.
Panelde Ayarlar › API & Webhook ekranına girin, Yeni Anahtar'a basın:
1. Anahtara bir ad verin (örn. "Logo Muhasebe entegrasyonu") — ileride hangisini iptal edeceğinizi bilmek için. 2. Yalnızca gereken yetkileri seçin. 3. Oluştur'a bastığınızda anahtar bir kez gösterilir.
> Önemli: Anahtarın düz metnini saklamıyoruz, yalnızca özetini tutuyoruz. Ekranı > kapattıktan sonra size tekrar gösteremeyiz — kaybederseniz yenisini üretirsiniz. Bu > kasıtlıdır: saklanan bir sır, sızabilen bir sırdır.
Adım 2 — İstek atın
Anahtarı Authorization başlığında gönderin. Başka başlık gerekmez; hangi çalışma alanı adına işlem yaptığınızı anahtarın kendisi belirler.
``GET https://api.qando.com.tr/api/v1/orders Authorization: Bearer qnd_live_xxxxxxxxxxxxxxxx``
Örnek yanıt:
``{ "data": [ { "id": "9f1c...", "extOrderId": "TY-123456789", "status": "SHIPPED", "customerName": "Ayşe Yılmaz", "totalAmountMinor": 24990, "currency": "TRY", "orderDate": "2026-08-14T09:12:00.000Z" } ], "nextCursor": "9f1c..." }``
Yetki kapsamları
Her anahtar yalnızca kendisine verilen kapsamlarda çalışır. Kapsamı olmayan bir uca istek atarsanız 403 alırsınız.
| Kapsam | Ne yapar | |---|---| | ORDERS_READ | Siparişleri okur | | ORDERS_WRITE | Sipariş günceller | | PRODUCTS_READ | Ürünleri okur | | PRODUCTS_WRITE | Ürün ekler / günceller | | STOCK_READ | Stok okur | | STOCK_WRITE | Stok günceller | | INVOICES_READ | Faturaları okur | | CUSTOMERS_READ | Cari kartları okur |
En az yetki ilkesini uygulayın: muhasebe programınıza fatura aktaracak bir anahtara stok yazma yetkisi vermeyin. Anahtar sızarsa zarar verdiğiniz yetkiyle sınırlı kalır.
Sayfalama
Liste uçları imleç (cursor) ile sayfalanır. Yanıttaki nextCursor değerini bir sonraki isteğe cursor parametresi olarak verin; null geldiğinde veri bitmiştir.
``GET /v1/orders?limit=100&cursor=9f1c...``
Sayfa numarası yerine imleç kullanılmasının sebebi: siz sayfalar arasında ilerlerken araya yeni sipariş girerse, sayfa numarasıyla ilerleyen bir okuma satır atlar. İmleç bu sorunu yaşamaz.
Artımlı okuma
Her seferinde tüm geçmişi çekmeyin. Son çalışmanızdan sonra değişenleri isteyin:
``GET /v1/orders?updatedSince=2026-08-16T00:00:00Z GET /v1/invoices?issuedSince=2026-08-16T00:00:00Z``
Para birimi ve tarih biçimleri
- Tutarlar en küçük birim (kuruş) cinsinden tam sayıdır.
24990= 249,90 TL. Kayan noktalı sayı kullanmıyoruz; finansal veride yuvarlama hatası kabul edilemez. - Tüm tarih/saat değerleri ISO 8601 (UTC) biçimindedir.
Hız limiti
Anahtar başına dakikada 600 istek. Aşarsanız 429 alırsınız; bir süre bekleyip tekrar deneyin. Limit anahtar bazlıdır — farklı işler için ayrı anahtarlar açarsanız biri diğerini etkilemez.
Hata yanıtları
| Kod | Anlamı | Ne yapmalı | |---|---|---| | 401 | Anahtar eksik, geçersiz, iptal edilmiş veya süresi dolmuş | Panelden anahtarı kontrol edin | | 403 | Anahtarda gerekli kapsam yok | Anahtara ilgili yetkiyi verin (yeni anahtar üretin) | | 429 | Hız limiti aşıldı | Bekleyip tekrar deneyin | | 400 | Girdi doğrulanamadı | Yanıttaki mesaj hangi alanın hatalı olduğunu söyler |
Sözleşme ve sürüm
Yanıt alanları bir sözleşmedir. Yeni alan eklenebilir — kodunuz bilmediği alanları yok saymalıdır. Alan çıkarma veya yeniden adlandırma kırıcı değişikliktir ve yeni bir sürüm (/v2) ile yapılır; /v1 çalışmaya devam eder.
Güvenlik notları
- Anahtarı kod deposuna koymayın, ortam değişkeninde tutun.
- Çalışan ayrıldığında ya da anahtar sızdığından şüphelendiğinizde panelden iptal edin — iptal anında geçerlidir.
- Kullanılmayan anahtarları fark edebilmek için panelde her anahtarın son kullanım tarihi gösterilir.