1. Aktif kurulumları uzlaştırın
GET /api/v1/app/installations?limit=100\nAuthorization: Bearer <APP_KEY>
Yalnız uygulamanızın aktif kurulumlarını cursor sayfalamasıyla alın. Webhook yeniden denense veya kaçırılsa bile bu endpoint telafi noktasıdır.
Tek entegrasyon, iki senkron yolu
Webhook değişiklikleri anlık iletir. Polling ise ilk aktarımı, kaçırılan teslimatları ve cursor sonrası değişiklikleri tamamlar. Her uygulama kurulumu kendi domain_id alanına bağlıdır.
Ortamlar ve kimlik doğrulama
Stage: https://stage-integration.tica.tr
Production: https://integration.tica.tr
Kimlik doğrulama: kurulumunuza tanımlı Bearer client key
Kurulum bootstrap
Kurulum webhook’u ile polling’i başlatın
Domain yöneticisi uygulamayı etkinleştirdiğinde installation.enabled gelir. Ayar veya onaylı izin değişikliklerinde installation.updated, bağlantı kaldırıldığında installation.revoked gelir. Bu olaylar kaynak verisi değil, uygulamanızın aktif domain kurulumlarını uzlaştırma sinyalidir.
2. Kurulum bağlı token alın
POST /api/v1/app/installations/{installation_id}/access-token\nAuthorization: Bearer <APP_KEY>10 dakikalık kurulum-bağlı access token, yalnız ilgili domain_id ve onaylı scope’larla Resource API çağırabilir.
3. Kaynakları cursor ile çekin
GET /api/v1/resources/orders?cursor=<next_cursor>\nAuthorization: Bearer <INSTALLATION_ACCESS_TOKEN>
İlk senkron ve artımlı polling aynı koleksiyon endpoint’i ve next_cursor üzerinden yürür.
Başlamadan önce
Uygulama başvuru ve ön gereksinimleri
Yeni bir Tica uygulaması için bilgilerinizi gönderin. Başvuru incelendikten sonra uygulama kaydı, webhook imzalama secret’ı ve uygun scope’lar tanımlanır.
- HTTPS ile erişilebilen bir webhook URL’i ve hızlı bir 2xx yanıtı hazırlayın.
- Ham gövdeyi HMAC ile doğrulayın;
delivery_idalanını idempotent işleyin. - Polling’i yalnızca sunucu/worker üzerinden çağırın; client key’i tarayıcı veya mobil uygulamaya koymayın.
- Stage ve production secret’larını, kurulumlarını ve yerel verilerini birbirinden ayırın.
Webhook olayları
Şema sürümü: 1. Her teslimat ortak zarf alanlarını içerir: delivery_id, event_id, event_name, installation_id, domain_id, aggregate_type, aggregate_id, aggregate_version, occurred_at ve payload.
Kurulum yaşam döngüsü
installation.enabledinstallation.updatedinstallation.revokedKurulum/domain kimliği, durum, onaylı scope ve event’ler ile changed_fields gelir. Credential ve ham ayar değerleri gönderilmez.
Sipariş
order.createdorder.updatedNumara, müşteri ve adres, durum/ödeme, tutarlar ve order_products satırları.
Ürün
product.createdproduct.updatedproduct.deletedAd, açıklama, fiyat, SKU/barkod, KDV, uygunluk, görsel, kategori ve marka verisi.
Ürün varyantı
product_variant.createdproduct_variant.updatedproduct_variant.deletedÜrün bağlantısı, seçenekler, SKU/barkod, fiyat, görsel, aktiflik ve stok takibi.
Stok
stock.createdstock.updatedstock.deletedÜrün/varyant, şube, miktar, rezerve miktar, sınırsız stok ve eşik bilgileri.
Kullanıcı
user.createduser.updateddomain_id ile ilişkilendirilmiş kullanıcı profil alanları; hassas kimlik doğrulama alanları gönderilmez.
Genişletilmiş entegrasyon
order.status_changedorder.payment_updatedorder.cancelledorder.refundedorder.deliveredstock.adjustedcategory.*brand.*campaign.*coupon.*customer.*return_request.*invoice.createdshipment.*Değişim eventleri changed_fields ve uygun olduğunda güvenli previous_values taşır.
Olaylar en az bir kez teslim edilir. İmzayı ham gövde üzerinden doğrulayın,
delivery_id için benzersiz kayıt oluşturun ve güvenle kuyruğa aldıktan sonra 2xx dönün.Kurulum yapılandırması
Domain ayarlarını ve erişim anahtarını kullanma
Uygulama yöneticisi, Dashboard’daki Entegrasyon Ayarları ekranından uygulamanın tanımladığı text, boolean ve selection alanlarını doldurur. Değerler uygulama genelinde değil, her aktif domain kurulumu için ayrı tutulur.
1. Client key’i güvenle saklayın
Kurulum oluşturulurken verilen installation client key yalnızca bir kez gösterilir. Uygulamanın sunucu tarafı secret store’unda saklayın; tarayıcı, mobil istemci, webhook gövdesi veya loglara koymayın.
2. Ayarları çalışma anında çekin
Uygulama sunucunuz, kendi kurulum anahtarıyla aşağıdaki endpoint’i çağırır. Anahtar yalnızca bağlı olduğu aktif kuruluma ait değerleri döndürür; domain_id istekle seçilemez.
GET /api/v1/app/settings\nAuthorization: Bearer <installation-client-key>
3. Anahtar yenileme
Kaybolan veya sızdığı düşünülen anahtar için operatör kurulum client key’ini yeniler. Yeni değer yine yalnız bir kez verilir; uygulama secret store’unu güncelledikten sonra eski anahtarı kullanmayı bırakın.
Örnek response · 200 OK
{"app_slug":"logo-erp","installation_id":"install_...","domain_id":42,"settings":{"api_key":"customer-api-key","secret_code":"customer-secret","environment":"production","auto_send_orders":true}}Bu endpoint kaynak polling izni gerektirmez; yine de client key hassas bir credential’dır. Ayar şemasındaki alan isimleri uygulama başvurusunda tanımlanır, seçim alanları yalnız izin verilen seçeneklerden birini kabul eder.
Webhooklar
Olayı soldan seçin. Sağda uygulamanıza yapılan gerçek request body ve webhook alıcınızın döndürmesi gereken response koşulu ayrı gösterilir.
installation.enabled
{"delivery_id":"delivery_...","event_id":"event_...","event_name":"installation.enabled","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"aggregate_type":"installation","aggregate_id":"installation_...","aggregate_version":1760000000000000000,"occurred_at":"2026-07-26T10:00:00Z","payload":{"installation_id":"installation_...","domain_id":42,"status":"active","changed_fields":["status","settings"]}}installation.updated
{"delivery_id":"delivery_...","event_id":"event_...","event_name":"installation.updated","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"aggregate_type":"installation","aggregate_id":"installation_...","aggregate_version":1760000000000000001,"occurred_at":"2026-07-26T10:05:00Z","payload":{"installation_id":"installation_...","domain_id":42,"status":"active","changed_fields":["settings"]}}installation.revoked
{"delivery_id":"delivery_...","event_id":"event_...","event_name":"installation.revoked","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"aggregate_type":"installation","aggregate_id":"installation_...","aggregate_version":1760000000000000002,"occurred_at":"2026-07-26T10:10:00Z","payload":{"installation_id":"installation_...","domain_id":42,"status":"revoked","changed_fields":["status"]}}order.created
{"delivery_id":"delivery_...","event_id":"...","event_name":"order.created","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"order","aggregate_id":"...","aggregate_version":1,"occurred_at":"2026-07-26T10:00:00+03:00","payload":{"order_id":"...","order_number":"1001","domain_id":42,"user_id":9,"status":"PENDING","payment_status":"PENDING","order_type":"DELIVERY","order_platform":"WEB","delivery_fee":20.0,"discount_price":0.0,"final_price":120.0,"coupon_info":{},"order_products":[{"product_id":"...","variant_id":"...","sku":"KHV-250","quantity":2,"unit_price":50.0,"total_price":100.0,"extras_price":0.0,"option_values":{},"variant_option_values":{},"extras":[],"removals":[]}],"aggregate_version":1,"created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:00:00+03:00","id":"..."}}order.updated
{"delivery_id":"delivery_...","event_id":"...","event_name":"order.updated","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"order","aggregate_id":"...","aggregate_version":2,"occurred_at":"2026-07-26T10:05:00+03:00","payload":{"order_id":"...","order_number":"1001","domain_id":42,"status":"PREPARING","payment_status":"SUCCESS","payment_method":"credit_card","final_price":120.0,"order_products":[],"aggregate_version":2,"created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:05:00+03:00","id":"..."}}order.status_changed
{"delivery_id":"delivery_...","event_id":"...","event_name":"order.status_changed","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"aggregate_type":"order","aggregate_id":"...","aggregate_version":3,"occurred_at":"2026-07-26T10:10:00Z","payload":{"order_id":"...","order_number":"1001","domain_id":42,"status":"SHIPPED","changed_fields":["status"],"previous_values":{"status":"PREPARING"},"aggregate_version":3,"updated_at":"2026-07-26T10:10:00Z"}}order.payment_updated
{"delivery_id":"delivery_...","event_id":"...","event_name":"order.payment_updated","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"aggregate_type":"order","aggregate_id":"...","aggregate_version":4,"occurred_at":"2026-07-26T10:11:00Z","payload":{"order_id":"...","order_number":"1001","domain_id":42,"payment_status":"SUCCESS","payment_method":"credit_card","changed_fields":["payment_status"],"previous_values":{"payment_status":"PENDING"},"aggregate_version":4,"updated_at":"2026-07-26T10:11:00Z"}}product.created
{"delivery_id":"delivery_...","event_id":"...","event_name":"product.created","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"product","aggregate_id":"...","aggregate_version":1,"occurred_at":"2026-07-26T10:00:00+03:00","payload":{"name":"Filtre Kahve","slug":"filtre-kahve","domain_id":42,"description":"250 g","base_price":50.0,"b2b_price":null,"discount_price":0.0,"original_price":0.0,"increment_factor":1.0,"weight":1.0,"barcode":null,"product_code":"KHV","buy_price":0.0,"kdv":20.0,"price_without_vat":0.0,"brand_id":null,"is_available":true,"availability_override":null,"images":[],"meta":{},"option_groups":[],"category_ids":[],"variant_count":0,"default_variant_id":null,"created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:00:00+03:00","id":"..."}}product.updated
{"delivery_id":"delivery_...","event_id":"...","event_name":"product.updated","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"product","aggregate_id":"...","aggregate_version":2,"occurred_at":"2026-07-26T10:05:00+03:00","payload":{"name":"Filtre Kahve","slug":"filtre-kahve","domain_id":42,"base_price":55.0,"discount_price":0.0,"is_available":true,"images":[],"category_ids":[],"variant_count":1,"created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:05:00+03:00","id":"..."}}product.deleted
{"delivery_id":"delivery_...","event_id":"...","event_name":"product.deleted","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"product","aggregate_id":"...","aggregate_version":2,"occurred_at":"2026-07-26T10:10:00+03:00","payload":{"name":"Filtre Kahve","slug":"filtre-kahve","domain_id":42,"base_price":55.0,"is_available":true,"category_ids":[],"created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:05:00+03:00","id":"..."}}product_variant.created
{"delivery_id":"delivery_...","event_id":"...","event_name":"product_variant.created","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"product_variant","aggregate_id":"...","aggregate_version":1,"occurred_at":"2026-07-26T10:00:00+03:00","payload":{"product_id":"...","domain_id":42,"option_values":{"size":"250 g"},"title":"250 g","sku":"KHV-250","barcode":null,"price":50.0,"buy_price":null,"kdv":null,"b2b_price":null,"b2b_only":false,"compare_at_price":null,"cost":null,"image":null,"images":[],"is_active":true,"stock_tracking":true,"pack_size":1,"stock_anchor_variant_id":null,"option_signature":"","created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:00:00+03:00","id":"..."}}product_variant.updated
{"delivery_id":"delivery_...","event_id":"...","event_name":"product_variant.updated","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"product_variant","aggregate_id":"...","aggregate_version":1,"occurred_at":"2026-07-26T10:05:00+03:00","payload":{"product_id":"...","domain_id":42,"option_values":{"size":"250 g"},"title":"250 g","sku":"KHV-250","price":55.0,"images":[],"is_active":true,"stock_tracking":true,"pack_size":1,"option_signature":"","created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:05:00+03:00","id":"..."}}product_variant.deleted
{"delivery_id":"delivery_...","event_id":"...","event_name":"product_variant.deleted","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"product_variant","aggregate_id":"...","aggregate_version":1,"occurred_at":"2026-07-26T10:10:00+03:00","payload":{"product_id":"...","domain_id":42,"option_values":{"size":"250 g"},"title":"250 g","sku":"KHV-250","price":55.0,"images":[],"is_active":true,"stock_tracking":true,"pack_size":1,"created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:05:00+03:00","id":"..."}}stock.created
{"delivery_id":"delivery_...","event_id":"...","event_name":"stock.created","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"stock","aggregate_id":"...","aggregate_version":1,"occurred_at":"2026-07-26T10:00:00+03:00","payload":{"variant_id":"...","branch_id":1,"domain_id":42,"quantity":10,"reserved":0,"is_unlimited":false,"low_stock_threshold":10,"created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:00:00+03:00","id":"..."}}stock.updated
{"delivery_id":"delivery_...","event_id":"...","event_name":"stock.updated","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"stock","aggregate_id":"...","aggregate_version":1,"occurred_at":"2026-07-26T10:05:00+03:00","payload":{"variant_id":"...","branch_id":1,"domain_id":42,"quantity":7,"reserved":2,"is_unlimited":false,"low_stock_threshold":10,"created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:05:00+03:00","id":"..."}}stock.deleted
{"delivery_id":"delivery_...","event_id":"...","event_name":"stock.deleted","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"stock","aggregate_id":"...","aggregate_version":1,"occurred_at":"2026-07-26T10:10:00+03:00","payload":{"variant_id":"...","branch_id":1,"domain_id":42,"quantity":7,"reserved":2,"is_unlimited":false,"low_stock_threshold":10,"created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:05:00+03:00","id":"..."}}stock.adjusted
{"delivery_id":"delivery_...","event_id":"...","event_name":"stock.adjusted","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"aggregate_type":"stock","aggregate_id":"...","aggregate_version":2,"occurred_at":"2026-07-26T10:12:00Z","payload":{"id":"...","domain_id":42,"variant_id":"...","branch_id":1,"previous_quantity":10,"quantity":7,"quantity_delta":-3,"reason":"order_reserved","reference_type":"order","reference_id":"...","changed_fields":["quantity"],"previous_values":{"quantity":10},"updated_at":"2026-07-26T10:12:00Z"}}category.updated
{"delivery_id":"delivery_...","event_id":"...","event_name":"category.updated","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"aggregate_type":"category","aggregate_id":"...","aggregate_version":2,"occurred_at":"2026-07-26T10:13:00Z","payload":{"id":"...","domain_id":42,"name":"Filtre Kahveler","slug":"filtre-kahveler","parent_id":null,"sort_order":2,"changed_fields":["name","sort_order"],"previous_values":{"name":"Kahveler","sort_order":1},"updated_at":"2026-07-26T10:13:00Z"}}user.created
{"delivery_id":"delivery_...","event_id":"...","event_name":"user.created","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"user","aggregate_id":"9","aggregate_version":1760000000000000000,"occurred_at":"2026-07-26T10:00:00+03:00","payload":{"id":9,"email":"[email protected]","phone":"905551112233","first_name":"Ayşe","last_name":"Yılmaz","domain_id":42,"is_active":true,"is_verified":true,"is_superuser":false,"b2b":false,"branch_id":null,"allowed_menus":[],"meta":{},"lid":null,"created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:00:00+03:00"}}user.updated
{"delivery_id":"delivery_...","event_id":"...","event_name":"user.updated","schema_version":1,"app_slug":"my-app","installation_id":"installation_...","domain_id":42,"domain":"","aggregate_type":"user","aggregate_id":"9","aggregate_version":1760000000000000001,"occurred_at":"2026-07-26T10:05:00+03:00","payload":{"id":9,"email":"[email protected]","phone":"905551112233","first_name":"Ayşe","last_name":"Demir","domain_id":42,"is_active":true,"is_verified":true,"is_superuser":false,"b2b":false,"branch_id":null,"allowed_menus":[],"meta":{},"lid":null,"created_at":"2026-07-26T10:00:00+03:00","updated_at":"2026-07-26T10:05:00+03:00"}}Pollingler
Kaynağı soldan seçin. Sağda ilk senkron (oluşturulmuş kayıtlar) ve cursor ile artımlı senkron (güncellenen kayıtlar) için ayrı request ve gerçek koleksiyon zarfındaki response örnekleri görünür.
Her çağrıda
Authorization: Bearer <installation-client-key> gönderin. Polling, yeni ve güncellenmiş kayıtları ayrı endpointlerle değil, next_cursor ile ilerleyen aynı koleksiyon üzerinden taşır; cursor aynı zaman damgasındaki kayıtları (updated_at,id) ile ayırır. Bir kaydı domain_id + id ile idempotent birleştirin.Standart çalışma akışı
Önce development’ta doğrulayın, sonra production’a alın
Uygulama kaydı ile müşterinin domain kurulumu farklı işlemlerdir. Geliştirici uygulamayı stage ortamında test eder; production uygulaması yayınlandığında her domain yöneticisi kendi Dashboard’undan bağlantıyı ayrıca onaylar.
- Development uygulamasını oluşturun.Webhook URL’i, istenen scope’lar, event’ler ve müşteri ayar şemasını başvuru modalından iletin. Development uygulaması yalnız izin verilen test domainlerinde görünür.
- Stage’de uçtan uca test edin.Webhook HMAC doğrulamasını, idempotent teslimat kaydını, cursor polling’i ve kısa ömürlü access token ile Resource API erişimini test edin. Stage credential’larını production ile asla paylaşmayın.
- Production kaydını tamamlayın.Test kabulünden sonra uygulama production olarak yayınlanır ve Integration Market’te tüm domainlere görünür. App key ve signing secret yalnız uygulamanın sunucu tarafı secret manager’ında tutulur.
- Domain yöneticisi Dashboard’dan etkinleştirir.Yönetici istenen izinleri onaylar ve uygulama ayarlarını girer. Hub
installation.enabledgönderir; uygulamanız kendi app key’iyle kurulumu uzlaştırır ve gerektiğinde 10 dakikalık kurulum-bağlı access token alır. - İşletin ve uzlaştırın.Ayar değişikliklerinde
installation.updated, bağlantı kesildiğindeinstallation.revokedgelir. Webhook’ları hızlıca kuyruklayın; kaçırılan değişiklikleri cursor polling ile tamamlayın.