18. API Entegrasyonu

◀ İçindekiler

Inkica API’si, sisteminizin siparişleri kendiliğinden Inkica’ya göndermesini sağlar — her siparişi panelde elle oluşturmanız gerekmez. Şu durumlarda uygundur:

• Kendi web sitenizde veya Inkica’nın henüz hazır bağlantısı olmayan bir kanalda satış yapıyorsanız.
• Siparişleri yöneten kendi aracınız/yazılımınız varsa ve bunları doğrudan atölyeye iletmek istiyorsanız.
• Her şeyi otomatikleştirmek istiyorsanız: sipariş gelir → Inkica siparişi oluşturulur → takip izlenir.

eBay, Etsy, TikTok Shop, Shopify veya Amazon’da satış yapıyorsanız daha basit yol mağazanızı bağlamaktır — siparişler otomatik gelir, kod yazmanız gerekmez. API, geriye kalan durumlar içindir.

Bu sayfa hem sizin hem de entegrasyonu yapacak geliştirici için yazılmıştır — sayfanın bağlantısını doğrudan ona gönderebilirsiniz.

Genel çalışma şekli

1. Inkica panelinde API token’ı oluşturun (bir kez yapılır).
2. Satmak istediğiniz ürünün variant_id değerini almak için kataloğu sorgulayın (tişört modeli, renk, beden).
3. Sipariş oluşturun — alıcının adresini + baskı dosyalarını gönderin. Sipariş taslak durumunda oluşturulur, para düşülmez.
4. Üretime gönderin — Inkica parayı cüzdandan düşer ve siparişi atölyeye iletir.
5. Siparişi izleyin — sipariş kargo firmasına teslim edildiğinde durumunu ve takip kodunu okuyun veya Inkica’nın sizi kendiliğinden bilgilendirmesi için bir webhook kaydedin.

1. API token’ı oluşturma

1. Hesap menüsünü açın (kenar çubuğunun en altındaki köşe) → API.
2. Token oluştur’a tıklayın, akılda kalacak bir ad verin (örneğin “Website sync”).
3. Token’ı hemen kopyalayın — token ink_pat_... biçimindedir ve yalnızca 1 kez görünür. İletişim kutusunu kapattığınızda tekrar göremezsiniz, tek çare yeni token oluşturmaktır.

🔒 Token’ı parola gibi saklayın. Token’a sahip olan herkes sipariş oluşturabilir ve cüzdanınızdaki parayı harcayabilir. Token’ı tarayıcıda çalışan koda yapıştırmayın, sohbetle göndermeyin, GitHub’a commit etmeyin. Sızdığından şüpheleniyorsanız Ayarlar → API’ye girip İptal et’e tıklayarak hemen geçersiz kılın; o token anında devre dışı kalır.

Her hesapta aynı anda en fazla 10 token olabilir. Bir tanesini iptal etmeniz gerektiğinde diğerleri çalışmaya devam etsin diye her sistem/araç için ayrı bir token oluşturmanız önerilir.

2. API’yi çağırma

Token’ı hızlıca denemek için ürün listesini çekin:

curl https://api.inkica.com/api/v1/catalog/blueprints?limit=5 \
  -H "Authorization: Bearer ink_pat_xxxxxxxxxxxx"

Ürün listesi dönerse token kullanıma hazırdır.

3. Ürün seçme (katalog)

Katalogun 2 katmanı vardır:

• Blueprint — temel ürün modeli, örneğin “US Unisex Heavy Cotton Tee”.
• Variant — o blueprint’in belirli bir renk × beden kombinasyonu, örneğin Black / L. Sipariş oluştururken variant_id ile seçersiniz.

Blueprint listesi

GET /v1/catalog/blueprints?q=tee&page=1&limit=20

Ayrıca category ile filtreleyebilirsiniz (örneğin clothing). Her blueprint’te id, name, product_type, görsel ve print_areas — basılabilen konumlar — bulunur.

Bir blueprint’in ayrıntısı

GET /v1/catalog/blueprints/1

{
  "id": 1,
  "name": "US Unisex Heavy Cotton Tee 2D",
  "colors": [{ "name": "Black", "hex": "#000000" }],
  "sizes": ["S", "M", "L", "XL", "2XL"],
  "included_print_area": "front",
  "print_areas": [
    { "position": "front", "fee": 4.2, "width": 38, "height": 58, "unit": "cm" },
    { "position": "back",  "fee": 4.2, "width": 38, "height": 58, "unit": "cm" },
    { "position": "sleeve_left", "fee": 3.35, "width": 4, "height": 3.5, "unit": "inch" }
  ]
}

