Kobiks - API V1 (v1.0.0)

API Hakkında

Kobiks API henüz beta aşamasındadır ve sadece seçili kullanıcıya açıktır. Eğer beta test sürecine katılmak veya API hakkındaki görüşlerinizi bizimle paylaşmak isterseniz lütfen bize destek@kobiks.com adresi üzerinden ulaşabilirsiniz.



API'yi kullanarak Kobiks veritabanına ulaşabilir ve kendi yazdığınız uygulamalar ile entegre edebilirsiniz. API vasıtasıyla Kobiks Web arayüzü ile yapılan işlemleri gerçekleştirebilirsiniz.



  • - Kobiks API geliştirmesi REST API standartlarında geliştirildi.

  • - API hizmetimizin END POINT'i https://kobiks.com/api şeklindedir.

  • - V1 END POINT'ine ulaşmak için https://kobiks.com/api/v1 adresini kullanabilirsiniz.

Doğrulama ve Giriş İşlemi

Kobiks API kimlik doğrulama için JSON Web Tokens (JWT) kullanmaktadır.


JSON Web Tokens (JWT) anahtarını Kobiks hesabınıza girdikten sonra Ayarlar/Entegrasyonlar/API seçeneğinden temin edebilirsiniz.


Access Token ile Kobiks Web arayüzü ile yapılan başlıca işlemleri gerçekleştirebilirsiniz. Lütfen bu kodu kimseyle paylaşmayınız.

Ürün Yaratma

Nitelik Tür Zorunlu Açıklama
product_name String Evet

Ürün ismi

is_new_product

String

Hayır Yeni ürün olup olmadığını belirtir. Örn 'evet' veya 'hayır'
product_variant_id

String

Hayır Eğer yeni ürünse hangi ürünün varyantı olduğunu belirtir. Format: "product_id"-"variant_id".
Örn. '98898-23332'
vat_rate

Integer

Hayır Ürünün KDV oranı.
Örn. "5", "12"
supplier_name

String

Hayır Tedarikçi ismi
Örn. "ŞAHİN" veya "fethi"
brand

String

Hayır Marka ismi
Örn. "Kısmet" veya "Beko"
categories

String

Hayır Ürünün kategorileri
Örn. "kolye" veya "kolye, bilezik"
short_desc

String

Hayır Ürünün kısa açıklaması
desc

String

Hayır Ürünün açıklaması
tags

String

Hayır Ürünün etiketleri
Örn. "tag 1" veya "tag 1, tag 2"
sku

String

Hayır Varyant stok kodu
Örn. "09-1-007"
barcode

String

Hayır Varyant barkod
Örn. "54496767"
sellable

String

Hayır Satışa açık mı? Örn. "evet" veya "hayır"
stock_enabled

String

Hayır Stok takibi yapılsın mı?
Örn. "evet" veya "hayır"
oversell

String

Hayır Depo harici satışa izin verilsin mi?
Örn. "evet" veya "hayır"
is_active

String

Hayır Ürün aktif mi?
Örn. "evet" veya "hayır"
exp_date

Date

Hayır Ürünün son kullanma tarihi
alert_at

Date

Hayır Yeniden sipariş noktası
image_url

String

Hayır Ürün fotoğraf adresi
Örn. "www.xxxxxxxx.com/images/1.jpg"
is_consign

String

Hayır Konsinye ürün mü?
Örn. "evet" veya "hayır"
external_id

Integer

Hayır İstemcinin yerel sunucusundaki ürünün yerel id'sidir. Upload işleminden sonra istemci-sunucu tarafındaki ürünlerin eşlenmesi için kullanılır.
Örn. "external_id": 1212
Hammadde Parametreleri

String

Hayır Hesabınızda varolan commodity paramtere isimleriyle değer yollanır.
Örn. "Altın" hammaddesini olsun: "Altın": "0.25 gr"
Lokasyon Parametreleri

String

Hayır Bebek adında bir lokasyon olsun. Örn. Lokasyonda ürün adetii belirtmek için:
"LO:[Bebek]": "15"
Fiyat Parametreleri

String

