Geliştiriciler

API ve Yapay Zeka Bağlantısı Belgeleri

Mağazanızın ürün, sipariş ve müşteri verisine kendi yazılımınızdan ya da yapay zeka asistanınızdan erişin.

Kimlik Doğrulama

Anahtar panelde Ayarlar › API bölümünden oluşturulur; ad ve yetkiler seçilir, anahtar (tici_ ile başlar) yalnız oluşturulduğu anda bir kez gösterilir. Her istekte 'Authorization: Bearer tici_…' başlığıyla gönderilir. Yetkiler: products:read, products:write, orders:read, orders:write, customers:read. API ve MCP erişimi Pro Plus paketinde açıktır; diğer paketlerde istek 403 döner. Anahtarı oluşturan yönetici kaldırılırsa ya da tam yetkisi alınırsa anahtar çalışmaz (401). Anahtar geçersizse 401, anahtarda rotanın yetkisi yoksa 403, doğrulama hatasında 422 döner; hata gövdesi {"message": "…"}.

İstek Sınırı

Uç başına dakikada 120 istek (REST v1 ve /mcp). Sayaç istemcinin IP adresine göre ve her uç için ayrı tutulur. Aşılırsa 429 döner; X-RateLimit-Limit, X-RateLimit-Remaining ve Retry-After başlıkları gelir.

REST API

GET/api/v1/openapi.json

OpenAPI belgesi

REST API'nin OpenAPI şeması. Anahtar gerektirmez.

Örnek yanıt

{
  "openapi": "3.1.0",
  "info": {
    "title": "…"
  },
  "paths": {
    "/products": {}
  }
}

GET/api/v1/products

Ürünleri listele

Listelenen ürünler; varyant, görsel, marka ve kategorileriyle.

Yetki: products:read

Parametre	Tür	Açıklama
updated_since	tarih (ISO 8601)	Yalnız bu andan sonra güncellenen kayıtlar; artımlı çekim için.
per_page	tam sayı (1-200)	Sayfa başına kayıt; varsayılan 50.
page	tam sayı	Sayfa numarası; yanıttaki links.next ile ilerlenir.

Örnek yanıt

{
  "data": [
    {
      "id": 42,
      "title": "Seramik Kupa",
      "slug": "seramik-kupa",
      "url": "https://magaza.com/urun/seramik-kupa",
      "status": "active",
      "brand": "Atölye",
      "categories": [
        "Mutfak"
      ],
      "description": "<p>El yapımı seramik kupa.</p>",
      "option_names": [
        "Renk"
      ],
      "images": [
        "https://magaza.com/storage/media/kupa-1600.webp"
      ],
      "variants": [
        {
          "id": 77,
          "sku": "KUPA-MAVI",
          "barcode": "8690000000017",
          "title": "Mavi",
          "options": [
            "Mavi"
          ],
          "price_minor": 19990,
          "compare_at_minor": 24990,
          "stock": 12
        }
      ],
      "updated_at": "2026-11-12T14:05:00+03:00"
    }
  ],
  "links": {
    "first": "…?page=1",
    "last": "…?page=3",
    "prev": null,
    "next": "…?page=2"
  },
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 128,
    "last_page": 3
  }
}

GET/api/v1/products/{product}

Ürün getir

Kimliğiyle tek ürün. Yoksa 404.

Yetki: products:read

Parametre	Tür	Açıklama
product *	tam sayı (yol)	Ürün kimliği (id).

Örnek yanıt

{
  "data": {
    "id": 42,
    "title": "Seramik Kupa",
    "slug": "seramik-kupa",
    "url": "https://magaza.com/urun/seramik-kupa",
    "status": "active",
    "brand": "Atölye",
    "categories": [
      "Mutfak"
    ],
    "description": "<p>El yapımı seramik kupa.</p>",
    "option_names": [
      "Renk"
    ],
    "images": [
      "https://magaza.com/storage/media/kupa-1600.webp"
    ],
    "variants": [
      {
        "id": 77,
        "sku": "KUPA-MAVI",
        "barcode": "8690000000017",
        "title": "Mavi",
        "options": [
          "Mavi"
        ],
        "price_minor": 19990,
        "compare_at_minor": 24990,
        "stock": 12
      }
    ],
    "updated_at": "2026-11-12T14:05:00+03:00"
  }
}

