Heyşirket Senkron API v1

Heyşirket Senkron API; e-ticaret sitenizin, pazaryeri yazılımınızın, ERP ya da ön muhasebe sisteminizin cari, ürün (renk/beden varyantları ve görselleriyle), stok, satış faturası, gider/gelen e-fatura, kasa-banka hareketi ve e-ticaret siparişlerini Heyşirket'teki firmanıza otomatik aktarmasını; Heyşirket'te yapılan değişiklikleri (stok, fiyat, yeni varyant, tahsilat, sipariş işlemi…) de geri okumasını sağlar.

• Taban adres: https://portal.heysirket.com/api/v1
• Makine tarafından okunur tanım: /api/v1/openapi.json · sınırlar ve sabitler: /api/v1/meta
• Bu sayfanın ham hali (yapay zekâ araçları için): /gelistiriciler/senkron-api.md

Yapay zekâ ile entegrasyon (hazır prompt)

Aşağıdaki metni olduğu gibi kopyalayıp kullandığınız yapay zekâ kodlama asistanına (Claude, ChatGPT, Cursor vb.) verin. Köşeli parantezli yerleri kendi bilgilerinizle doldurun. API anahtarını prompta yazmayın; asistandan anahtarı ortam değişkeninden (HEYSIRKET_API_KEY) okumasını isteyin.

