Tecof

Tecof Uygulamaları ve Entegrasyonlar

Tecof uygulama entegrasyonu iki ayrı yüzeye ayrılır: satıcı panelinde çalışan JWT korumalı yönetim API'leri ve canlı mağazanın kullandığı secret-key korumalı storefront API'leri.

Mevcut kodda doğrulanan entegrasyon modeli REST tabanlıdır. OAuth 2.0 ve GraphQL, bu kod tabanında aktif public contract olarak görünmediği için bu dokümanda ana akış olarak anlatılmaz.

Entegrasyon Katmanları

Merchant Admin API

Satıcı panelindeki kaynaklar /api/merchant/* altında bulunur ve JWT role/team doğrulaması ister. Örnek kaynaklar:

Alan Örnek endpoint
CMS collections GET /api/merchant/cms/collections
CMS items GET /api/merchant/cms/collections/:collectionId/items
Webhook yönetimi GET /api/merchant/ecommerce/webhooks
Ödeme yönetimi POST /api/merchant/ecommerce/payments/checkout
Tema yönetimi GET /api/merchant/themes

Bu uçlar canlı temaya doğrudan verilmemelidir; satıcı paneli veya güvenilir backend app katmanı üzerinden çağrılmalıdır.

Storefront API

Canlı mağaza ve tema paketlerinin kullandığı public contract /api/store/* altındadır. Bu uçlar x-secret-key ile merchant bağlamını çözer.

Alan Örnek endpoint
Sayfa render POST /api/store/render
Merchant bilgisi GET /api/store/merchant-info
Ürün listesi GET /api/store/ecommerce/products
Sepet doğrulama POST /api/store/ecommerce/cart/validate
Checkout POST /api/store/ecommerce/checkout
CMS canlı içerik POST /api/store/cms/collections/:slug/items

Tam liste için Public API Referansı sayfasını kullanın.

Webhook Olayları

Webhook yönetimi admin tarafında /api/merchant/ecommerce/webhooks uçlarıyla yapılır. Backend ve frontend tarafında senkron tutulan olay kataloğu şu event değerlerini içerir:

Grup Event
Sipariş order.created, order.paid, order.updated, order.fulfilled, order.cancelled, order.refunded
Ürün product.created, product.updated, product.deleted, inventory.low_stock
Müşteri customer.created, customer.updated, customer.deleted
Değerlendirme review.created, review.approved
Pazarlama subscriber.created
CMS cms.item.published
Genel *

cms.item.published, CMS item publish akışında fire-and-forget dispatch edilir. Düşük stok için backend eşik değeri LOW_STOCK_THRESHOLD = 5 olarak tanımlıdır.

Webhook Yönetim Endpointleri

Metot Endpoint Açıklama
GET /api/merchant/ecommerce/webhooks Webhook listesini getirir
GET /api/merchant/ecommerce/webhooks/by/id/:id Tek webhook detayını getirir
POST /api/merchant/ecommerce/webhooks Webhook oluşturur
PUT /api/merchant/ecommerce/webhooks/:id Webhook günceller
DELETE /api/merchant/ecommerce/webhooks/:id Webhook siler
POST /api/merchant/ecommerce/webhooks/:id/test Test gönderimi yapar
GET /api/merchant/ecommerce/webhooks/deliveries Teslimat geçmişini listeler
POST /api/merchant/ecommerce/webhooks/deliveries/:id/redeliver Aynı payload ile tekrar gönderir

App Marketplace Verisi

Backend'de StoreApp modeli uygulama kataloğu için name, description, developer, version, category, permissions, webhooks, settings, pricing, installUrl, webhookUrl ve sıralama alanlarını taşır.

Bu veri modeli uygulama vitrini ve entegrasyon tanımları için hazırdır; ancak canlı uygulama yükleme akışını dokümante ederken mevcut endpoint ve auth davranışı ayrıca doğrulanmalıdır.

Örnek Entegrasyon: Paraşüt Otomatik Faturalandırma

Paraşüt Muhasebe Entegrasyonu (tecof-app-parasut), Tecof e-ticaret sitelerinden gelen siparişlerin ödemesi alındığında otomatik olarak fatura taslağı oluşturan örnek bir e-ticaret uygulamasıdır.

Mimari Akış ve Webhook

Uygulama, Tecof'un order.paid (ödeme alındı) webhook olayına abone olur.

sequenceDiagram
    participant Backend as Tecof Backend (api.tecof.com)
    participant App as Parasut App (parasut.tecof.com)
    participant Parasut as Parasut API (api.parasut.com)

    Backend->>App: POST /api/webhook/order_paid (orderId, customerEmail)
    Note over App: 1. Option API Proxy ile settings çeker
    App->>Backend: GET /api/store/option?name=parasut-settings
    Backend-->>App: clientId, clientSecret, companyId, vb.
    Note over App: 2. Sipariş detaylarını çeker
    App->>Backend: GET /api/store/ecommerce/orders/:id
    Backend-->>App: Sipariş kalemleri, adres, KDV oranları
    Note over App: 3. Parasut token'ı alır
    App->>Parasut: POST /oauth/token
    Parasut-->>App: Access Token
    Note over App: 4. Müşteri (contact) sorgular / oluşturur
    App->>Parasut: GET/POST /v4/{company_id}/contacts
    Parasut-->>App: Contact ID
    Note over App: 5. Fatura Taslağı oluşturur
    App->>Parasut: POST /v4/{company_id}/sales_invoices
    Parasut-->>App: Fatura Oluşturuldu
    App->>Backend: PUT /api/store/option (parasut-logs)

Kullanılan API Endpoint'leri

Paraşüt uygulaması, Tecof ile iletişim kurarken aşağıdaki endpoint'leri kullanır:

  1. GET /api/store/option?name=parasut-settings: Paraşüt kimlik bilgilerini (clientId, clientSecret, email, password, companyId) almak için.
  2. GET /api/store/ecommerce/orders/:id: Siparişin line items (kalemler), fatura adresi, vergi dairesi ve kargo ücreti gibi ham fatura detaylarını edinmek için.
  3. PUT /api/store/option: Fatura deneme geçmişini (parasut-logs) ve hata günlüklerini merchant options tablosunda saklamak için.

Örnek Entegrasyon: EDM Bilişim e-Fatura & e-Arşiv

EDM Bilişim Entegrasyonu (tecof-app-edm), Tecof e-ticaret sitelerinden gelen siparişlerin ödemesi alındığında otomatik olarak EDM portalı üzerinde e-Fatura veya e-Arşiv faturası oluşturan SOAP tabanlı bir entegrasyon uygulamasıdır.

Mimari Akış ve Webhook

Uygulama, Tecof'un order.paid (ödeme alındı) webhook olayına abone olur.

sequenceDiagram
    participant Backend as Tecof Backend (api.tecof.com)
    participant App as EDM App (edm.tecof.com)
    participant EDM as EDM SOAP API (portal.edmbilisim.com.tr)

    Backend->>App: POST /api/webhook/order_paid (orderId, customerEmail)
    Note over App: 1. Option API Proxy ile settings çeker
    App->>Backend: GET /api/store/option?name=edm-settings
    Backend-->>App: username, password, companyId, isTest
    Note over App: 2. Sipariş detaylarını çeker
    App->>Backend: GET /api/store/ecommerce/orders/:id
    Backend-->>App: Sipariş kalemleri, adres, VKN/TCKN, KDV oranları
    Note over App: 3. EDM SOAP portalına Login olur
    App->>EDM: SOAP LoginRequest
    EDM-->>App: SessionID
    Note over App: 4. Müşterinin e-Fatura mükellefiyetini sorgular
    App->>EDM: SOAP CheckUserRequest (VKN/TCKN)
    EDM-->>App: Alias / e-Fatura durum yanıtı
    Note over App: 5. Belge tipini seçer ve XML faturayı yükler
    App->>EDM: SOAP LoadInvoiceRequest (UBL-TR XML)
    EDM-->>App: e-Fatura / e-Arşiv UUID Referansı
    App->>Backend: PUT /api/store/option (edm-logs)

SOAP XML Entegrasyon Modeli

EDM Bilişim SOAP WCF web servislerine SOAP XML isteklerini hafif ve kararlı tutmak amacıyla doğrudan HTTP fetch POST istekleri şeklinde göndeririz. Bu yöntem TypeScript/ESM uyumunu bozmadan çalışır.

Örnek bir LoginRequest SOAP XML gövdesi:

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://3gbilgi.com.tr/service">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:LoginRequest>
         <ser:USER_NAME>KULLANICI_ADI</ser:USER_NAME>
         <ser:PASSWORD>SIFRE</ser:PASSWORD>
      </ser:LoginRequest>
   </soapenv:Body>
</soapenv:Envelope>

Örnek bir CheckUserRequest SOAP XML gövdesi (VKN/TCKN mükellefiyet sorgulama):

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://3gbilgi.com.tr/service">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:CheckUserRequest>
         <ser:REQUEST_HEADER>
            <ser:SESSION_ID>SESSION_ID_DEGERI</ser:SESSION_ID>
         </ser:REQUEST_HEADER>
         <ser:USER>
            <ser:IDENTIFIER>VKN_TCKN_DEGERI</ser:IDENTIFIER>
         </ser:USER>
      </ser:CheckUserRequest>
   </soapenv:Body>
</soapenv:Envelope>

---

## Örnek Entegrasyon: DHL eCommerce Kargo & Barkod

DHL eCommerce Entegrasyonu (`tecof-app-dhl`), Tecof e-ticaret sitelerinden gelen siparişler "Kargoya Hazır" (`order.ready_to_ship`) durumuna geçtiğinde otomatik olarak DHL üzerinde gönderi kaydı açıp kargo barkod etiketini (Shipping Label PDF) oluşturan bir kargo entegrasyon uygulamasıdır.

### Mimari Akış ve Webhook

Uygulama, Tecof'un `order.ready_to_ship` (kargoya hazır) webhook olayına abone olur.

```mermaid
sequenceDiagram
    participant Backend as Tecof Backend (api.tecof.com)
    participant App as DHL App (dhl.tecof.com)
    participant DHL as DHL REST API (api.dhl.com)

    Backend->>App: POST /api/webhook/order_ready_to_ship (orderId, customerEmail)
    Note over App: 1. Option API Proxy ile settings çeker
    App->>Backend: GET /api/store/option?name=dhl-settings
    Backend-->>App: clientId, clientSecret, pickupAccount, vb.
    Note over App: 2. Sipariş detaylarını çeker
    App->>Backend: GET /api/store/ecommerce/orders/:id
    Backend-->>App: Alıcı bilgileri, kargo adresi, paket ağırlığı
    Note over App: 3. DHL portalından OAuth2 token alır
    App->>DHL: POST /oauth/jsonwebtoken/token
    DHL-->>App: Access Token
    Note over App: 4. Gönderi ve Barkod oluşturur
    App->>DHL: POST /shipping/v2/shipments
    DHL-->>App: trackingNumber, labelUrl
    Note over App: 5. Kargo paketini siparişe ekler
    App->>Backend: POST /api/store/ecommerce/orders/:id/packages
    Backend-->>App: Paket siparişe eklendi ve statü Shipped yapıldı
    App->>Backend: PUT /api/store/option (dhl-logs)

Kullanılan API Endpoint'leri

DHL uygulaması, Tecof ile iletişim kurarken aşağıdaki endpoint'leri kullanır:

  1. GET /api/store/option?name=dhl-settings: DHL API kimlik bilgilerini (clientId, clientSecret, pickupAccount, soldToAccount) almak için.
  2. GET /api/store/ecommerce/orders/:id: Siparişin alıcı ad/soyad, kargo adresi, posta kodu, ülke kodu ve toplam paket ağırlığı gibi detayları edinmek için.
  3. POST /api/store/ecommerce/orders/:id/packages: Oluşturulan takip numarasını, kargo firmasını ("dhl") ve kargo etiket linkini (labelUrl) siparişe "paket" olarak kaydetmek ve sipariş durumunu otomatik olarak "kargoya verildi" (shipped) durumuna geçirmek için.
  4. PUT /api/store/option: Gönderi deneme geçmişini (dhl-logs) ve kargo takip numaralarını merchant options tablosunda saklamak için.

Örnek Entegrasyon: ShipEntegra Kargo & Barkod

ShipEntegra Entegrasyonu (tecof-app-shipentegra), Tecof e-ticaret sitelerinden gelen siparişler "Kargoya Hazır" (order.ready_to_ship) durumuna geçtiğinde otomatik olarak ShipEntegra üzerinde gönderi siparişi açıp kargo barkod etiketini (Shipping Label PDF) oluşturan bir kargo entegrasyon uygulamasıdır.

Mimari Akış ve Webhook

Uygulama, Tecof'un order.ready_to_ship (kargoya hazır) webhook olayına abone olur.

sequenceDiagram
    participant Backend as Tecof Backend (api.tecof.com)
    participant App as ShipEntegra App (shipentegra.tecof.com)
    participant ShipEntegra as ShipEntegra REST API (api.shipentegra.com)

    Backend->>App: POST /api/webhook/order_ready_to_ship (orderId, customerEmail)
    Note over App: 1. Option API Proxy ile settings çeker
    App->>Backend: GET /api/store/option?name=shipentegra-settings
    Backend-->>App: username, password, isTest
    Note over App: 2. Sipariş detaylarını çeker
    App->>Backend: GET /api/store/ecommerce/orders/:id
    Backend-->>App: Alıcı bilgileri, kargo adresi, paket ağırlığı, GTIP kodları
    Note over App: 3. ShipEntegra portalından OAuth2 token alır
    App->>ShipEntegra: POST /auth/login
    ShipEntegra-->>App: Bearer Token
    Note over App: 4. Sipariş kaydı oluşturur
    App->>ShipEntegra: POST /orders
    ShipEntegra-->>App: shipentegraOrderId
    Note over App: 5. Kargo etiketi (PDF) ve takip nosu üretir
    App->>ShipEntegra: POST /orders/{id}/label
    ShipEntegra-->>App: trackingNumber, labelUrl
    Note over App: 6. Kargo paketini siparişe ekler
    App->>Backend: POST /api/store/ecommerce/orders/:id/packages
    Backend-->>App: Paket siparişe eklendi ve statü Shipped yapıldı
    App->>Backend: PUT /api/store/option (shipentegra-logs)

Kullanılan API Endpoint'leri

ShipEntegra uygulaması, Tecof ile iletişim kurarken aşağıdaki endpoint'leri kullanır:

  1. GET /api/store/option?name=shipentegra-settings: ShipEntegra API kullanıcı adı ve şifre bilgilerini almak için.
  2. GET /api/store/ecommerce/orders/:id: Siparişin alıcı adı, soyadı, kargo adresi, posta kodu, ülke kodu, toplam paket ağırlığı ve ürün fiyatları gibi detayları edinmek için.
  3. POST /api/store/ecommerce/orders/:id/packages: Oluşturulan takip numarasını, kargo firmasını ("shipentegra") ve kargo etiket linkini (labelUrl) siparişe "paket" olarak kaydetmek ve sipariş durumunu otomatik olarak "kargoya verildi" (shipped) durumuna geçirmek için.
  4. PUT /api/store/option: Gönderi deneme geçmişini (shipentegra-logs) ve kargo takip numaralarını merchant options tablosunda saklamak için.

Örnek Entegrasyon: Hepsijet Kargo

Hepsijet Entegrasyonu (tecof-app-hepsijet), Tecof e-ticaret sitelerinden gelen siparişler "Kargoya Hazır" (order.ready_to_ship) durumuna geçtiğinde otomatik olarak Hepsijet üzerinde gönderi siparişi açan bir kargo entegrasyon uygulamasıdır.

Mimari Akış ve Webhook

Uygulama, Tecof'un order.ready_to_ship (kargoya hazır) webhook olayına abone olur.

sequenceDiagram
    participant Backend as Tecof Backend (api.tecof.com)
    participant App as Hepsijet App (hepsijet.tecof.com)
    participant Hepsijet as Hepsijet REST API (api.hepsijet.com)

    Backend->>App: POST /api/webhook/order_ready_to_ship (orderId, customerEmail)
    Note over App: 1. Option API Proxy ile settings çeker
    App->>Backend: GET /api/store/option?name=hepsijet-settings
    Backend-->>App: username, password, companyKey, isTest
    Note over App: 2. Sipariş detaylarını çeker
    App->>Backend: GET /api/store/ecommerce/orders/:id
    Backend-->>App: Alıcı bilgileri, kargo adresi, paket ağırlığı
    Note over App: 3. Hepsijet portalına gönderi kaydı açar
    App->>Hepsijet: POST /advance/sendDeliveryAdvance/v2
    Hepsijet-->>App: hepsijetBarcode (deliveryNo)
    Note over App: 4. Kargo paketini siparişe ekler
    App->>Backend: POST /api/store/ecommerce/orders/:id/packages
    Backend-->>App: Paket siparişe eklendi ve statü Shipped yapıldı
    App->>Backend: PUT /api/store/option (hepsijet-logs)

Kullanılan API Endpoint'leri

Hepsijet uygulaması, Tecof ile iletişim kurarken aşağıdaki endpoint'leri kullanır:

  1. GET /api/store/option?name=hepsijet-settings: Hepsijet API kullanıcı adı, şifre ve firma anahtarı (companyKey) bilgilerini almak için.
  2. GET /api/store/ecommerce/orders/:id: Siparişin alıcı adı, soyadı, kargo adresi, posta kodu, il/ilçe ve paket ağırlığı gibi detayları edinmek için.
  3. POST /api/store/ecommerce/orders/:id/packages: Hepsijet'ten dönen barkod / takip numarasını kargo firması ("hepsijet") ile siparişe "paket" olarak kaydetmek ve sipariş durumunu otomatik olarak "kargoya verildi" (shipped) durumuna geçirmek için.
  4. PUT /api/store/option: Gönderi deneme geçmişini (hepsijet-logs) ve kargo takip numaralarını merchant options tablosunda saklamak için.

Örnek Entegrasyon: Hepsiburada Pazaryeri

Hepsiburada Pazaryeri Entegrasyonu (tecof-app-hepsiburada), Tecof e-ticaret sitenizdeki ürünleri tek tıkla Hepsiburada kataloğuna aktarmanızı ve Hepsiburada'da oluşan siparişleri otomatik olarak Tecof siparişlerine senkronize etmenizi sağlayan bir pazaryeri uygulamasıdır.

Mimari Akış ve Webhook

Uygulama, Tecof'un product_created, product_updated ve order_sync webhook olaylarına abone olur.

sequenceDiagram
    participant Backend as Tecof Backend (api.tecof.com)
    participant App as Hepsiburada App (hepsiburada.tecof.com)
    participant Hepsiburada as Hepsiburada Merchant API (merchant-api.hepsiburada.com)

    Backend->>App: POST /api/webhook/product_created (product)
    Note over App: 1. Option API Proxy ile settings çeker
    App->>Backend: GET /api/store/option?name=hepsiburada-settings
    Backend-->>App: merchantId, username, password, isTest
    Note over App: 2. Hepsiburada kataloğuna ürünü gönderir
    App->>Hepsiburada: POST /packages/merchant/{merchantId}/products
    Hepsiburada-->>App: batchRequestId (id)
    App->>Backend: PUT /api/store/option (hepsiburada-logs)

Kullanılan API Endpoint'leri

Hepsiburada uygulaması, Tecof ile iletişim kurarken aşağıdaki endpoint'leri kullanır:

  1. GET /api/store/option?name=hepsiburada-settings: Hepsiburada API kullanıcı adı, şifre ve satıcı ID (merchantId) bilgilerini almak için.
  2. POST /api/store/ecommerce/orders: Hepsiburada'da oluşan ve getOrders API'siyle çekilen siparişleri Tecof siparişlerine eklemek için.
  3. PUT /api/store/option: Ürün aktarım geçmişini (hepsiburada-logs) ve senkronizasyon raporlarını merchant options tablosunda saklamak için.

Örnek Entegrasyon: Jivochat Canlı Destek

Jivochat Entegrasyonu (tecof-app-jivochat), Tecof e-ticaret sitenize kolayca canlı destek aracı (widget) eklemenizi ve Jivochat platformunda gerçekleşen olayları (chat_accepted, offline_message vb.) Tecof altyapınıza senkronize etmenizi sağlayan bir eklentidir.

Mimari Akış ve Webhook

Jivochat uygulaması, kendi ayarlarına göre bir widgetId alır ve Jivochat üzerinden gelen webhookları karşılamak için API oluşturur.

sequenceDiagram
    participant Backend as Tecof Backend (api.tecof.com)
    participant App as Jivochat App (jivochat.tecof.com)
    participant Jivochat as Jivochat Webhook

    Jivochat->>App: POST /api/webhook/jivochat (payload)
    Note over App: 1. Option API Proxy ile settings çeker
    App->>Backend: GET /api/store/option?name=jivochat-settings
    Backend-->>App: merchantId, enabled, widgetId
    Note over App: 2. Gelen event loglara yazılır
    App->>Backend: PUT /api/store/option (jivochat-logs)

Kullanılan API Endpoint'leri

Jivochat uygulaması, Tecof ile iletişim kurarken aşağıdaki endpoint'leri kullanır:

  1. GET /api/store/option?name=jivochat-settings: Jivochat uygulamasının aktif olup olmadığı ve widget ID bilgisini almak için.
  2. PUT /api/store/option: Webhook olaylarını (jivochat-logs) saklamak ve ayarları güncellemek için.

Örnek Entegrasyon: Mailchimp E-posta Pazarlama

Mailchimp Entegrasyonu (tecof-app-mailchimp), Tecof'a kaydolan müşterileri otomatik olarak Mailchimp "Audience" (Kitle) listenize eklemenizi sağlayan bir entegrasyondur.

Mimari Akış ve Webhook

Uygulama, Tecof'un customer_created webhook olayına abone olur ve Mailchimp API'sine istek atar.

sequenceDiagram
    participant Backend as Tecof Backend (api.tecof.com)
    participant App as Mailchimp App (mailchimp.tecof.com)
    participant Mailchimp as Mailchimp API

    Backend->>App: POST /api/webhook/customer_created (customer)
    Note over App: 1. Option API Proxy ile settings çeker
    App->>Backend: GET /api/store/option?name=mailchimp-settings
    Backend-->>App: apiKey, serverPrefix, listId
    Note over App: 2. Mailchimp'e Abone Ekler
    App->>Mailchimp: POST /3.0/lists/{listId}/members (email, FNAME, LNAME)
    Mailchimp-->>App: Başarılı / Hata
    App->>Backend: PUT /api/store/option (mailchimp-logs)

Kullanılan API Endpoint'leri

Mailchimp uygulaması, Tecof ile iletişim kurarken aşağıdaki endpoint'leri kullanır:

  1. GET /api/store/option?name=mailchimp-settings: Mailchimp API Key, Prefix ve List ID bilgilerini almak için.
  2. PUT /api/store/option: Abone aktarım geçmişini (mailchimp-logs) saklamak için.

Örnek Entegrasyon: Twilio SMS Bildirimleri

Twilio Entegrasyonu (tecof-app-twilio), Tecof üzerinde gerçekleşen e-ticaret süreçlerinde (sipariş oluşturulması, kargo vb.) müşterilere otomatik SMS bildirimleri göndermenizi sağlayan bir uygulamadır.

Mimari Akış ve Webhook

Uygulama, Tecof'un order_created ve order_shipped webhook olaylarına abone olur ve Twilio API'si üzerinden SMS gönderir.

sequenceDiagram
    participant Backend as Tecof Backend (api.tecof.com)
    participant App as Twilio App (twilio.tecof.com)
    participant Twilio as Twilio API

    Backend->>App: POST /api/webhook/order_created (order)
    Note over App: 1. Option API Proxy ile settings çeker
    App->>Backend: GET /api/store/option?name=twilio-settings
    Backend-->>App: accountSid, authToken, fromNumber, notifyOrderCreated
    Note over App: 2. SMS Gönderir
    App->>Twilio: POST /Accounts/{accountSid}/Messages.json
    Twilio-->>App: Başarılı / Hata
    App->>Backend: PUT /api/store/option (twilio-logs)

Kullanılan API Endpoint'leri

Twilio uygulaması, Tecof ile iletişim kurarken aşağıdaki endpoint'leri kullanır:

  1. GET /api/store/option?name=twilio-settings: Twilio API kimlik bilgilerini almak için.
  2. PUT /api/store/option: SMS gönderim geçmişini (twilio-logs) saklamak için.

Örnek Entegrasyon: QNB e-Finans (e-Fatura)

QNB e-Finans Entegrasyonu (tecof-app-qnb), Tecof üzerinde alınan siparişleri otomatik olarak QNB sistemine (SOAP API) ileterek e-Fatura / e-Arşiv taslağı (Draft) oluşturan bir muhasebe entegrasyonudur.

Mimari Akış ve Webhook

Uygulama, Tecof'un order_created veya order_shipped webhook olaylarına abone olur, sipariş bilgisini alır, UBL (Universal Business Language) formatında bir XML paketi oluşturur ve QNB Connector Service SOAP uç noktasına iletir.

sequenceDiagram
    participant Backend as Tecof Backend (api.tecof.com)
    participant App as QNB App (qnb.tecof.com)
    participant QNB as QNB SOAP API

    Backend->>App: POST /api/webhook/order_created (order)
    Note over App: 1. Option API Proxy ile settings çeker
    App->>Backend: GET /api/store/option?name=qnb-settings
    Backend-->>App: username, password, autoCreateInvoice
    Note over App: 2. UBL XML Oluşturur ve SOAP İsteği Atar
    App->>QNB: POST /connectorService
    QNB-->>App: Başarılı / Hata (Fatura ID)
    App->>Backend: PUT /api/store/option (qnb-logs)

Kullanılan API Endpoint'leri

QNB uygulaması, Tecof ile iletişim kurarken aşağıdaki endpoint'leri kullanır:

  1. GET /api/store/option?name=qnb-settings: QNB portal kimlik bilgilerini almak için.
  2. PUT /api/store/option: Fatura oluşturma loglarını (qnb-logs) saklamak için.