PATCH/api/v1/variants/{sku}

Fiyat ve stok güncelle

SKU'su verilen varyantın fiyatını, indirimden önceki fiyatını ve stoğunu günceller; gönderilmeyen alan değişmez. Stok değişimi stok hareketlerine 'API · <anahtar adı>' notuyla yazılır ve satış kanallarına yansır. Yanıt ürünün güncel halidir.

Yetki: products:write

Parametre	Tür	Açıklama
sku *	metin (yol)	Varyant SKU'su.
price	metin ya da sayı	Satış fiyatı, TL: "199,90" ya da 199.9. Sıfırdan büyük olmalı.
compare_at	metin ya da sayı	İndirimden önceki fiyat, TL. Satış fiyatından büyük değilse boşaltılır.
stock	tam sayı (0-1000000)	Yeni stok adedi.
warehouse_id	tam sayı	Stoğun yazılacağı depo kimliği; verilmezse varsayılan depo.

Örnek yanıt

{
  "data": {
    "id": 42,
    "title": "Seramik Kupa",
    "slug": "seramik-kupa",
    "url": "https://magaza.com/urun/seramik-kupa",
    "status": "active",
    "brand": "Atölye",
    "categories": [
      "Mutfak"
    ],
    "description": "<p>El yapımı seramik kupa.</p>",
    "option_names": [
      "Renk"
    ],
    "images": [
      "https://magaza.com/storage/media/kupa-1600.webp"
    ],
    "variants": [
      {
        "id": 77,
        "sku": "KUPA-MAVI",
        "barcode": "8690000000017",
        "title": "Mavi",
        "options": [
          "Mavi"
        ],
        "price_minor": 19990,
        "compare_at_minor": 24990,
        "stock": 12
      }
    ],
    "updated_at": "2026-11-12T14:05:00+03:00"
  }
}

GET/api/v1/orders

Siparişleri listele

Siparişler kalemleri, tutarları, adresleri ve kargo bilgisiyle.

Yetki: orders:read

Parametre	Tür	Açıklama
status	metin	Sipariş durumu: awaiting_payment, payment_review, to_ship, shipped, delivered, refunded, payment_failed, cancelled.
updated_since	tarih (ISO 8601)	Yalnız bu andan sonra güncellenen kayıtlar; artımlı çekim için.
per_page	tam sayı (1-200)	Sayfa başına kayıt; varsayılan 50.
page	tam sayı	Sayfa numarası; yanıttaki links.next ile ilerlenir.

Örnek yanıt

{
  "data": [
    {
      "number": 1042,
      "status": "to_ship",
      "status_label": "Kargoya verilecek",
      "payment_method": "card",
      "source": "storefront",
      "channel": null,
      "external_id": null,
      "customer": {
        "name": "Ayşe Yılmaz",
        "email": "ayse@ornek.com",
        "phone": "+905321112233"
      },
      "shipping_address": {
        "name": "Ayşe Yılmaz",
        "phone": "+905321112233",
        "line1": "Bağdat Cad. 12/3",
        "district": "Kadıköy",
        "city": "İstanbul",
        "zip": "34710",
        "country": "TR"
      },
      "billing_address": null,
      "currency": "TRY",
      "subtotal_minor": 19990,
      "discount_minor": 0,
      "shipping_minor": 4990,
      "cod_fee_minor": 0,
      "tax_minor": 3332,
      "total_minor": 24980,
      "commission_minor": 0,
      "coupon_code": null,
      "items": [
        {
          "sku": "KUPA-MAVI",
          "title": "Seramik Kupa",
          "variant": "Mavi",
          "quantity": 1,
          "unit_price_minor": 19990,
          "total_minor": 19990,
          "tax_rate_bp": 2000
        }
      ],
      "delivery_method": "cargo",
      "delivery_date": null,
      "carrier": null,
      "tracking_number": null,
      "note": null,
      "created_at": "2026-11-12T13:40:00+03:00",
      "paid_at": "2026-11-12T13:41:00+03:00",
      "shipped_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "updated_at": "2026-11-12T13:41:00+03:00"
    }
  ],
  "links": {
    "first": "…?page=1",
    "last": "…?page=3",
    "prev": null,
    "next": "…?page=2"
  },
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 128,
    "last_page": 3
  }
}

