Kobiks - API V1

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.



  • - 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.


Gönderilen istek başlığında 'Content-Type: application/json' ve 'Accept: application/vnd.kobiks-api.v1+json' olması gerekmektedir.

Sorgu Filtreleri

İsteğinize göre filtrelenmiş dataya ulaşmak için URL kısmına eklenebilecek parametreler örnekle açıklanmıştır.

http://localhost:3000/api/v1/products?include=supplier&page[size]=10&page[number]=1&sort=name

- include parametresi, dönüş bilgileri içerisinde varyant'ın ürün ve tedarikçi bilgisiyle birlikte gelmesi için kullanılmıştır.

- page gelen verileri sayfalamak için bu parametre kullanılmalıdır.

  • Size ifadesi bir sayfada kaç adet bilgi getirileceğini göstermektedir.
  • Number ifadesi ise kaçıncı sayfa bilgisinin istendiğini belirtmektedir.

- sort parametresi, hangi kolona veya kolonlara göre göre sıralanması isteniyorsa dizi içerisinde verilmelidir. Varsayılan olarak Asc kabul edilmektedir. Değerin '-' ile başlaması halinde desc olarak sıralama yapılacaktır. (ÖR: '-variant.cachedName'') 

BASE_URL/deliveries?filters[created_at][gt]='2020-06-16 13:00:00'

- filters parametresi, dinamik sonuç üretmek için kullanılmaktadır. İlk dizi elemanı, değişkeni belirtirken; ikinci dizi elemanı, terimi belirtir

  • eq Equal: "="
  • not_eq Not Equal: "<>"
  • lt Less Than: "<"
  • gt Greater Than: ">"
  • lteq Less Equal: "<="
  • gteq Greater Equal: ">="
  • matches Contains Pattern: "LIKE"

Doğrulama ve Giriş İşlemi

Kobiks API kimlik doğrulama için Bearer Authentication kullanmaktadır.


Kullanıcı bilgilerini almak için destek@kobiks.com adresine mail atabilirsiniz.


Kimlik doğrulama işleminin başarılı olması durumunda bir adet kimlik jetonu (authentication token) ve bir adet de yenileme jetonu (refresh token) gönderilecektir. Kimlik jetonu 2 saat süreyle geçerlidir ve her istekte http başlık bilgilerinin içerisinde gönderilmelidir. Bu sürenin sonunda kimlik jetonu geçerliliğini yitirecektir ve yenileme jetonu kullanılarak tekrar üretilmesi gerekmektedir.


Gönderilen istek başlığında 'Authorization: Bearer $TOKEN' olması gerekmektedir.







Request POST 'https://kobiks.com/api/v1/login'

    "user": {
      "email": "EMAIL",
      "password": "PASSWORD"
    }

Response

    {
      token: "TOKEN",
      refreshToken: "REFRESH_TOKEN"
    }

Ürün Oluşturma

Ürün oluştururken kullanılacak niteliklerin açıklamaları aşağıdaki tabloda verilmiştir. En geniş kapsamıyla bir ürünün oluşturulması için gerekli json body yan tarafta belirtilmiştir.


Örn: Bir ürün oluştururken sistemde var olan bir tedarikçi ile ilişkilendirilmek isteniyor olsun. Bu durumda name bilgisi eğer sistemde var olan bir tedarikçi bilgisi ile eşleşiyorsa; bir ilişki kurulacaktır. Aksi taktirde hata mesajı dönecektir.


Hem ürün oluşturma hem de ürün güncelleme aynı parametre ile yapılmak istenirse parametre olarak create_or_update: true eklenmelidir. Öncelikle ürün ismine eğer yoksa sku bilgisine bakılarak ürünün sistemde daha önce oluşturulup oluşuturulmadığı kontrol edilir. Eğer sistemde ürün varsa güncelleme işlemi yapılır.
BASE_URL/unit_products?create_or_update=true


Dönüş değeri, başarılı olma durumunda 200 OK mesajı dönecektir.

Nitelik Tür Zorunlu Açıklama
name String Evet Ürün ismi
supplier Hash Hayır supplier eklendiyse isim ve code kısmı zorunlu.
supplier:name String Koşullu zorunlu Tedarikçi İsmi
supplier:code String Koşullu zorunlu Tedarikçiyi tanımlayan kod
short_desc String Hayır Ürünün kısa açıklaması
desc String Hayır Ürünün açıklaması
taxRate Float Hayır Ürünün KDV oranı.
Örn. "1", "2.5", "8", "18"
brand String Hayır Marka ismi
Örn. "Kısmet" veya "Beko"
is_active

String

 Hayır Ürün aktif mi?
Örn. "true" veya "false"
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. "true" veya "false"
stock_enabled String Hayır Stok takibi yapılsın mı?
Örn. "true" veya "false"
oversell String Hayır Depo harici satışa izin verilsin mi?
Örn. "true" veya "false"
alert_at Date Hayır Yeniden sipariş noktası
consign String Hayır Konsinye ürün mü?
Örn. "true" veya "false"
exp_date Date Hayır Ürünün son kullanma tarihi
categories Array Hayır Ürünün kategorileri
Örn. "kolye" veya "kolye, bilezik"
commodities Hash Array Hayır commodities eklendiyse name ve value kısımları zorunlu
commodities:name String Koşullu Zorunlu Hammadde ismi
commodities:value String Koşullu Zorunlu Ürünün hammadde miktarı
product_features Hash Array Hayır product_features eklendiyse name ve value kısımları zorunlu
product_features:name String Koşullu Zorunlu Ürün özelliği ismi
product_features:value String Koşullu Zorunlu Ürünün özelli
prices Hash Array Hayır prices eklendiyse name ve value kısımları zorunlu
prices:price_category_name String Koşullu Zorunlu Sistemdeki fiyat kategorisi ismi
prices:value String Koşullu Zorunlu Ürünün fiyat kategorisideki fiyatı
images Hash Array Hayır images eklendiyse uri kısmı zorunlu
images:uri String Koşullu Zorunlu Ürün resminin çekileceği url adresi
prices Hash Array Hayır prices eklendiyse name ve value kısımları zorunlu
prices:price_category_name String Koşullu Zorunlu Sistemdeki fiyat kategorisi ismi
prices:value String Koşullu Zorunlu Ürünün fiyat kategorisideki fiyatı
quantities Hash Array Hayır quantities eklendiyse location_name ve value kısımları zorunlu
quantities:location_name String Koşullu Zorunlu Sistemdeki lokasyon ismi
quantities:value String Koşullu Zorunlu Ürünün belirtilen lokasyondaki miktarı

Request POST 'https://kobiks.com/api/v1/unit_products'

{
    "name": "Test|001",
    "supplier": {
        "name": "Demo Ted",
        "code": "724.T.01"
    },
    "short_desc": "kısa açıklama",
    "desc": "açıklama",
    "brand": "TIFFANY G",
    "tax_rate": 18,
    "is_active": true,
    "sku":"00000001",
    "barcode":"11111111",
    "sellable":true,
    "stock_enabled":true,
    "oversell":true,
    "alert_at":10,
    "consign":false,
    "exp_date":"22-06-2020",
    "priority":1,
    "shelf":1,
    "categories": ["1600", "1605"],
    "commodities": [
      {"name": "Pırlanta",  "value": 1,020},
      {"name": "Altın 8K",  "value": 5,920},
    ],
    "product_features": [
      {"name": "KISA KOD",      "value": "000194"},
      {"name": "MODEL KODU",    "value": "ALY00421"},
    ],
    "prices": [
      {"price_category_name": "Toptan Alış Fiyatı (USD)",     "value": "1068"},
      {"price_category_name": "Perakende Satış Fiyatı (USD)", "value": "13090"}
    ],
    "images": [
      {"uri": "http://img.kobiks.com/testurun.png" },
      {"uri": "http://img.kobiks.com/testurun_2.jpg" }
    ],
    "quantities": [
      {
        "location_name": "Merkez Depo",
        "value":  1
      },
      {
        "location_name": "Test Depo",
        "value":  1
      }
    ]
}

Response

    {
      "ok"
    }

Ürün Güncelleme

Ürün Güncelleme, ürün yaratma ile aynı json kullanılır.


- Stok kodu bilgisi parametreye eklenmelidir. Eğer stok kodu ile ilişkili bir ürün bulunmaz ise hata mesajı dönecektir. Stok kodu parametre ile gönderildiği için body içerisinde göndereceğiniz stok kodunu güncelleyebilirsiniz

- Girilmeyen bilgiler için herhangi bir işlem yapılmaz. Boş dizi gönderilse bile silme işlemi yapılmaz.

- Ürünün silinmek istenen özelliği için "_destroy: true" eklenmeli.

- Kategori bilgileri verildiği kadarı kaydedilir. Varsa diğer ilişkileri silinir.

- Ürün fiyatı ve hammadde miktarı 0 olan değerler için ilişkiler silinir.

- Ürüne resim eklenirken eski resim bilgileri girilmezse eski olanlar silinir.


Request POST 'https://kobiks.com/api/v1/unit_products/:sku'

{
    "name": "Test|001",
    "supplier": {
        "name": "Demo Ted",
        "code": "724.T.01"
    },
    "short_desc": "kısa açıklama",
    "desc": "açıklama",
    "brand": "Marka",
    "tax_rate": 18,
    "is_active": true,
    "sku":"00000001",
    "barcode":"11111111",
    "sellable":true,
    "stock_enabled":true,
    "oversell":true,
    "alert_at":10,
    "consign":false,
    "exp_date":"22-06-2020",
    "priority":1,
    "shelf":1,
    "categories": ["1600", "1605"],
    "commodities": [
      {"name": "Pırlanta",  "value": 1,020},
      {"name": "Altın 8K",  "value": 5,920},
    ],
    "product_features": [
      {"name": "KISA KOD",      "value": "000194", '_destroy': true},
      {"name": "MODEL KODU",    "value": "ALY00421"},
    ],
    "prices": [
      {"price_category_name": "Toptan Alış Fiyatı (USD)",     "value": "1068"},
      {"price_category_name": "Perakende Satış Fiyatı (USD)", "value": "13090"}
    ],
    "images": [
      {"uri": "http://img.kobiks.com/testurun.png" },
      {"uri": "http://img.kobiks.com/testurun_2.jpg" }
    ],
    "quantities": [
      {
        "location_name": "Merkez Depo",
        "value":  1
      },
      {
        "location_name": "Test Depo",
        "value":  1
      }
    ]
}

Response

    {
      "ok"
    }

İrsaliye Listesi

Bu yöntem ile sistemdeki irsaliye listesine ulaşılabilmektedir. Url içerisine ekleyeceğiniz query filters ile toptan alış veya toptan satışa ait irsaliyelere ulaşabilirsiniz.

Örn: 

BASE_URL/whole_purchase_return_deliveries?include=line_items&filters[created_at][gt]='2020-05-20 13:00:00'


Request GET 'https://kobiks.com/api/v1/whole_purchase_return_deliveries?include=line_items'

Response

    [
        {
        "associate_name": "Test Müşteri",
        "code": "153200522111635C629",
        "created_at": "2020-05-22 11:16:35 UTC",
        "issued_at": "2020-05-22 11:16:35 UTC",
        "line_items": [
            {
                "quantity": 1,
                "variant_name": "2110079128517-6143688    ",
                "variant_sku": "S05",
                "notes": 'IADE',
                "transaction_type" 'Ürün İade'
            }
        ],
        "location_name": "Merkez Depo",
        "notes": 'IADE',
        "user_name": "Test Kullanıcı"
    },
    {
        "associate_name": "Test Müşteri 2",
        "code": "153200522134441B88D",
        "created_at": "2020-05-22 13:46:34 UTC",
        "issued_at": "2020-05-22 13:46:34 UTC",
        "line_items": [
            {
                "quantity": 1,
                "variant_name": "7000720 36.0   ",
                "variant_sku": "KCT00001",
                "notes": 'IADE',
                "transaction_type" 'Ürün İade'
            },
            {
                "quantity": 1,
                "variant_name": "7000721 38.0   ",
                "variant_sku": "KCT00002",
                "notes": 'IADE',
                "transaction_type" 'Ürün İade'
            }
        ],
        "location_name": "Merkez Depo",
        "notes": "2 adet iade ürünler",
        "user_name": "Test Kullanıcı"
    }
  ]

Toptan Alış Fatura Listesi

Bu yöntem ile sistemdeki toptan alış fatura listesine ulaşılabilmektedir. Url içerisine ekleyeceğiniz query filters ile toptan alışa ait faturalara ulaşabilirsiniz.

Örn: 

BASE_URL/whole_purchase_invoices?filters[created_at][gt]='2020-07-14 00:00'


Request GET 'https://kobiks.com/api/v1/whole_purchase_invoices?filters[created_at][gt]='2020-07-14 00:00''

Response

  [
    {
        "associate_name": "Test Müşteri",
        "code": "153200522111635C629",
        "created_at": "17/07/2020 17:27:20",
        "currency": "TRY",
        "discount": "0.0",
        "issued_at": "13/07/2020 17:27:20",
        "location_name": "Merkez Depo",
        "notes": null,
        "price_category": "Toptan Alış Fiyatı (TL)",
        "quantity": 52,
        "sub_total": "13202.000007",
        "tax": "2376.360001",
        "total": "15578.360008",
        "user_name": "Test Kullanıcı",
        "line_items": [
            {
                "base_unit": "adt",
                "discount": "0.0",
                "notes": null,
                "price": "310.555556",
                "quantity": "1",
                "sub_total": "310.555556",
                "tax": "55.9",
                "tax_rate": 18.0,
                "total": "366.455556",
                "variant_name": "12471 1   ",
                "variant_sku": "KCT00000"
            },
            {
                "base_unit": "adt",
                "discount": "0.0",
                "notes": null,
                "price": "416.111111",
                "quantity": "1",
                "sub_total": "416.111111",
                "tax": "74.9",
                "tax_rate": 18.0,
                "total": "491.011111",
                "variant_name": "12321 LXL    ",
                "variant_sku": "KCT00001"
            }
        ],
        "deliveries": [
            {
                "associate_name": "Test Müşteri",
                "code": "153200717142720EA0A",
                "created_at": "17/07/2020 17:27:20",
                "issued_at": "17/07/2020",
                "location_name": "Merkez Depo (Depo)",
                "notes": null,
                "user_name": "Test Kullanıcı",
                "shipping_address": {
                    "address1": "Arnavutköy Mah. AbdulHakmolla Sk. No: 9-11 İç kapı No:3 Beşiktaş/İstanbul",
                    "address2": "",
                    "address_type": "dual",
                    "city": "",
                    "code": "",
                    "country": "",
                    "created_at": "2020-05-12 14:44:55",
                    "email": "",
                    "fax": null,
                    "name": "KillYourIdol-Sedat Yazıcı",
                    "phone": "",
                    "tax_no": "31697240394",
                    "tax_office": "Beşiktaş",
                    "trade_name": "KillYourIdol-Sedat Yazıcı",
                    "trade_type": "business",
                    "updated_at": "2020-05-12 18:22:21",
                    "zip": ""
                },
                "line_items": [
                    {
                        "quantity": 10,
                        "base_unit": "adt",
                        "composite_quantity": 500.0,
                        "composite_base_unit": "adt",                        
                        "transaction_type": null,
                        "variant_name": "PAKET (50 ADT)",
                        "variant_sku": "51KBKS2001BY",
                        "notes": null
                    },
                    {
                        "quantity": 1,
                        "base_unit": "kg",
                        "composite_quantity": null,
                        "composite_base_unit": null,                        
                        "transaction_type": null,
                        "variant_name": "7001472 LXL",
                        "variant_sku": "57KBKS2234BY",
                        "notes": null
                    }
                ]
            }
        ]
    }
  ]

Toptan Satış Faturası Listesi

Bu yöntem ile sistemdeki toptan satış fatura listesine ulaşılabilmektedir. Url içerisine ekleyeceğiniz query filters ile toptan satışa ait faturalara ulaşabilirsiniz.

Örn: 

BASE_URL/whole_sale_invoices?filters[created_at][gt]='2020-05-14 00:00'


Request GET 'https://kobiks.com/api/v1/whole_sale_invoices?filters[created_at][gt]='2020-05-14 00:00''

Response

[
    {
        "associate_name": "Test Müşteri",
        "code": "153200522111635C629",
        "created_at": "17/07/2020 17:27:20",
        "currency": "TRY",
        "discount": "0.0",
        "issued_at": "13/07/2020 17:27:20",
        "location_name": "Merkez Depo",
        "notes": null,
        "price_category": "Toptan Satış Fiyatı (TL)",
        "quantity": 52,
        "sub_total": "13202.000007",
        "tax": "2376.360001",
        "total": "15578.360008",
        "user_name": "Test Kullanıcı",
        "line_items": [
            {
                "base_unit": "adt",
                "discount": "0.0",
                "notes": null,
                "price": "310.555556",
                "quantity": "1",
                "sub_total": "310.555556",
                "tax": "55.9",
                "tax_rate": 18.0,
                "total": "366.455556",
                "variant_name": "12471 1   ",
                "variant_sku": "KCT00000"
            },
            {
                "base_unit": "adt",
                "discount": "0.0",
                "notes": null,
                "price": "416.111111",
                "quantity": "1",
                "sub_total": "416.111111",
                "tax": "74.9",
                "tax_rate": 18.0,
                "total": "491.011111",
                "variant_name": "12321 LXL    ",
                "variant_sku": "KCT00001"
            }
        ],
        "deliveries": [
            {
                "associate_name": "Test Müşteri",
                "code": "153200717142720EA0A",
                "created_at": "17/07/2020 17:27:20",
                "issued_at": "17/07/2020",
                "location_name": "Merkez Depo (Depo)",
                "notes": null,
                "user_name": "Test Kullanıcı",
                "shipping_address": {
                    "address1": "Arnavutköy Mah. AbdulHakmolla Sk. No: 9-11 İç kapı No:3 Beşiktaş/İstanbul",
                    "address2": "",
                    "address_type": "dual",
                    "city": "",
                    "code": "",
                    "country": "",
                    "created_at": "2020-05-12 15:34:21",
                    "email": "",
                    "fax": null,
                    "name": "KillYourIdol-Sedat Yazıcı",
                    "phone": "",
                    "tax_no": "31697240394",
                    "tax_office": "Beşiktaş",
                    "trade_name": "KillYourIdol-Sedat Yazıcı",
                    "trade_type": "business",
                    "updated_at": "2020-05-12 18:22:21",
                    "zip": ""
                },
                "line_items": [
                    {
                        "quantity": 10,
                        "base_unit": "adt",
                        "composite_quantity": 500.0,
                        "composite_base_unit": "adt",
                        "transaction_type": null,
                        "variant_name": "PAKET (50 ADT)",
                        "variant_sku": "51KBKS2001BY",
                        "notes": null
                    },
                    {
                        "quantity": 1,
                        "base_unit": "kg",
                        "composite_base_unit": null,
                        "composite_quantity": null,
                        "transaction_type": null,
                        "variant_name": "7001472 LXL",
                        "variant_sku": "57KBKS2234BY",
                        "notes": null
                    }
                ]
            }
        ]
    }
]

Fiyat Kategorileri

Hesaba tanımlı fiyat kategorileri listesine ulaşmak için kullanılmaktadır.


tax_included: Fiyata vergi dahil olup olmadığı bilgisi

Request GET 'https://kobiks.com/api/v1/price_categories'

Response

    [
      {
        "currency": {
            "iso": "TRY",
            "name": "Türk Lirası"
        },
        "name": "Toptan Alış Fiyatı (TL)",
        "price_type": "whole_buy",
        "tax_included": false
      },
      {
          "currency": {
              "iso": "TRY",
              "name": "Türk Lirası"
          },
          "name": "Toptan Satış Fiyatı (TL)",
          "price_type": "whole_sell",
          "tax_included": false
      },
      {
          "currency": {
              "iso": "TRY",
              "name": "Türk Lirası"
          },
          "name": "Perakende Satış Fiyatı (TL)",
          "price_type": "retail_sell",
          "tax_included": false
      },
      {
          "currency": {
              "iso": "USD",
              "name": "Amerikan Doları"
          },
          "name": "Perakende Satış Fiyatı (Dolar)",
          "price_type": "retail_sell",
          "tax_included": true
      }
   ]

Ürün Özellikleri

Hesaba tanımlı ürün özellikleri listesine ulaşmak için kullanılmaktadır.


required: Ürün oluşturulken ürün özelliğinin zorunlu olup olmadığı bilgisi. Eğer true ise ürün oluştururken bu bilginin eklenmesi gerekecektir. Aksi taktirde ürün oluşturma hatası ile karşılaşılır.
value_type: Arayüzde kullanılmak üzere ürün özelliği giriş özelliğini belirtmektedir. "text", "date", "checkbox" ve "integer" değerlerini alabilmektedir.

Request GET 'https://kobiks.com/api/v1/product_feature_types'

Response

    [
      {
          "name": "Color",
          "required": false,
          "value_type": "text"
      }
      {
          "name": "Uretici kodu",
          "required": false,
          "value_type": "text"
      },
      {
          "name": "SIZE",
          "required": false,
          "value_type": "text"
      }
    ]

Bileşenler

Hesaba tanımlı bileşenler listesine ulaşmak için kullanılmaktadır.

Request GET 'https://kobiks.com/api/v1/commodities'

Response

    [
        {
            "currency": {
                "iso": "TRY",
                "name": "Türk Lirası"
            },
            "factor": 0.75,
            "iso": "AU",
            "name": "altın",
            "price": "145.4625",
            "unit_code": "Gr",
            "unit_price": "193.95",
            "market_date": "2018-07-17 00:00:00 UTC"
        }
    ]

İşlem Türleri

Hesaba tanımlı işlem türleri listesine ulaşmak için kullanılmaktadır.


Modüllere bağlı listeyi filtrelemek için filters kullanılmaktadır. Tanımlı moduller:

- repair

- return

Örn: 

BASE_URL/transaction_types?filters[module][eq]=repair

Request GET 'https://kobiks.com/api/v1/transaction_types'

Response

    [
        {
            "module": "repair",
            "name": "test",
            "state_code": "on_sale"
        }
    ]

Tamir Listesi

Bu yöntem ile sistemdeki tamir listesine ulaşılabilmektedir. Url içerisine ekleyeceğiniz query filters ile tamir listesine filtre uygulayabilirsiniz.

Örn: 

BASE_URL/repair_orders?filters[created_at][gt]='2020-05-20 13:00:00'


Request GET 'https://kobiks.com/api/v1/repair_orders

Response

    [
      {
          "associate_name": "TEST MÜŞTERİSİ SAN.TİC.LTD.ŞTİ",
          "code": "300200826092548F3C0",
          "created_at": "26/08/2020 12:25:48",
          "line_items": [
              {
                  "discount_rate": 0.0,
                  "fx_rate": null,
                  "notes": null,
                  "orig_price": 0,
                  "price": 0,
                  "quantity": 1,
                  "status": null,
                  "tax_rate": 18.0,
                  "variant_name": " DP69-DPS125-02",
                  "variant_sku": "DPS125-02"
              }
          ],
          "notes": "",
          "order_date": "26/08/2020",
          "user_name": "Kobiks"
      }
  ]