Hayır Oluşturulan fiyat kategorilerine göre fiyat belirtilir. Örn. Online Satış Fiyatı (TL) isimli fiyat kategorisi için fiyat
"Online Satış Fiyatı (TL)": "550"
Ürün Özellikleri Parametreleri

String

Hayır Oluşturulan ürün özelliklerine göre değer belirtilir. Örn. Online Taş Adeti isimli ürün özelliği için değer
"OZ:[Taş Adeti]": "12"

Örnek Ürün veya Varyant oluşturma işleminin cevabı:

// Varyant oluşturma
        {
            "status": "success",
            "products": [
                {
                    "operation_id": 98671,
                    "external_id": "1"
                },
                {
                    "operation_id": 98677,
                    "external_id": null
                }
            ]
        }
      

Cevapta bulunan 'status' anahtarı isteğin durumunu belirtir. 'products' ise kaydedilen ürünleri, 'operation_id' kaydedilen ürünün sunucudaki id'sini, 'external_id' parametre olarak alınan istemci ürün id'sini belirtir. Eğer external_id parametresi verilmeze cevapta o ürünün external_id'si 'null döner'


Ürün Yaratma Örnek Sorgu

curl -X POST -H "Accept: application/vnd.kobiks-api.v1+json" -H "Content-type: application/json" -H "Authorization: ACCESS_TOKEN"
https://www.kobiks.com/api/v1/api/import_products

  {
    "products":
    [
      {
      "product_name": "Demo Atkı",
      "is_new_product": "evet",
      "vat_rate": "18",
      "supplier_name": "Demo Tedariko",
      "brand": "Tedariko",
      "categories": "Aksesuar",
      "short_desc": "Yaz ve bahar günleri için hafif atkı",
      "desc": "Bu demo atkı üç renkte mevcuttur ve üzerinde Tedariko markası belirtilmektedir.",
      "tags": "Kış 2018, Aksesuar",
      "sku": "9999-1-007",
      "barcode": "54496767",
      "sellable": "Evet",
      "stock_enabled": "Evet",
      "oversell": "Evet",
      "is_active": "Evet",
      "exp_date": "2018-12-15",
      "alert_at": "2012-8-21",
      "is_consign": "Hayır",
      "external_id": "1212",
      "Perakende Satış Fiyatı (TL)": "64",
      "Demo Perakende Dolar": "16",
      "LO:[Demo Mağaza]": "85",
      "LO:[Demo Depo]" : "45",
      "Safir ": "0.11",
      "Yakut": "0",
      "OZ:[Özellik 1 İsmi]": "Kış 2018",
      "image_url": "https://s3-eu-west-1.amazonaws.com/kobikssetup/KobiksDemoImages/images/DemoAtkiMavi.jpg"
      },
      {
      "product_name": "Demo Şapka",
      "is_new_product": "hayır",
      "product_variant_id": "98889-55596",
      "vat_rate": "18",
      "supplier_name": "Demo Tedariko",
      "brand": "Tedariko",
      "categories": "Aksesuar",
      "short_desc": "%100 yün şapka",
      "desc": "Bu demo şapka, kış mevsimlerinde uzun seyahatlerde korunmak için tasarlanmıştır.",
      "tags": "Kış 2018, Aksesuar",
      "sku": "9999-2-090",
      "barcode": "54496767",
      "sellable": "Evet",
      "stock_enabled": "Evet",
      "oversell": "Evet",
      "is_active": "Evet",
      "exp_date": "2018-12-15",
      "alert_at": "2012-8-21",
      "is_consign": "Evet",
      "external_id": "1213",
      "Perakende Satış Fiyatı (TL)": "20",
      "Demo Perakende Dolar": "80",
      "LO:[Demo Mağaza]": "85",
      "LO:[Demo Depo]" : "45",
      "Safir": "0.11",
      "Yakut": "0",
      "OZ:[Özellik 1 İsmi]": "Kış 2018",
      "image_url": "https://s3-eu-west-1.amazonaws.com/kobikssetup/KobiksDemoImages/images/DemoSapkaMavi.jpg"
      }
    ]
  }
  