GET/api/v1/orders/{number}

Sipariş getir

Sipariş numarasıyla tek sipariş. Yoksa 404.

Yetki: orders:read

Parametre	Tür	Açıklama
number *	tam sayı (yol)	Sipariş numarası (ör. 1042).

Örnek yanıt

{
  "data": {
    "number": 1042,
    "status": "to_ship",
    "status_label": "Kargoya verilecek",
    "payment_method": "card",
    "source": "storefront",
    "channel": null,
    "external_id": null,
    "customer": {
      "name": "Ayşe Yılmaz",
      "email": "ayse@ornek.com",
      "phone": "+905321112233"
    },
    "shipping_address": {
      "name": "Ayşe Yılmaz",
      "phone": "+905321112233",
      "line1": "Bağdat Cad. 12/3",
      "district": "Kadıköy",
      "city": "İstanbul",
      "zip": "34710",
      "country": "TR"
    },
    "billing_address": null,
    "currency": "TRY",
    "subtotal_minor": 19990,
    "discount_minor": 0,
    "shipping_minor": 4990,
    "cod_fee_minor": 0,
    "tax_minor": 3332,
    "total_minor": 24980,
    "commission_minor": 0,
    "coupon_code": null,
    "items": [
      {
        "sku": "KUPA-MAVI",
        "title": "Seramik Kupa",
        "variant": "Mavi",
        "quantity": 1,
        "unit_price_minor": 19990,
        "total_minor": 19990,
        "tax_rate_bp": 2000
      }
    ],
    "delivery_method": "cargo",
    "delivery_date": null,
    "carrier": null,
    "tracking_number": null,
    "note": null,
    "created_at": "2026-11-12T13:40:00+03:00",
    "paid_at": "2026-11-12T13:41:00+03:00",
    "shipped_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "updated_at": "2026-11-12T13:41:00+03:00"
  }
}

POST/api/v1/orders/{number}/ship

Siparişi kargoya ver

Kargolanacak (to_ship) durumundaki siparişi kargoya verildi yapar, müşteriye kargo e-postası gider ve order.shipped webhook'u tetiklenir. Sipariş başka durumdaysa 422.

Yetki: orders:write

Parametre	Tür	Açıklama
number *	tam sayı (yol)	Sipariş numarası.
carrier	metin (en çok 64)	Kargo firması adı.
tracking_number	metin (en çok 64)	Takip numarası.

Örnek yanıt

{
  "data": {
    "number": 1042,
    "status": "shipped",
    "status_label": "Kargoda",
    "payment_method": "card",
    "source": "storefront",
    "channel": null,
    "external_id": null,
    "customer": {
      "name": "Ayşe Yılmaz",
      "email": "ayse@ornek.com",
      "phone": "+905321112233"
    },
    "shipping_address": {
      "name": "Ayşe Yılmaz",
      "phone": "+905321112233",
      "line1": "Bağdat Cad. 12/3",
      "district": "Kadıköy",
      "city": "İstanbul",
      "zip": "34710",
      "country": "TR"
    },
    "billing_address": null,
    "currency": "TRY",
    "subtotal_minor": 19990,
    "discount_minor": 0,
    "shipping_minor": 4990,
    "cod_fee_minor": 0,
    "tax_minor": 3332,
    "total_minor": 24980,
    "commission_minor": 0,
    "coupon_code": null,
    "items": [
      {
        "sku": "KUPA-MAVI",
        "title": "Seramik Kupa",
        "variant": "Mavi",
        "quantity": 1,
        "unit_price_minor": 19990,
        "total_minor": 19990,
        "tax_rate_bp": 2000
      }
    ],
    "delivery_method": "cargo",
    "delivery_date": null,
    "carrier": "Yurtiçi Kargo",
    "tracking_number": "123456789012",
    "note": null,
    "created_at": "2026-11-12T13:40:00+03:00",
    "paid_at": "2026-11-12T13:41:00+03:00",
    "shipped_at": "2026-11-13T10:15:00+03:00",
    "delivered_at": null,
    "cancelled_at": null,
    "updated_at": "2026-11-13T10:15:00+03:00"
  }
}

