Kaynak içe aktarma API'si

​

Başlamadan önce

• Organizasyon sahibi tarafından JSON API girdi sözleşmesi tanımlanmış, aktif bir kaynak adaptörü.
• İlgili organizasyonda Ayarlar → API anahtarları (/settings/api-keys) üzerinden alınmış bir API anahtarı. Entegrasyon için ayrı bir kullanıcı kullanın; anahtarı kaynak kodunda veya paylaşılan günlüklerde değil, bir gizli bilgi yönetim sisteminde saklayın.
• İçe aktarma göndermek ve çalıştırmak için Collector, Approver, Manager veya Owner rolü ve hedef lokasyonlara erişim. Adaptör keşfi ve izin verilen çalıştırmaları okumak için Viewer erişimi yeterlidir.
• Örnekleri uygulamak için curl ve jq.

export AZALT_API_URL="https://azalt.example.com"

​

1. Adaptörü etkinleştirin

{
  "enabled": true,
  "context": { "yearRequired": true, "siteRequired": false },
  "sheets": [
    {
      "name": "Sheet1",
      "required": true,
      "additionalColumns": false,
      "fields": [
        {
          "name": "invoice_id",
          "type": "string",
          "required": true,
          "example": "INV-2026-0001"
        },
        {
          "name": "line_id",
          "type": "string",
          "required": true,
          "example": "0001"
        },
        {
          "name": "amount",
          "type": "number",
          "required": true,
          "example": -125.5
        },
        {
          "name": "unit",
          "type": "string",
          "required": true,
          "example": "litre"
        }
      ]
    }
  ]
}

​

Kabul edilen veri türleri

​

2. Adaptörleri ve sözleşmelerini listeleyin

curl --fail-with-body \
  "$AZALT_API_URL/api/v1/source-adapters?limit=50&offset=0" \
  -H "Authorization: Bearer $AZALT_API_KEY"

export AZALT_ADAPTER_ID="REPLACE_WITH_ADAPTER_ID"

curl --fail-with-body \
  "$AZALT_API_URL/api/v1/source-adapters/$AZALT_ADAPTER_ID" \
  -H "Authorization: Bearer $AZALT_API_KEY" \
  --output adapter.json

jq '{id, apiReady, adapterVersion, inputContract, limits, exampleRequest}' adapter.json

jq -e 'if .apiReady == true and .exampleRequest != null then .exampleRequest else error("Adapter is not API-ready") end' \
  adapter.json > submission.json

{
  "sourceAdapterDefinitionId": "ADAPTER_ID",
  "adapterVersion": "COPY_VERSION_FROM_ADAPTER_RESPONSE",
  "mode": "preview",
  "context": { "year": 2026 },
  "sheets": [
    {
      "name": "Sheet1",
      "rows": [
        {
          "invoice_id": "INV-2026-0001",
          "line_id": "0001",
          "amount": -125.5,
          "unit": "litre"
        }
      ]
    }
  ]
}

​

3. Önizleme gönderin

export AZALT_BATCH_KEY="erp-invoices-2026-09-08-batch-001"

curl --fail-with-body "$AZALT_API_URL/api/v1/source-imports" \
  -H "Authorization: Bearer $AZALT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $AZALT_BATCH_KEY" \
  --data-binary @submission.json \
  --output preview.json

jq '{run, counts, outcomes, execution, replayed}' preview.json
export AZALT_RUN_ID="$(jq -er '.run.id' preview.json)"

curl --fail-with-body \
  "$AZALT_API_URL/api/v1/source-imports/$AZALT_RUN_ID/rows?limit=100&offset=0" \
  -H "Authorization: Bearer $AZALT_API_KEY"

curl --fail-with-body \
  "$AZALT_API_URL/api/v1/source-imports/$AZALT_RUN_ID/readiness" \
  -H "Authorization: Bearer $AZALT_API_KEY"

​

4. Kaydedilen önizlemeyi çalıştırın

curl --fail-with-body \
  "$AZALT_API_URL/api/v1/source-imports/$AZALT_RUN_ID/execute" \
  -H "Authorization: Bearer $AZALT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}' \
  --output execution.json

jq '{run, counts, outcomes, execution}' execution.json

{ "allowMissingFormSiteCreation": true }

​

Sonucu yorumlama

​

Önceden aktarılan satırları güncelleyin

{
  "sourceColumns": ["invoice_id", "line_id"],
  "rowIdentity": {
    "fields": ["invoice_id", "line_id"],
    "match": "all"
  }
}

​

Yalnızca yeni satırları ekleyin

​

Mevcut API istemcisini yeni sözleşmeye taşıma

​

Yalnızca mevcut satırları güncelleyin

{
  "sourceAdapterDefinitionId": "ADAPTER_ID",
  "adapterVersion": "COPY_VERSION_FROM_ADAPTER_RESPONSE",
  "mode": "preview",
  "context": { "year": 2026 },
  "sheets": [
    {
      "name": "Sheet1",
      "rows": [
        {
          "invoice_id": "INV-2026-0001",
          "line_id": "0001",
          "amount": -150,
          "unit": "litre"
        }
      ]
    }
  ]
}

​

Eklenen ve güncellenen satırları ayırt etme

​

Veri aktardıktan sonra satır kimliği kuralını değiştirme