Ürün Güncelleme

Ürün Güncelleme, ürün yaratma etme işlemi ile aynı şekilde yapılır. Ek olarak "is_new_product" ve "product_variant_id" parametrelerinin verilmesi gerekmektedir.

Nitelik Tür Zorunlu Açıklama
is_new_product String Evet

Yeni ürün olup olmadığını belirtir. Ürün güncelleme işleminde bu parametre 'Hayır' olmalıdır.

product_variant_id

String

Evet

Format: "product_id"-"variant_id". Örn. 98898-23332

Bu parametre eksik veya hatalı verilirse sunucu hata üretir. Hata mesajının metni e-posta hesabına gönderilir.

Örnek Ürün veya Varyant güncelleme işleminin cevabı:

// Varyant güncelleme
        {
            "status": "success",
            "products": [
                {
                    "operation_id": 98671,
                    "external_id": "1"
                },
                {
                    "operation_id": 98677,
                    "external_id": null
                }
            ]
        }
      

Ürünleri Güncelleme Örnek Sorgu

curl -X POST -H "Accept: application/vnd.kobiks-api.v1+json" -H "Content-type: application/json" -H "Authorization: ACCESS_TOKEN"
https://www.kobiks.com/api/v1/api/import_products

  {
    "products":
    [
      {
      "product_name": "Demo Atkı",
      "is_new_product": "hayır",
      "product_variant_id": "98889-55596",
      "vat_rate": "18",
      "supplier_name": "Demo Tedariko",
      "brand": "Tedariko",
      "categories": "Aksesuar, Yüzük",
      "short_desc": "Yaz ve bahar günleri için hafif atkı",
      "desc": "Bu demo atkı üç renkte mevcuttur ve üzerinde Tedariko markası belirtilmektedir.",
      "tags": "Kış 2018"
      }
    ]
  }
  

Ürün veya Varyant Silme İşlemi

Ürün veya varyant silme işlemi için aşağıdaki parametreler gerekmektedir. "variant_id" verilirse sadece varyant silinir.

DİKKAT: "variant_id" parametresi verilmez ise sunucu ürünü tüm varyantları ile birlikte silmeye çalışır. Silinmek istenen ürün veya varyant ile ilişkili geçmişte bir işlem (alış, satış, vs.) yapılmış ise, silinmesine izin verilmez.

Paramatre Tür Zorunlu Açıklama
variant_id Integer Hayır

Ürün varyant id.

Örnek Ürün veya Varyant silme işleminin cevabı:

// Varyant silme
    {
      "variant_id": 98646,
      "name": " mavi beyaz ",
      "status": "ok"
    }


        // Product silme
    {
        "product_id": 81872,
        "product_name": " mavi beyaz",
        "status": "ok"
    }
      

Ürün veya Varyant Silme

curl -X DELETE -H "Accept: application/vnd.kobiks-api.v1+json" -H "Content-type: application/json" -H "Authorization: ACCESS_TOKEN"
localhost:3000/api/v1/api/products/PRODUCTID

  {
    "variant_id": variant_id
  }
  

Müşteri Yaratma

Nitelik Tür Zorunlu Açıklama
customer_name String Evet

İsim veya Marka

kobiks_no

Integer

Hayır Müşterinin kobiks id'si. Müşteri güncellemek için kullanılır
trade_name

String

Hayır Müşterinin ticari ünvanı
tax_no

Integer

Hayır Müşterinin vergi numarası, 10 veya 11 haneli olmalı
tax_office

String

Hayır Müşterinin kayıtlı olduğu vergi dairesi
code

String

Hayır Müşterinin cari kodu
discount_rate

Integer

Hayır Müşterinin yüzdelik indirim oranı
tax_rate

Integer

Hayır Müşterinin yüzdelik vergi oranı
phone

Tel

Hayır Müşterinin telefon numarası
fax

Tel

Hayır Müşterinin fax numarası
email

Email

Hayır Müşterinin email adresi
web

String

Hayır Müşterinin web adresi
notes

String

Hayır Müşteri hakkındaki notlar
address_name