Sen kıdemli bir entegrasyon mühendisisin. Görevin: [SİSTEM ADI — ör. WooCommerce mağazam / kendi
e-ticaret yazılımım / ERP'm] ile Heyşirket arasında kesintisiz, çift yönlü ve güvenli bir senkron kurmak.

Kaynaklar (önce tamamını oku, varsayım yapma):
- Rehber: https://heysirket.com/gelistiriciler/senkron-api.md
- OpenAPI: https://portal.heysirket.com/api/v1/openapi.json
- Sınırlar/sabitler: https://portal.heysirket.com/api/v1/meta

Bağlam:
- Heyşirket firmamın API anahtarı HEYSIRKET_API_KEY ortam değişkeninde. Anahtarı asla loglama, koda,
  depoya veya hata mesajına yazma.
- Kaynak sistemim: [dil/çatı, veritabanı, barındırma — ör. PHP 8 + WordPress/WooCommerce, MySQL, cPanel cron].
- Sistemimdeki kalıcı kod (source): [ör. magazam] — küçük harf, rakam, tire.
- Satış kanallarım: [ör. kendi sitem (woocommerce), trendyol, hepsiburada].
- E-fatura sağlayıcım: [ör. Trendyol E-Faturam / yok].

Yapacakların (sırayla, her adımı test ederek):
1. Veri eşlemesi çıkar: sistemimdeki her varlığı (müşteri, tedarikçi, ürün + varyant + görsel, stok, sipariş,
   fatura, iade/iptal, gider, gelen e-fatura, ödeme/tahsilat) rehberdeki alanlara eşle. Kalıcı ve
   değişmeyen kimlikleri externalId yap. Tutarları ana para biriminde ondalık, KDV'yi yüzde gönder.
   Varyantlı ürünlerde yalnız satılabilir varyantları products[] olarak, ana ürünü family ile gönder;
   attributes'a renk/beden gibi özellikleri insan okunur adlarla yaz. Görselleri https adresleriyle gönder.
2. Değişiklik takibi kur: her varlık için "son değişiklik zamanı/sürümü" imleci ve gönderilen kaydın
   parmak izini sakla; yalnız değişenleri gönder. Hiçbir şey değişmediyse istek atma.
3. Gönderimi kur: POST /sync ile sayfalı gönder (istek başına ≤400 kayıt, fatura+gider+sipariş ≤150,
   gövde ≤2 MB). Sıra: business → customers → products(+family) → stock → orders → invoices → expenses
   → transactions → deleted (tedarikçiler suppliers[] ile, customers'tan önce ya da aynı sayfada).
   Önce aynı veriyi ?dryRun=1 ile gönderip errors boşalana kadar eşlemeyi düzelt.
4. Hata yönetimi: 200 yanıtındaki errors[] kayıt bazlıdır; ilgili kaydı düzeltip tekrar gönder
   (aynı sayfayı tekrar göndermek güvenlidir, idempotenttir). 429'da Retry-After kadar bekle
   (DAILY_QUOTA: ertesi UTC gününe kadar, kalan kayıtları sıraya koy). 5xx ve ağ hatasında üstel geri
   çekilme uygula; 401/402/423'te dur ve yöneticiyi uyar.
5. Geri akışı kur: her turda ÖNCE GET /changes?after=<son seq> ile Heyşirket'teki değişiklikleri oku ve
   kendi sistemine uygula (stok için quantity'yi FARK olarak uygula, IN +, OUT −, ADJUSTMENT işaretli),
   sonra kendi değişikliklerini gönder. Uygulanan son seq'i kalıcı sakla. Heyşirket'te yeni açılan
   ürün/varyant/ailede kendi kaydını oluştur ve bir sonraki gönderimde heysirketId ile eşle.
6. Zamanlama: değişiklik akışı ve gönderim için 15 dakikada bir çalışan tek, kilitli bir görev kur.
   İlk tam aktarımı elle başlatılabilir ve kaldığı yerden devam edebilir yap; günlük kotayı aşarsa ertesi
   gün devam etsin.
7. Gözlemlenebilirlik: son çalışma zamanı, gönderilen/hatalı kayıt sayıları ve son hataları sisteminin
   yönetim ekranında göster. GET /sync/runs ile Heyşirket tarafındaki sonucu karşılaştır.
8. Test: eşleme fonksiyonları için birim testleri yaz (tutar yuvarlama, satır toplamlarının fatura
   toplamına eşitliği, varyant/aile eşlemesi, silinen kayıtlar, akış olaylarının uygulanması). Önce
   ?dryRun=1, sonra küçük bir gerçek sayfa ile uçtan uca doğrula; GET /ping ile anahtarı kontrol et.

Kurallar: Para hesaplarında kuruşa dikkat et; aynı parayı iki kez sayma (bir tahsilat ya fatura ödemesi
ya da kasa hareketi olarak gelsin). Faturaları silme, iptali status: "CANCELLED" ile bildir. Kişisel
verileri yalnız rehberdeki alanlarla gönder. Bitince yaptığın eşlemeyi ve çalıştırma talimatını kısa bir
README olarak yaz.

Hızlı başlangıç

1. Anahtar oluşturun. Heyşirket → Ayarlar → API ve senkron → Anahtar oluştur. Anahtar (hsk_live_…) yalnız bir kez gösterilir; güvenli bir yerde saklayın. Her sistem için ayrı anahtar açın.
2. Bağlantıyı test edin.
   Kopyala

   curl -s https://portal.heysirket.com/api/v1/ping -H "Authorization: Bearer $HEYSIRKET_API_KEY"

3. Önce doğrulayın, sonra yazın. Aynı gövdeyi ?dryRun=1 ile gönderin; errors boşsa parametreyi kaldırın.
   Kopyala

   curl -s -X POST "https://portal.heysirket.com/api/v1/sync?dryRun=1" \
     -H "Authorization: Bearer $HEYSIRKET_API_KEY" -H "Content-Type: application/json" \
     -d '{"source":"magazam","customers":[{"externalId":"c-1","title":"Ayşe Yılmaz"}]}'

4. Sonucu görün. Heyşirket'te Ayarlar → API ve senkron ekranında her aktarımın sayıları ve kayıt bazlı hataları görünür.

Kimlik doğrulama ve sınırlar

Authorization: Bearer hsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Genel kurallar

• İdempotent upsert: Aynı source + externalId ile gelen kayıt güncellenir, çoğaltılmaz. Ağ hatasında aynı sayfayı tekrar göndermek güvenlidir.
• Birimler: tutarlar ana para biriminde ondalık (149.90), KDV oranı yüzde (20), miktar ondalık (1.5), tarihler YYYY-MM-DD ya da ISO-8601.
• source: sisteminizin kalıcı kodu (^[a-z0-9][a-z0-9_-]{1,39}$). Aynı firmaya birden çok sistem farklı source ile veri gönderebilir.
• Tam nesne: her kaydı tam gönderin; gönderilmeyen alan boş kabul edilir. İstisna: business nesnesinde yalnız dolu alanlar yazılır.
• Sıra: aynı istek içinde siparişler faturalardan önce işlenir; aileler varyantlardan önce oluşur.
• Yalnız değişenleri gönderin: hiçbir şey değişmediyse istek atmayın; kota ve hız sınırı tüm firmaların ortak altyapısını korur.

Gövde

{
  "source": "magazam",
  "business": { "title": "…", "taxId": "…", "taxOffice": "…", "address": "…", "district": "…", "city": "…", "phone": "…", "email": "…",
                "bankAccounts": [ { "bankName": "Ziraat Bankası", "branchName": "Merkez", "accountName": "…", "iban": "TR…", "currency": "TRY", "isDefault": true } ] },
  "customers": [ /* Cari */ ],
  "suppliers": [ /* Tedarikçi */ ],
  "products": [ /* Ürün / varyant */ ],
  "stock": [ /* Stok seviyesi */ ],
  "orders": [ /* E-ticaret siparişi */ ],
  "invoices": [ /* Satış faturası */ ],
  "expenses": [ /* Gider / gelen fatura */ ],
  "transactions": [ /* Kasa-banka hareketi */ ],
  "deleted": { "customers": [], "suppliers": [], "products": [], "expenses": [], "transactions": [] }
}

Firma (business)

Yalnız dolu alanlar yazılır. bankAccounts[] (en fazla 10): IBAN ile eşlenir; hesap hem faturalarda gösterilen banka hesaplarına hem de Nakit ve bankalar takibine eklenir. isDefault: true olan hesap faturalarda ilk sırada gösterilir.

Cari (customers[])

Tedarikçi (suppliers[])

Heyşirket'te aynı vergi numaralı ya da aynı unvanlı (büyük/küçük harf, Türkçe karakter duyarsız) bir tedarikçi zaten varsa yenisi açılmaz, mevcut kart eşlenir. customers[] içinde contactType: "supplier" ya da "both" olan kayıtlar da tedarikçi kartı olarak yazılır. Her gider (expenses[]) tedarikçisine supplierExternalId → supplierTaxId → supplierName sırasıyla bağlanır; bulunamazsa tedarikçi kartı otomatik açılır. Böylece tedarikçi ekstreleri ve borç bakiyeleri Heyşirket'te kendiliğinden oluşur.

Ürün ve varyant (products[])

Varyantlı ürünlerde yalnız satılabilir varyantlar products[] olarak gönderilir; ana ürün family ile tanımlanır. Heyşirket'te aile tek satırda görünür, varyantlar tek pencerede düzenlenir.

Stok seviyesi (stock[])

{ "productExternalId": "123", "quantity": 7, "warehouse": { "code": "ANA", "name": "Ana depo" } } — mutlak miktar gönderilir; Heyşirket farkı sayım düzeltmesi olarak stok defterine yazar. warehouse gönderilmezse varsayılan depo (yoksa ANA) kullanılır.

Satış faturası (invoices[])

Gider / gelen fatura (expenses[])

Kasa-banka hareketi (transactions[])

{ "externalId": "…", "direction": "INFLOW"|"OUTFLOW", "amount": 120.5, "currency": "TRY", "date": "2026-10-01", "description": "…", "counterparty": "…", "account": { "externalId": "iyzico", "name": "iyzico", "type": "BANK"|"CASH" }, "expenseExternalId": "…" } — fatura tahsilatlarını burada tekrar göndermeyin (invoices[].payments yeterlidir).

E-ticaret siparişi (orders[])

Silme (deleted)

externalId listeleriyle bildirilir: cari, tedarikçi ve ürün pasife alınır (geçmiş korunur); bu kaynaktan gelen gider ve kasa-banka hareketi silinir. Faturalar silinmez; status: "CANCELLED" gönderin.

Yanıt ve hata kodları

{
  "ok": true,
  "runId": "…",
  "stats": { "customers": { "created": 3, "updated": 10 }, "products": { "created": 2, "updated": 40 } },
  "errors": [ { "type": "products", "externalId": "55", "code": "DUPLICATE_SKU", "message": "Bu stok kodu (SKU) firmada başka bir ürüne ait." } ]
}

Bir kaydın hatası diğerlerini durdurmaz. Mesajlar Türkçedir ve kullanıcıya gösterilebilir.

Değişiklik akışı (Heyşirket → sizin sisteminiz)

GET /api/v1/changes?after=<seq>&limit=200[&types=inventory.movement,product.updated]

{ "events": [ { "seq": 41, "type": "inventory.movement", "entityType": "inventory_movement", "entityId": "…", "createdAt": "2026-10-13 09:12:00",
    "data": { "productExternalProvider": "api:magazam", "productExternalId": "123", "sku": "S1", "direction": "IN", "quantity": 5, "warehouseCode": "ANA" } } ],
  "next": 41, "hasMore": false }

Akışa yalnız Heyşirket'te yapılan değişiklikler düşer; bu API ile yazılanlar geri yansıtılmaz (döngü oluşmaz). next değerini saklayın ve sonraki çağrıda after olarak gönderin; hasMore: true ise hemen tekrar çağırın. Kendi kayıtlarınızı externalProvider = api:<source> olanlarla eşleyin.

Uygulama sırası: her turda önce akışı okuyup uygulayın, sonra kendi değişikliklerinizi gönderin. Heyşirket'te açılan ürün/varyant/aile için kendi kaydınızı oluşturun ve bir sonraki gönderimde heysirketId ile eşleyin. Stok olaylarını fark olarak uygulayın; sonra mutlak stok gönderdiğinizde Heyşirket sıfır fark görür.

Entegrasyon kontrol listesi

• Her sistem için ayrı anahtar; anahtar yalnız ortam değişkeninde.
• GET /ping başarılı.
• Tüm sayfalar ?dryRun=1 ile hatasız.
• İlk aktarım sayfalı, kaldığı yerden devam edebiliyor, günlük kotaya uyuyor.
• Yalnız değişen kayıtlar gönderiliyor (parmak izi / değişiklik zamanı).
• Fatura satırlarının toplamı fatura toplamına eşit; iptaller CANCELLED.
• Varyantlar family + attributes ile, görseller https.
• Akış önce okunuyor, stok fark olarak uygulanıyor, next kalıcı saklanıyor.
• 429'da Retry-After'a uyuluyor, 5xx'te geri çekiliyor.
• Yönetim ekranınızda son çalışma ve hatalar görünüyor; Heyşirket'te Ayarlar → API ve senkron ile karşılaştırıldı.

Sık sorulanlar

Aynı kaydı iki kez gönderirsem ne olur? Güncellenir; kopya oluşmaz.

Pazaryeri faturalarım gecikmiş görünüyor. dueDate olarak beklenen hakediş tarihini, ödendiğinde de payments[] ile tahsilatı gönderin.

Ürünlerim Heyşirket'te tek tek görünüyor. Varyantları family ve attributes ile gönderin; aile tek satırda toplanır.

Heyşirket'te stok girdim, sistemime nasıl gelir? GET /changes akışındaki inventory.movement olayını fark olarak uygulayın.

Büyük kataloğum var. İlk aktarım günlük kotaya göre birkaç güne yayılır; DAILY_QUOTA aldığınızda kalan kayıtları ertesi gün gönderin.