• print_areas[].width / height / unit — baskı alanının ölçüsü; baskı dosyasını doğru orana göre hazırlamak için kullanılır.
• fee — o konumun baskı ücreti.

Variant listesi (fiyatlarıyla)

GET /v1/catalog/blueprints/1/variants?page=1&limit=100

{
  "data": [
    { "id": 20139, "sku": "IUSG5000-S-ASH", "color": "ASH", "size": "S", "is_available": true, "price": 7.58 }
  ],
  "page": 1, "limit": 100, "total": 821
}

Fiyat nasıl hesaplanır: variant’ın price değerine 1 baskı konumu dahildir (included_print_area konumu, genellikle ön yüz). Başka bir konuma da basarsanız o konumun baskı ücreti eklenir. Yukarıdaki örnekte: yalnızca ön baskı = $7.58; ön + arka baskı = $7.58 + $4.20 = $11.78.

Her satırın kesin fiyatı, sipariş oluştururken unit_price içinde her zaman bulunur — o sayıyı esas alın.

Yalnızca is_available: true olan variant’ları kullanın. Büyük blueprint’lerde yüzlerce variant bulunur — hepsini almak için limit değerini artırın (en fazla 1000) veya page değerini değiştirin.

4. Kargo ücreti tahmini (zorunlu değil)

Sipariş verilmeden önce müşteriye kargo ücretini bildirmek istiyorsanız:

POST /v1/orders/shipping

{
  "line_items": [{ "variant_id": 20139, "quantity": 2 }],
  "address_to": { "country": "US", "region": "CA", "zip": "90001" },
  "shipping_method": "standard"
}

{ "shipping": 7.39, "currency": "USD", "is_estimate": true } döndürür. ABD’ye giden siparişlerde zip zorunludur.

Etiketi kendiniz sağlıyorsanız "shipping_mode": "self" ekleyin — dönen shipping bu durumda (kargo ücreti yerine) sabit işlem ücretidir, is_estimate: false.

5. Sipariş oluşturma

POST /v1/orders

{
  "external_id": "WEB-10023",
  "shipping_method": "standard",
  "address_to": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "phone": "+1 555 123 4567",
    "country": "US",
    "region": "CA",
    "address1": "123 Main St",
    "address2": "Apt 4",
    "city": "Los Angeles",
    "zip": "90001"
  },
  "line_items": [
    {
      "variant_id": 20139,
      "quantity": 2,
      "print_areas": {
        "front": "https://your-cdn.com/designs/front.png",
        "back": "https://your-cdn.com/designs/back.png"
      },
      "mockups": {
        "front": "https://your-cdn.com/mockups/front.jpg"
      }
    }
  ]
}

