Rol & kapsam
Kendi ERP'sine (NetSuite) sahip bir e-ticaret şirketi, beraberinde gelen maliyetler ve taşıyıcı sözleşmeleri üzerindeki sınırlı kontrolle birlikte bir SaaS gönderi aracı üzerinden sevkiyat yapıyordu. CarrierAPI bunun self-hosted yerine geçeni: etiket oluşturan, tarifeleri karşılaştıran, gönderileri takip eden ve birden fazla taşıyıcıda toplu işleri yürüten tek bir API — önceki araçla aynı bağlantı noktalarına sahip olduğu için NetSuite tarafındaki geçiş, yeniden inşa yerine doğrudan bir yer değiştirme olabildi.
- Taşıyıcı başına adaptör mimarisi (çekirdek küme olarak PostNL, DHL Express ve UPS; ek adaptörler olarak DHL Parcel, FedEx, GLS ve SendCloud'un kendisi), böylece yeni bir taşıyıcı eklemek sistemin geri kalanında değişiklik gerektirmiyor.
- NetSuite içinde önceki SaaS aracının doğrudan yerine geçme: aynı özel alan adları, mevcut SuiteScript entegrasyonunda asgari değişiklik.
- NetSuite'teki Item Fulfillment kayıtlarına doğrudan bağlantı; ayrıca taşıyıcıların yanı sıra Shopify senkronizasyonu ve bir Amazon entegrasyonu.
- Taşıyıcı kimlik bilgilerini yönetmenin iki yolu: arayüz üzerinden (veritabanı destekli, tercih edilen) veya ortam değişkenleriyle (mevcut kurulumlar için eski yol).
Etki
- Gönderi maliyetleri ve taşıyıcı sözleşmeleri, bir SaaS ara katmanının tarifelerine ve koşullarına bağlı kalmak yerine yeniden kendi elinizde.
- Daha önce yanlış ayrıştırılan bir adres sınıfı için adres tanıma onarıldı (kapı numarası çıkarımı, sokak adından sonraki ilk sayı yerine yanlışlıkla son sayıyı alıyordu — örneğin hem kapı numarası hem bungalov numarası taşıyan tatil köyü adreslerinde hatalıydı).
- UPS faturalarının dışa aktarım biçimini iki kez değiştirmesine rağmen fatura eşleştirmesi çalışmaya devam etti; çünkü sütun tespiti sabit konumlar yerine içeriğe dayandırıldı ve sonuç, faturanın kendi belirttiği toplam tutarla karşılaştırıldı.
- Silinmiş kullanıcıların 24 saate kadar erişimini koruduğu bir oturum açığı kapatıldı; çünkü oturum jetonunun yalnızca imzası ve geçerlilik süresi kontrol ediliyordu — hesabın hâlâ var olup olmadığı değil.
Mimari
Her taşıyıcı, ortak bir arayüzün arkasında bir adaptör (gönderi oluşturma ve iptal, tarife sorgulama, takip, mevcut hizmetler) — yeni bir taşıyıcı bağlamak sistemin geri kalanına dokunmuyor. Backend, birincil veritabanı olarak PostgreSQL ve etiketlerin toplu işlenmesi için Redis tabanlı bir arka plan işçisi (arq) ile FastAPI (Python, async); böylece aynı anda yüzlerce etiket oluşturmak API'yi kilitlemiyor. Etiketlerin kendisi MinIO'da (S3 uyumlu) saklanıyor, dolayısıyla depolama tek bir bulut sağlayıcısına bağlı değil. Frontend, gönderileri, taşıyıcı ayarlarını ve kimlik bilgilerini yönetmek için bir Next.js/React panosu. Tümü Traefik arkasında Docker Compose ile self-hosted çalışıyor, Coolify ile yayına alınıyor.
Model seçimi
Yapay zekâ/LLM yok — bu bilinçli olarak deterministik bir sistem: gönderi etiketleri, tarifeler ve takip üretilmiş değil, öngörülebilir ve denetlenebilir olmalı. Buradaki kilit tercih self-hosted mi SaaS mi olduğuydu: bir SaaS gönderi aracı daha hızlı kurulur, ama self-hosted bir platform taşıyıcı sözleşmeleri üzerinde kontrol verir, ara katmana etiket veya gönderi başına ücret ödetmez ve işlevselliği (örneğin doğrudan NetSuite bağlantısını) bir SaaS sağlayıcısının neyi destekleyip desteklemediğini beklemek yerine tam ihtiyaca göre kurmaya izin verir.
Maliyet & gecikme
- Gönderi başına yinelenen bir SaaS ücreti yerine kendi barındırılan altyapı (Docker Compose, PostgreSQL, Redis, MinIO).
- Toplu etiket üretimi Redis kuyruğu (arq) üzerinden asenkron çalışıyor; böylece aynı anda yüzlerce etiket oluşturmak, talebi yapanı bekletmek yerine API'yi tepkisel tutuyor.
- Fatura eşleştirmesi gerçek UPS faturalarıyla doğrulandı: bunlar arasında 1.275 satırlık 4.855,72 €'luk bir fatura ve 2.275 satırlık bir dışa aktarım — sütun tespiti düzeltmesinden sonra ikisi de doğru işlendi.
Çıkarılan dersler
Hollanda adreslerinin ayrıştırılması belirli bir adres sınıfında hata veriyordu ("Hessenweg 83 41" gibi, hem kapı numarası hem ayrı bir bungalov numarası taşıyan tatil köyü adresleri); çünkü ayrıştırıcı, sokak satırındaki son sayıyı sokak adından sonraki ilk sayı yerine kapı numarası olarak okuyordu. Ortak bir ayrıştırıcıyla çözüldü ve gerçek bir vaka üzerinde doğrulandı. UPS fatura içe aktarımı iki kez bozuldu; çünkü UPS faturalarının dışa aktarım biçimini değiştirdi (sütun sayısı ve sırası kaydı). Sabit sütun konumları yaklaşımı, sonucu faturanın kendi belirttiği toplam tutarla çapraz kontrol eden içerik tabanlı sütun tespitiyle değiştirildi. Adres doğrulama uyarıları başlangıçta gönderi oluşturmayı tamamen engelliyordu; bu davranış yalnızca otomatik etiket satın almayı engellemeye çekildi, böylece işaretlenmiş bir gönderi takılıp kalmak yerine görünür ve yeniden denenebilir kalıyor. Bir de oturum açığı: silinmiş kullanıcılar 24 saate kadar erişimini koruyordu; çünkü jetonlar yalnızca imza ve geçerlilik süresi üzerinden kontrol ediliyordu, hesabın varlığı üzerinden değil — her istekte hesabın hâlâ var olduğu doğrulanarak giderildi.