GET/api/v1/customers

Müşterileri listele

Müşteriler; verisi silinmiş (anonimleştirilmiş) kayıtlar gelmez.

Yetki: customers:read

Parametre	Tür	Açıklama
updated_since	tarih (ISO 8601)	Yalnız bu andan sonra güncellenen kayıtlar; artımlı çekim için.
per_page	tam sayı (1-200)	Sayfa başına kayıt; varsayılan 50.
page	tam sayı	Sayfa numarası; yanıttaki links.next ile ilerlenir.

Örnek yanıt

{
  "data": [
    {
      "id": 7,
      "name": "Ayşe Yılmaz",
      "email": "ayse@ornek.com",
      "phone": "+905321112233",
      "marketing_consent": true,
      "created_at": "2026-10-01T09:12:00+03:00"
    }
  ],
  "links": {
    "first": "…?page=1",
    "last": "…?page=3",
    "prev": null,
    "next": "…?page=2"
  },
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 128,
    "last_page": 3
  }
}

Yapay Zeka Bağlantısı (MCP)

Adres: POST https://<mağaza alan adı>/mcp (HTTP üzerinden MCP; sunucu adı 'tici', sürüm 1.0.0). REST API anahtarıyla aynı 'Authorization: Bearer tici_…' başlığı kullanılır. Araçlar anahtarın yetkisine göre listelenir; hepsi salt okunurdur.

urun-ara

Ürünleri ada, SKU ya da barkoda göre arar; varyant fiyatı (kuruş) ve stoğuyla döner. Arama boşsa son güncellenenler. Yetki: products:read.

Parametre	Tür	Açıklama
arama	metin (en çok 100)	Ürün adı, SKU ya da barkod.
stok_az	mantıksal	Yalnız mağazanın düşük stok eşiğindeki ürünler.
adet	tam sayı (1-50)	En çok kaç ürün; varsayılan 20.

siparisler

Siparişleri en yeniden eskiye listeler; duruma, tarihe ve müşteri adı/e-postasına göre süzer. Yetki: orders:read.

Parametre	Tür	Açıklama
durum	metin	Sipariş durumu: awaiting_payment, payment_review, to_ship, shipped, delivered, refunded, payment_failed, cancelled.
baslangic	tarih (YYYY-AA-GG)	Bu tarihten sonra verilenler.
bitis	tarih (YYYY-AA-GG)	Bu tarihe kadar verilenler.
musteri	metin (en çok 100)	Müşteri adı ya da e-postası.
adet	tam sayı (1-50)	En çok kaç sipariş; varsayılan 20.

siparis

Sipariş numarasıyla tek siparişin tüm ayrıntısı. Yetki: orders:read.

Parametre	Tür	Açıklama
numara *	tam sayı	Sipariş numarası (ör. 1042).

musteri-ara

Müşterileri ada, e-postaya ya da telefona göre arar; sipariş sayısı (orders_count) ve toplam harcamasıyla (spent_minor) döner. Arama boşsa son kayıt olanlar. Yetki: customers:read.

Parametre	Tür	Açıklama
arama	metin (en çok 100)	Ad, e-posta ya da telefon.
adet	tam sayı (1-50)	En çok kaç müşteri; varsayılan 20.