String

Hayır Müşterinin adres ismi
address1

String

Hayır Müşterinin 1. adres satırı
address2

String

Hayır Müşterinin 2. adres satırı
city

String

Hayır Müşterinin adresinin bulunduğu şehir
zip

String

Hayır Müşterinin adresinin posta kodu
country

String

Hayır Müşterinin adresinin bulunduğu ülke
address_phone

Tel

Hayır Müşterinin adresinin telefon numarası
address_fax

Tel

Hayır Müşterinin adresinin fax numarası
address_email

String

Hayır Müşterinin adresinin mail adresi
sex

String

Hayır Müşterinin cinsiyeti
external_id

Integer

Hayır İstemcinin yerel sunucusundaki müşterinin yerel id'sidir. Upload işleminden sonra istemci-sunucu tarafındaki müşterilerin eşlenmesi için kullanılır.
Örn. "external_id": 1212
Müşteri Özellikleri

String

Hayır Müşterini özellikleri parametre anahtarının başına [OZ]:[Özellik] şeklinde yazılır. Kobiks varsayılan olarak 'Evlilik Tarihi' ve 'Doğum Tarihi' özelliklerini oluşturur. Daha fazla özellik kobiks.com'dan oluşturulabilir veya silinebilir.
Örn. "OZ:[Evlilik Tarihi]": ""

Örnek Müşteri oluşturma işleminin cevabı:

{
        "status": "success",
        "customers": [
            {
                "operation_id": 56299,
                "external_id": 488
            },
            {
                "operation_id": 56300,
                "external_id": 8988
            },
            {
                "operation_id": 56301,
                "external_id": null
            },
            {
                "operation_id": 56303,
                "external_id": null
            }
        ]
    }

Cevapta bulunan 'status' anahtarı isteğin durumunu belirtir. 'customers' ise kaydedilen müşterileri, 'operation_id' kaydedilen müşterinin sunucudaki id'sini, 'external_id' parametre olarak alınan istemci müşteri id'sini belirtir. Eğer external_id parametresi verilmeze cevapta o müşteri external_id'si 'null döner'


Müşteri Yaratma Örnek Sorgu

curl -X POST -H "Accept: application/vnd.kobiks-api.v1+json" -H "Content-type: application/json" -H "Authorization: ACCESS_TOKEN"
https://www.kobiks.com/api/v1/api/import_customers

  {
    "customers":
    [
      {
      "customer_name": "Demo Musteriko",
      "trade_name": "Demo Müşteri Ltd. Şti.",
      "tax_no": "54615634341",
      "tax_office": "Demo Vergi Dairesi",
      "code": "DEMOMUST",
      "discount_rate": 10.0,
      "tax_rate": 12,
      "phone": "(212) 444-1891",
      "fax": "(212) 444-1892",
      "email": "demomusteri@demomusteri.com",
      "web": "http://www.demomusteri.com",
      "notes": "En iyi beş müşteriden biri",
      "address_name": "Demo Müşteriko Merkez Ofis",
      "address1": "Demo Müşteri Sok No 4",
      "address2": "Karaköy",
      "city": "İstanbul",
      "zip": "34000",
      "country": "Türkiye",
      "address_phone": "(212) 444-1812",
      "address_fax": "(212) 444-1813",
      "address_email": "demotedarikci@demotedarikci.com",
      "sex": "Belirtilmemiş",
      "external_id": 250,
      "OZ:[Doğum Tarihi] (Opsiyonel)": "",
      "OZ:[Evlilik Tarihi] (Opsiyonel)": ""
      },
      {
      "customer_name": "Demo Musteri",
      "trade_name": "Demo Müşteri Ltd.",
      "tax_no": "45166544341",
      "tax_office": "Demo Vergi Dairesi",
      "code": "DEMOMUST",
      "discount_rate": 0.0,
      "tax_rate": 18,
      "phone": "(212) 444-9118",
      "fax": "(212) 444-9281",
      "email": "musteri@musteri.com",
      "web": "http://www.musteri.com",
      "address_name": "Demo Müşteri Merkez Ofis",
      "address1": "Demo Müşteri Sok No 5",
      "address2": "Kadıköy",
      "city": "İstanbul",
      "zip": "34000",
      "country": "Türkiye",
      "address_phone": "(212) 444-8558",
      "address_fax": "(212) 444-8559",
      "address_email": "demomust@demomust.com",
      "sex": "Belirtilmemiş",
      "external_id": 250,
      "OZ:[Doğum Tarihi] (Opsiyonel)": "",
      "OZ:[Evlilik Tarihi] (Opsiyonel)": ""
      }
    ]
  }
  

