Toptandepo ERP Entegrasyon API'si

Mağazalar kendi muhasebe programlarını (Logo Netsis / Logo Tiger) Toptandepo'ya bağlamak için müşteri sunucusuna küçük bir ajan kurar. Ajan yalnız dışa doğru HTTPS yapar; bu sayfa ajan ↔ bulut REST API'sini belgeler. Hazır ajan paketini mağaza panelindeki Dış ERP sayfasından indirebilirsiniz.

Genel

• Taban adres: https://register.ixirbilisim.com
• Kimlik: Her istek Authorization: Bearer başlığı taşır. Anahtar mağaza panelinden üretilir; her hesaba (mağazaya) özeldir.
• Biçim: İstek/yanıt gövdeleri JSON'dur (fatura yükleme hariç — multipart).
• Hata: Geçersiz/eksik anahtar → 401.
• İnkremental: Çekme uçları watermark (değişim kolonu) ile çalışır; daha önce çekilen tekrar çekilmez.

Uçlar

1. Heartbeat — POST /erp/agent/heartbeat

Ajanın canlı olduğunu ve sürümünü bildirir.

POST /erp/agent/heartbeat
{ "version": "1.0.0" }
→ { "ok": true, "server_time": "2026-05-30 12:00:00" }

2. Config — GET /erp/agent/config

Tablo/kolon eşleştirmelerini ve her varlığın son watermark'ını indirir.

GET /erp/agent/config
→ { "ok": true, "config": {
      "provider": "logo",
      "poll_interval": 120, "batch_size": 25,
      "mappings": [
        { "entity": "product", "table_name": "...", "custom_select": "SELECT ...",
          "watermark_column": "CAPIBLOCK_MODIFIEDDATE", "watermark_value": "2026-05-01 ...",
          "fields": [ { "odoo_field": "sku", "erp_column": "sku", "is_key": true, ... } ] },
        { "entity": "stock", ... }, { "entity": "invoice", ... }, { "entity": "order", ... }
      ] } }

3. Ürün gönder — POST /erp/agent/products/push

ERP'den çekilen ürünleri (varyant/stok dahil) batch olarak gönderir. Sunucu kuyruğa alır ve arka planda işler.

POST /erp/agent/products/push
{ "max_watermark": "2026-05-30 12:00:00",
  "items": [
    { "sku": "ABC-1", "name": "Ürün", "barcode": "869...", "price": 199.90,
      "vat": 20, "uom": "Adet", "description": "...", "category": "Giyim",
      "brand": "Marka", "stock": 25,
      "variants": [ { "attrs": {"Renk":"Kırmızı","Beden":"L"}, "barcode":"869...", "stock": 5 } ] }
  ] }
→ { "ok": true, "queued": 1 }

Alan anahtarları: sku, name, barcode, price, cost, site_price, stock, description, category, brand, vat, uom, image_data, images[], variants[]. image_data base64; images URL listesi.

4. Stok gönder — POST /erp/agent/stock/push

Hafif/sık stok güncellemesi (ürün üstverisi olmadan).

POST /erp/agent/stock/push
{ "items": [ { "sku": "ABC-1", "qty": 17 } ], "max_watermark": "..." }
→ { "ok": true, "applied": 1 }

5. Bekleyen siparişler — GET /erp/agent/orders/pending

ERP'ye yazılacak yeni siparişleri döndürür (yalnız yeni; durum güncelleme yok).

GET /erp/agent/orders/pending
→ { "ok": true, "orders": [
      { "outbox_id": 12, "external_ref": "TY-123", "channel": "trendyol",
        "partner": { "name": "...", "vat": "...", "city": "..." },
        "lines": [ { "sku": "ABC-1", "barcode": "...", "qty": 2, "price": 199.90, "vat": 20 } ] }
   ] }

6. Sipariş onayı — POST /erp/agent/orders/ack

Ajan, ERP'nin güvenli ara tablosuna yazdığı siparişleri onaylar.

POST /erp/agent/orders/ack
{ "acks": [ { "outbox_id": 12, "status": "written", "erp_ref": "SIP-9" } ] }
→ { "ok": true, "acked": 1 }

7. Fatura yükle — POST /erp/agent/invoice/upload (multipart)

ERP'de kesilen e-Faturayı (ETTN + PDF + opsiyonel UBL) yükler. Sunucu siparişe bağlar ve siparişin geldiği kanala (Trendyol/N11) iletir; storefront siparişinde müşteri portalda görür.

POST /erp/agent/invoice/upload   (Content-Type: multipart/form-data)
fields: ettn, invoice_number, order_external_ref, invoice_date, channel
files:  pdf (zorunlu), ubl (opsiyonel)
→ { "ok": true, "invoice_id": 5, "state": "distributed" }

Performans — sunucuyu yormaz

• Kilitlemez okuma (READ UNCOMMITTED) — ERP'nin canlı işlemlerini bloklamaz, kullanıcıları etkilemez.
• Kademeli ilk yükleme — büyük katalog tek hamlede değil, tur başına sınırlı satır (varsayılan 2000) olacak şekilde birçok tura yayılır.
• Akışlı + inkremental — satırlar parça parça okunur (sabit RAM); ilk turdan sonra yalnız değişenler, stok yalnız hareket gören ürünler için çekilir.
• Adaptif yavaşlama + throttle — değişiklik yoksa aralık uzar; parçalar arası kısa duraklama IO/CPU'yu nazik kullanır. config.ini → [performance]/[schedule] ile ayarlanır.

Güvenlik

• Tüm trafik TLS (HTTPS) üzerinden; ajan yalnız giden bağlantı kurar.
• ERP çekirdek tablolarına yazma yoktur; sipariş yalnız özel ara tabloya eklenir.
• MSSQL kimliği yalnız ajanda tutulur (bulut bilmez); ajan anahtarı sızarsa panelden döndürülür.

Mağaza Panelinde Aç