Baskı dosyası gereksinimleri: URL herkese açık bir bağlantı (https://...) olmalı, giriş yapmadan doğrudan indirilebilmeli ve sipariş teslim edilene kadar o bağlantı aynen korunmalıdır — atölye üretim sırasında dosyayı bu bağlantıdan indirir. PNG dosyası, saydam arka planlı ve 3. adımdaki baskı alanı ölçüsüne göre yeterli çözünürlükte olmalıdır.

Dönen sonuç, draft durumundaki siparişin kendisidir:

{
  "id": "4821",
  "external_id": "WEB-10023",
  "status": "draft",
  "line_items": [
    { "id": "9150", "variant_id": 20139, "sku": "IUSG5000-S-ASH", "quantity": 2, "unit_price": 11.78, "print_areas": { "front": "...", "back": "..." } }
  ],
  "subtotal": 23.56,
  "shipping": 0,
  "total": 23.56,
  "currency": "USD",
  "shipment": null
}

Taslak sipariş için para düşülmez ve üretim yapılmaz. Bu aşamada kargo ücreti her zaman 0’dır — üretime gönderilirken hesaplanır. API ile oluşturulan siparişler panelde Siparişler bölümünde, diğer siparişlerle aynı yerde görünür.

Kargo etiketini kendiniz sağlama (self-ship)

Elinizde hazır bir etiket mi var (kendiniz satın aldınız ya da pazaryeri verdi)? Siparişle birlikte gönderin — atölye sizin etiketinizi yazdırıp koliye yapıştırır, Inkica etiket satın almaz ve kargo ücreti almaz; yalnızca küçük bir sabit işlem ücreti ödersiniz (tam tutarı POST /v1/orders/shipping veya dry_run ile görebilirsiniz).

{
  "external_id": "WEB-10024",
  "shipping_mode": "self",
  "shipping_label": {
    "label_url": "https://your-cdn.com/labels/WEB-10024.pdf",
    "tracking_number": "9400111899223197428490",
    "carrier": "USPS"
  },
  "address_to": { "...": "..." },
  "line_items": [ { "...": "..." } ]
}

• shipping_mode: "self" ve shipping_label birlikte gönderilmelidir — yalnızca birini göndermek 400 döndürür.
• Etiket, siparişin tam olarak aynı address_to adresine gitmelidir. Inkica etiketin içeriğini okumaz: adresi yanlış, süresi dolmuş veya daha önce kullanılmış bir etiket koliyi yanlış yere gönderir ve sorumluluk size aittir.
• label_url doğrudan indirilebilmeli (giriş gerektirmemeli) ve baskı dosyalarında olduğu gibi sipariş teslim edilene kadar değişmeden kalmalıdır.
• Yalnızca standart kargo ile — priority/express ile birlikte kullanmak 400 döndürür (teslimat hızını sizin etiketiniz belirler).
• Bir etiket yalnızca bir koliye yapıştırılabilir; bu yüzden siparişteki tüm ürünler aynı atölye tarafından üretilmelidir ve her atölye dışarıdan gelen etiketi kabul etmez. Sipariş bu koşulu karşılamıyorsa üretime gönderme 400 döndürür — önceden dry_run ile kontrol edin. Bu durumda siparişi birkaç siparişe bölün ya da etiketi Inkica’nın alması için shipping_mode/shipping_label alanlarını kaldırın.
• Sipariş hâlâ taslakken fikrinizi değiştirdiyseniz: aynı external_id ile shipping_label olmadan yeniden gönderin → sipariş, etiketi Inkica’nın satın aldığı moda döner ve eski etiket bırakılır.
• Yanıtta "shipping_mode": "self" bulunur ve shipment etiketinizi + takip numaranızı hemen gösterir. Webhook kullanıyorsanız bu siparişin order:shipment:created olayı, atölyenin kargolamasını beklemeden sipariş oluşturulur/gönderilir gönderilmez gelir.

6. Üretime gönderme

POST /v1/orders/4821/send_to_production

Inkica kargo ücretini hesaplar, toplam tutarı cüzdandan düşer ve siparişi atölyeye iletir. Cüzdanda yeterli para yoksa API hata verir, sipariş taslak durumunda kalır; para yükleyip yeniden gönderin.

Gerçek gönderimden önce deneme (dry_run)

Entegrasyonu geliştiriyorsanız ve gerçek para harcamak istemiyorsanız "dry_run": true ekleyin:

POST /v1/orders/4821/send_to_production

{ "dry_run": true }

Inkica gerçek gönderimdeki tüm kontrolleri eksiksiz yapar — adres, baskı dosyaları, stok durumu, o konumu basabilecek bir atölye olup olmadığı, kargo ücreti — ardından düşülecek tutarı döndürür, ancak para düşmez, hiçbir şey üretilmez, sipariş taslak olarak kalır:

{
  "dry_run": true,
  "orders": [
    { "external_id": "WEB-10023", "subtotal": 23.56, "shipping": 7.39, "total": 30.95 }
  ],
  "total": 30.95,
  "currency": "USD",
  "wallet_balance": 26.66,
  "sufficient_balance": false
}

• total, o anda gerçekten gönderilirse düşülecek tam tutardır.
• sufficient_balance: false → cüzdan yetersiz, gerçek gönderim reddedilir — önce para yükleyin.
• Siparişte sorun varsa (stok yok, baskı konumu yapılamıyor…) gerçek gönderimde alacağınız 400 hatasının aynısını alırsınız.

İstediğiniz kadar deneme yapabilirsiniz. Her şey tamam olduğunda, gerçekten üretime göndermek için dry_run olmadan (veya "dry_run": false ile) yeniden gönderin.

Deneme, gönderimden sonraki adımlardan geçmez (siparişin in_production → shipped durumuna geçmesi, takip kodu alması). Durum/takip okuma kısmını test etmek için küçük bir gerçek sipariş kullanın — gerekirse hemen iptal edin, para cüzdana iade edilir.

⚠️ Bu adımdan sonra sipariş yeni bir id alır. Taslak sipariş resmi siparişle değiştirilir, bu nedenle eski id (4821) artık kullanılamaz. Daha sonra izlemek için dönen sonuçtaki orders[].id değerini kaydedin:

{
  "orders": [
    { "id": "4822", "external_id": "WEB-10023", "status": "in_production", "shipping": 7.39, "total": 30.95 }
  ]
}

Genellikle orders içinde yalnızca 1 sipariş olur. Siparişteki ürünlerin birden fazla atölyede yapılması gerekiyorsa sipariş birkaç siparişe bölünür — bu durumda external_id değerine -F1, -F2… eki gelir.

Dönen sonucu kaybettiniz mi (örneğin bağlantı yarıda koptu)? Yeniden göndermeyin — siparişi external_id ile bulun:

GET /v1/orders?external_id=WEB-10023

Sipariş bölünmüşse sonuçta -F1, -F2 parçaları da bulunur.

7. Siparişi izleme

GET /v1/orders/4822
GET /v1/orders?status=shipped&page=1&limit=50

Sipariş kargo firmasına teslim edildiğinde shipment alanında, müşteriye iletebileceğiniz takip bilgileri bulunur:

"shipment": {
  "carrier": "usps",
  "tracking_number": "9400111899223456789012",
  "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
  "label_url": "https://cdn.inkica.com/labels/4822.pdf",
  "status": "in_transit",
  "delivered_at": null
}

label_url, koliye yapıştırılan etiket dosyasıdır (PDF) — atölye etiketi kendisi satın alıp yalnızca takip kodunu geri gönderdiğinde null olur. tracking_url de null olabilir; bu durumda tracking_number ile carrier’ın sayfasında sorgulayın.

Etiketi sizin sağladığınız siparişlerde shipment, gönderdiğiniz etiket ve takip numarasıdır; sipariş oluşturulduğu andan itibaren görünür.

Sisteminizin sürekli sormak zorunda kalması yerine, sipariş durumu değiştiğinde veya takip kodu geldiğinde Inkica’nın sizi kendiliğinden bilgilendirmesini mi istiyorsunuz? Webhook kullanın. Webhook kullanmıyorsanız pending/in_production durumundaki siparişleri yaklaşık saatte 1 kontrol etmeniz önerilir.

8. Siparişi iptal etme

POST /v1/orders/4822/cancel

Yalnızca atölye üretime henüz başlamadıysa iptal edilebilir. Ödemesi yapılmış sipariş cüzdana iade edilir. Taslak sipariş iptal edilirse para düşülmediği için iade edilecek bir şey yoktur. İptal edilebilir süreyi geçtiyseniz API hata verir — yine de işlem gerekiyorsa support ile iletişime geçin.

9. Webhook — otomatik bildirimler

Sunucunuzda bir adres (URL) kaydedin — her değişiklikte Inkica oraya kendiliğinden gönderir (POST), sürekli sormanız gerekmez.

Kayıt

En hızlı yol: hesap menüsünü açın → API → Webhook’lar bölümü → Webhook ekle, URL’yi girin ve olayları seçin. Burada her webhook’un durumunu (çalışıyor / kapalı ve nedeni), son gönderimin başarılı mı hatalı mı olduğunu, Test gönder düğmesini ve silme düğmesini de görürsünüz.

Ya da API ile kaydedin:

POST /v1/webhooks

{
  "url": "https://your-server.com/inkica/webhooks",
  "events": ["order:updated", "order:shipment:created"]
}

events boş bırakılırsa = hepsini alırsınız. Dönen sonuçta whsec_... biçiminde bir secret bulunur — yalnızca 1 kez görünür, imzayı doğrulamak için saklayın (aşağıda).

• url herkese açık bir https:// adresi olmalıdır — iç adresler (localhost, LAN IP’leri…) kabul edilmez.
• Hesap başına en fazla 5 webhook, her URL yalnızca 1 kez kaydedilebilir. Listeyi görmek için: GET /v1/webhooks · Silmek için: DELETE /v1/webhooks/{id}.
• Hemen test gönderimi: POST /v1/webhooks/{id}/test — Inkica bir ping olayı gönderir ve sonucu döndürür (delivered, status_code, error).

Inkica’nın gönderdiği içerik

{
  "id": "dlv_1042",
  "event": "order:updated",
  "created_at": "2026-10-17T08:06:10.000Z",
  "data": {
    "previous_status": "in_production",
    "order": { "id": "4822", "external_id": "WEB-10023", "status": "shipped", "shipment": { "tracking_number": "9400111899223456789012", "...": "..." }, "...": "..." }
  }
}

data.order, GET /v1/orders/{id} ile tamamen aynı yapıdadır — mevcut sipariş işleme kodunuzu yeniden kullanabilirsiniz.

Sunucunuzun 10 saniye içinde 2xx kodu döndürmesi gerekir. Önce kaydedip hemen 200 döndürmeniz, işlemeyi sonra yapmanız önerilir.

İmzayı doğrulama (yapmanız şiddetle önerilir)

İsteğin gerçekten Inkica’dan geldiğinden (birinin taklit etmediğinden) emin olmak için her istekte şu header’lar bulunur:

İmzayı ham içerik (JSON olarak ayrıştırılmamış) üzerinden yeniden hesaplayıp karşılaştırın:

// Node.js (Express) — ham içeriği olduğu gibi korumak için express.raw() kullanın
const crypto = require('crypto');
app.post('/inkica/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-Inkica-Timestamp');
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.INKICA_WEBHOOK_SECRET)
    .update(`${ts}.${req.body}`).digest('hex');
  const got = req.get('X-Inkica-Signature') || '';
  const valid = got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
  if (!valid || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  // ... olayı kaydedin, işlemeyi sonra yapın
  res.sendStatus(200);
});