Müşteri Güncelleme

Müşteri Güncelleme, müşteri yaratma etme işlemi ile aynı şekilde yapılır. Kritik olan kobiks_no parametresinin doğru verilmiş olmasıdır.

Müşterinin bir adresi güncellenecek ise ilgili 'address_name' parametresi verilmelidir.



Örnek Müşteri güncelleme işleminin cevabı:

{
        "status": "success",
        "customers": [
            {
                "operation_id": 56299,
                "external_id": 488
            }
        ]
    }

Cevapta bulunan 'status' anahtarı isteğin durumunu belirtir. 'customers' ise kaydedilen müşterileri, 'operation_id' kaydedilen müşterinin sunucudaki id'sini, 'external_id' parametre olarak alınan istemci müşteri id'sini belirtir. Eğer external_id parametresi verilmeze cevapta o müşteri external_id'si 'null döner'


Müşterileri Güncelleme Örnek Sorgu

curl -X POST -H "Accept: application/vnd.kobiks-api.v1+json" -H "Content-type: application/json" -H "Authorization: ACCESS_TOKEN"
https://www.kobiks.com/api/v1/api/import_customers

  {
    "customers":
    [
      {
      "customer_name": "Müşteri Demo",
      "kobiks_no": 56299
      }
    ]
  }
  

Müşteri Silme

Müşteri silmek için müşterinin id'sinin verilmiş olması gerekir.

Örnek Müşteri güncelleme işleminin cevabı:


      {
        "customers": [
        {
          "customer_name": "Shoplatitude.com.tr",
          "kobiks_no": 56299
        }
        ]
      }

Müşteri Silme

curl -X DELETE -H "Accept: application/vnd.kobiks-api.v1+json" -H "Content-type: application/json" -H "Authorization: ACCESS_TOKEN"
localhost:3000/api/v1/api/customers/CUSTOMERID

Perakende Satış Faturası Yaratma

Nitelik Tür Zorunlu Açıklama
orderable_id String Evet

Ürün kobiks no. Ürünün product ve varyant id'lerinin yanyana eklenmeleriyle oluşur.
Örn. product_id: 10, variant_id: 123 => orderable_id: "10-123"

customer

String

Evet Müşteri adı. İsmi verilen müşterinin sistemde kayıtlı olması gereklidir.
cust_code

String

Hayır Müşteri Kodu
quantity

Integer

Evet Faturadaki Ürün adeti.
price_category

String

Evet Fiyat kategorisi. Belirtilen fiyat kategorisinin sistemde bulunması gerekir.
price

Integer

Evet Ürünün birin fiyatı
fx_rate

Integer

Hayır Döviz kuru
discount_rate

Integer

Hayır İndirim Oranı (%)
discount_amount

Integer

Hayır İndirim Miktarı
tax_rate

Integer

Hayır KDV Oranı (%)
store

String

Hayır Şube. Belirtilen şubenın sistemde kayıtlı olması gereklidir.
invoice_date

Date

Hayır Fatura Tarihi
user

String

Hayır Sorumlu Kişi E-Posta
notes

String

Hayır Fatura notları
invoice_no

String

Hayır Fatura No
external_id

Integer

Hayır İstemcinin yerel sunucusundaki ürünün yerel id'sidir. Upload işleminden sonra istemci-sunucu tarafındaki perakende satışların eşlenmesi için kullanılır.
Örn. "external_id": 1212