• Faaliyetler: Sonraki update/skip gönderiminde Azalt, mevcut faaliyetlerin kayıtlı kaynak hücrelerinden yeni kuralla eşleştirme kimlikleri üretir. Tek bir eşleşme bulunursa veritabanı kimliği korunarak güncellenebilir. Kayıtlı kaynakta gerekli alanlar yoksa faaliyet eşleşemez. Güncelleme uç noktası eşleşmeyen satırı reddeder. Yalnızca ekleme yapan API gönderimleri ve eklemeye izin veren dosya aktarımları bu satırı yeni sayıp yinelenen kayıt oluşturabilir. Birden fazla mevcut eşleşme reddedilir.
• Form değerleri: Eski aktarımlar kayıtlı kaynak taslaklarıyla eşleştirilebilir. Bir hedefin kaydedilmiş güncelleme katkı listesi varsa kimlik kuralını değiştirmek sonraki güncellemeleri engeller. Yeni kuralla güncellemeye başlamadan önce ilgili form değeri hedefine katkı yapan tüm satırları dosya aktarımı akışında append seçeneğiyle tam değiştirme olarak içe aktarın. JSON API bu değiştirme işlemini desteklemez ve istek gövdesindeki onExistingRow alanını reddeder. Bu değiştirme davranışı form değerleri içindir; append faaliyetlerde yeni kayıt oluşturur.
• API sürümleri ve önizlemeler: Kural değişince güncel adapterVersion değerini alın. Eski sürümle yapılan yeni gönderimler 409 döndürür. Kaydedilmiş önizlemeler özgün kurallarını kullanmaya devam eder.

​

Yeniden denemeler ve adaptör değişiklikleri

• POST /source-imports ve POST /source-imports/amendments için Idempotency-Key zorunludur: boşluk içermeyen 1–200 yazdırılabilir ASCII karakteri. Kapsamı organizasyon ve API anahtarı sahibidir.
• Aynı anahtar ve gövde tekrar gönderilirse aynı çalıştırma replayed: true ile döner. Nesne anahtarlarının sırası önemsizdir; sayfa ve satır dizilerinin sırası önemlidir. Aynı anahtarla farklı veri, mod, sürüm veya onay ayarı göndermek 409 döndürür.
• Önizlemeyi çalıştırmak için /source-imports/{id}/execute çağrısını kullanın. İlk isteğin mode değerini aynı anahtar altında değiştirmeyin. Çalıştırma uç noktası idempotency başlığı gerektirmez ve aynı çalıştırma için güvenle tekrarlanabilir.
• Zaman aşımı veya geçici hata sonrasında aynı isteği/çalıştırmayı tekrarlayın. Veritabanı kilitleri farklı replikalardan ve arayüzden gelen eşzamanlı denemeleri koordine eder. Bazı yazımlar tamamlanmış olabilir; aynı çalıştırmayı tekrarlamak yeni içe aktarma başlatmak yerine kalan hazır taslakları tamamlar.
• Farklı anahtarlar farklı aktarımlar oluşturur. Genel POST eşleşen iş kaydı kimliklerini reddeder; amendments bunları günceller. Değişmemiş paketi yeni aktarım olarak göndermek yerine özgün anahtarıyla yeniden deneyin.
• Betik veya girdi sözleşmesi değişikliği adapterVersion değerini günceller. Eski sürümle yapılan yeni gönderimler 409 döndürür. Güncel sözleşmeyi alın, değişiklikleri inceleyin ve yeni bir paket hazırlayın. Mevcut önizlemeler, düzenlenmiş adaptör betiğini yeniden çalıştırmadan kaydedilmiş taslaklarını işler.
• Adaptör hata verirse kaydedilen satır hatalarını inceleyin, girdiyi veya adaptörü düzeltin ve düzeltilmiş paketi yeni anahtarla gönderin. Hatalı isteği değiştirmeden tekrarlamak eşlemeyi yeniden çalıştırmaz.
• Silinmiş çalıştırmalara bu uç noktalardan erişilemez. Kalıcı silme idempotency rezervasyonunu korur; aynı anahtarı tekrar kullanmak yeni içe aktarma değil 409 döndürür.

​

Uç nokta referansı

​

Sınırlar ve hatalar

​

Şirket içi ve Helm split kurulumu

1. Hedef veritabanını yedeklemeli ve normal Helm migrasyon işi/süreciyle sürümdeki tüm bekleyen migrasyonları uygulamalıdır. Bunlar, isteklerin yinelenmesini önleyen tabloyu oluşturan 20260908000000_add_source_import_api_requests.ts migrasyonunu da içerir.
2. Split kurulumda birbirine uyumlu güncel frontend ve backend imajlarını dağıtmalıdır. Yalnızca frontend’i güncellemek backend uç noktalarını eklemez.
3. Ingress/proxy üzerinde /api/v1 yönlendirmesini ve Authorization, Content-Type, Idempotency-Key başlıklarını korumalıdır. Kimlik doğrulamalı yanıtlar önbelleğe alınmamalıdır.
4. İstek gövdesi ve eşzamanlı istek zaman aşımı sınırlarını kontrol etmeli; ardından dağıtılmış OpenAPI belgesini doğrulayıp çalıştırma öncesinde küçük, incelenmiş bir önizleme denemelidir.