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": "FATURA ID",
          "type": "string",
          "required": true,
          "example": "INV-2026-0001"
        },
        {
          "name": "TUTAR",
          "type": "number",
          "required": true,
          "example": -125.5
        },
        {
          "name": "BİRİM",
          "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": [
        { "FATURA ID": "INV-2026-0001", "TUTAR": -125.5, "BİRİM": "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, 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, execution}' execution.json

{ "allowMissingFormSiteCreation": true }

​

Sonucu yorumlama

​

Yeniden denemeler ve adaptör değişiklikleri

• POST /source-imports 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ı içe aktarmalar oluşturur. Paketler arasında iş verisinin yinelenmesini önlemek hâlâ adaptörün idempotencyKey ve yinelenen veri stratejisine bağlıdır. Strateji bunu karşılamıyorsa başarılı satırları yeni anahtarla tekrar göndermeyin.
• 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ümün ekleme yapan 20260908000000_add_source_import_api_requests.ts migrasyonunu uygulamalıdır. Bu migrasyon isteklerin yinelenmesini önleyen tabloyu oluşturur.
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.