satis-ozeti

Tarih aralığında ciro, sipariş sayısı, ortalama sepet, ödeme yöntemi ve kanal dağılımı, en çok satan 10 ürün. Ciro ödenmiş ve iptal edilmemiş siparişlerden, ödeme gününe göre hesaplanır. Yetki: orders:read.

Parametre	Tür	Açıklama
baslangic	tarih (YYYY-AA-GG)	Varsayılan 30 gün önce.
bitis	tarih (YYYY-AA-GG)	Varsayılan bugün; başlangıçtan önce olamaz.

Webhook Olayları

Ayarlar › API bölümünden https adresi ve olaylar seçilerek eklenir. Her olayda adrese JSON POST gider. Başlıklar: X-Tici-Event (olay adı), X-Tici-Delivery (teslimat kimliği), X-Tici-Signature: sha256=<gövdenin webhook gizli anahtarıyla HMAC-SHA256'sı>, User-Agent: tici-webhooks/1. 15 saniyede 2xx dönmeyen teslimat 1 dk, 5 dk, 15 dk ve 1 saat sonra yeniden denenir; art arda 20 başarısız teslimatta webhook kapanır. Panelden gönderilen test 'ping' olayıdır.

Olay	Ne zaman	Gövde
order.placed	Sipariş verildi	Sipariş (GET /orders/{number} ile aynı alanlar)
order.paid	Ödeme alındı	Sipariş
order.shipped	Kargoya verildi	Sipariş
order.delivered	Teslim edildi	Sipariş
order.cancelled	İptal edildi	Sipariş
return.refunded	İade ödendi	{return: {number, refund_minor, reason}, order: Sipariş}
product.saved	Ürün kaydedildi	Ürün (GET /products/{product} ile aynı alanlar)
customer.created	Müşteri oluştu	Müşteri (id, name, email, phone, marketing_consent, created_at)

Örnek gövde

{
  "id": "0b8f6c1e-5d1a-4c57-9a43-2f1d6f0c9e11",
  "event": "order.paid",
  "created_at": "2026-11-12T13:41:00+03:00",
  "data": {
    "number": 1042,
    "status": "to_ship",
    "status_label": "Kargoya verilecek",
    "payment_method": "card",
    "source": "storefront",
    "channel": null,
    "external_id": null,
    "customer": {
      "name": "Ayşe Yılmaz",
      "email": "ayse@ornek.com",
      "phone": "+905321112233"
    },
    "shipping_address": {
      "name": "Ayşe Yılmaz",
      "phone": "+905321112233",
      "line1": "Bağdat Cad. 12/3",
      "district": "Kadıköy",
      "city": "İstanbul",
      "zip": "34710",
      "country": "TR"
    },
    "billing_address": null,
    "currency": "TRY",
    "subtotal_minor": 19990,
    "discount_minor": 0,
    "shipping_minor": 4990,
    "cod_fee_minor": 0,
    "tax_minor": 3332,
    "total_minor": 24980,
    "commission_minor": 0,
    "coupon_code": null,
    "items": [
      {
        "sku": "KUPA-MAVI",
        "title": "Seramik Kupa",
        "variant": "Mavi",
        "quantity": 1,
        "unit_price_minor": 19990,
        "total_minor": 19990,
        "tax_rate_bp": 2000
      }
    ],
    "delivery_method": "cargo",
    "delivery_date": null,
    "carrier": null,
    "tracking_number": null,
    "note": null,
    "created_at": "2026-11-12T13:40:00+03:00",
    "paid_at": "2026-11-12T13:41:00+03:00",
    "shipped_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "updated_at": "2026-11-12T13:41:00+03:00"
  }
}

Entegrasyonunuzu Birlikte Yayınlayalım

Uygulama geliştirici ve çözüm ortağı başvuruları bir hafta içinde yanıtlanır.

Ücretsiz Başlayın Paketleri İnceleyin

0850 307 11 17 · Hafta içi 09.00–18.00