Örnek Perakende Satış Faturası oluşturma işleminin cevabı:


        {
            "status": "ok",
            "orders": [
                {
                    "operation_id": 44194,
                    "external_id": "1"
                },
                {
                    "operation_id": 44195,
                    "external_id": "2"
                }
            ]
        }
      

Cevapta bulunan 'status' anahtarı isteğin durumunu belirtir. 'orders' ise kaydedilen perakende satışları, 'operation_id' kaydedilen perakende satışın sunucudaki id'sini, 'external_id' parametre olarak alınan istemci perakende satış id'sini belirtir. Eğer external_id parametresi verilmeze cevapta o perakende satış external_id'si 'null döner'


Fatura bilgilerinde herhangi bir eksik veya yanlışlık bulunması durumunda sunucu o faturayı oluşturmayacaktır. Fakat hatalı olduğu için sistem hata kodu da dönmeyecektir. Eğer fatura oluşturulmadıysa sunucunun cevabında "orders" içinde fatura olmayacaktır. Fakat diğer faturalar başarılı oluşturulduysa o faturalara ait id'ler "orders" etiketi içinde olacaktır.


Ürün Yaratma Örnek Sorgu

curl -X POST -H "Accept: application/vnd.kobiks-api.v1+json" -H "Content-type: application/json" -H "Authorization: ACCESS_TOKEN"
https://www.kobiks.com/api/v1/api/import_products

  {
      "retail_sales" :
      [
        {
        "orderable_id": "81892-98686",
        "customer": "Demo Müşteriko",
        "quantity": "2.00",
        "price_category": "Perakende Satış Fiyatı (TL)",
        "price": "157",
        "fx_rate": "1",
        "discount_rate": "5",
        "discount_amount": "100",
        "tax_rate": "0",
        "store": "Merkez Depo",
        "invoice_date": "10/10/2018",
        "user": "Demo Kullanıcı",
        "notes": "Kobiks sistem girişi",
        "external_id": "1"
        },
        {
        "orderable_id": "81893-98687",
        "customer": "Demo Müşteriko",
        "quantity": "1.00",
        "price_category": "Perakende Satış Fiyatı (TL)",
        "price": "228",
        "fx_rate": "1",
        "discount_rate": "5",
        "discount_amount": "100",
        "tax_rate": "0",
        "store": "Merkez Depo",
        "invoice_date": "9/10/2018",
        "user": "Demo Kullanıcı",
        "notes": "Kobiks sistem girişi"
        }
      ]
  }
    

Perakende Satış Faturası Silme İşlemi

Perakende Satış faturasının silme işlemi için o faturaya ait 'id' gerekmektedir. Faturanın silinmesi işleminde o faturaya ait ödeme planlarıı ve yapılan ödemelerde silinir.


Örnek Perakende Satış Faturası silme işleminin cevabı:


    {
    "status": "ok",
    "invoice": {
        "id": 44192,
        "account_id": 401,
        "order_id": 32873,
        "invoice_draft_id": null,
        "associate_id": 56313,
        "store_id": 1397,
        "user_id": 1957,
        "assistant_id": null,
        "invoice_id": null,
        "code": "401181010082747E782",
        "serial_no": null,
        "sequence_no": null,
        "slip_no": null,
        "z_no": null,
        "okc_no": null,
        "okc_date": null,
        "billing_address_id": 57120,
        "location_id": 3467,
        "issued_at": "2018-10-10T08:27:47.000Z",
        "notes": "Kobiks sistem girişi",
        "quantity": 5,
        "sub_total": "785.0",
        "tax": "0.0",
        "discount": "100.000365",
        "total": "684.999635",
        "price_category_id": 4589,
        "currency_id": 1,
        "created_at": "2018-10-10T08:27:47.000Z",
        "updated_at": "2018-10-10T08:27:47.000Z",
        "deleted_at": "2018-10-10T08:36:53.441Z"
    }
}
      

Perakende Satış Faturası Silme

curl -X DELETE -H "Accept: application/vnd.kobiks-api.v1+json" -H "Content-type: application/json" -H "Authorization: ACCESS_TOKEN"
localhost:3000/api/v1/api/retail_sales/RETAILSALEINVOICEID