# Python (Flask)
import hmac, hashlib, time
from flask import request, abort
 
@app.post("/inkica/webhooks")
def inkica_webhook():
    ts = request.headers.get("X-Inkica-Timestamp", "")
    body = request.get_data()  # ham içerik (bytes)
    expected = "sha256=" + hmac.new(SECRET.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Inkica-Signature", "")) or abs(time.time() - int(ts or 0)) > 300:
        abort(401)
    event = request.get_json()
    return "", 200

// PHP
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_INKICA_TIMESTAMP'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_INKICA_SIGNATURE'] ?? '') || abs(time() - (int)$ts) > 300) {
  http_response_code(401); exit;
}
$event = json_decode($body, true);
http_response_code(200);

Ayrıca birinin eski bir isteği yeniden göndermesini engellemek için X-Inkica-Timestamp değerinin 5 dakikadan eski olmadığını da kontrol edin.

Hata durumunda yeniden gönderim

• Sunucunuz 2xx döndürmezse (hata, 10 saniyeyi aşma, erişilememe) Inkica kendiliğinden yeniden gönderir: 1, 5, 15, 60 dakika sonra, ardından 3, 6, 12 saat sonra — yaklaşık 1 gün içinde toplam 8 kez.
• Aynı olay birden fazla kez gelebilir ve olaylar sırasız gelebilir — yinelenenleri atlamak için id kullanın ve sıranın doğru olduğunu varsaymak yerine her zaman en güncel data.order.status değerine (veya GET /v1/orders/{id} çağrısına) güvenin.
• Çok uzun süre hata verirse (art arda 20 gönderim tamamen başarısız) webhook kendiliğinden kapanır (active: false). Sunucunuzu düzelttikten sonra API sayfasında (hesap menüsü) Test gönder’e tıklayın (veya POST /v1/webhooks/{id}/test çağırın) — başarılı ping webhook’u yeniden açar. Webhook kapalıyken gerçekleşen değişiklikler sonradan gönderilmez — yeniden açtıktan sonra, takip ettiğiniz siparişlerin durumunu güncellemek için GET /v1/orders çağırın.
• Panelden oluşturduğunuz siparişler veya pazaryeri siparişleri (eBay, Etsy…) için de bildirim gelir — yalnızca API ile oluşturduğunuz siparişlerle ilgileniyorsanız external_id’ye göre filtreleyin.

Sık karşılaşılan hatalar

Hata olduğunda API, HTTP kodunu ve message içinde bir açıklama döndürür:

{ "statusCode": 400, "error": "Bad Request", "message": "line_items[0].print_areas: this blueprint has no \"hood\" print position" }

Sınırlar

• Dakikada 600 çağrı.
• Sipariş başına en fazla 50 ürün satırı, hesap başına 10 token.
• Yalnızca Inkica kataloğundan (variant_id ile) sipariş oluşturulabilir; Ürünler bölümünde oluşturduğunuz ürünler henüz API üzerinden doğrudan kullanılamaz.
• Hesap başına en fazla 5 webhook.
• Ayrı bir test ortamı henüz yok — para harcamadan sipariş kontrolü için dry_run kullanın.

◀ Bildirimler · İçindekiler · Sonraki: Davet programı ▶