Talep ile Aktarım

Talep Kuralları ve Hataları

Yoklama sınırı, talep ömrü, tek açık talep kuralı, kalıcı ve geçici hatalar.

Son güncelleme: 21 Eylül 2026 · Sözleşme sürümü 1.0.0

Kurallar

Yoklama anahtar başına dakikada 12 çağrıyla sınırlıdır (önerilen 20–30 sn). Yanıt kapsam ailenize göre süzülür: yalnız statements:* kapsamı olan anahtar statement taleplerini görür; salt okunur anahtar listeler ama alamaz.
Tür başına tek açık talep vardır; aynı talebi iki program alamaz (claim/complete atomiktir; başka anahtar almışsa 409 request_already_claimed).
Talep 30 dk sonra expired olur; süresi geçmiş talebe complete 409 request_not_active döner ve dosya/taslak oluşmaz — veriyi atın, panel yeni talep bırakır. claim süreyi now()+10 dk'ya kadar uzatır; toplam ömür en çok 40 dk (her turda yeniden claim etmek süreyi sonsuza dek uzatmaz).
Panel kullanıcısı talebi iptal edebilir (cancelled); firma yöntemi "Anlık bağlantı"ya çevrilirse açık talepler iptal edilir. Yöntem "Talep ile aktarım" değilken yoklama boş liste döner.
fail.reason yalnız o talebin kaydında saklanır (≤300 karakter; anahtar/sır içermesin — sunucu yine de maskeler).
complete teslimatında Idempotency-Key zorunludur (başlıksız 400): aynı anahtar + aynı gövde ile tekrar gönderim ikinci kez işlenmez (24 sa önbellek). Talep başına tek teslimat bağlanır; başlık düşse bile tekrar çağrı aynı sonucu döner.
Kalıcı ret (400/402/413/422, tür/parametre uyuşmazlığı) talebi failed yapar ve sebebi panelde gösterir: aynı veriyi yeniden göndermeyin, muhasebe personeli düzeltip yeni talep bırakır. Geçici hata (429, 5xx) rezervasyonu pending'e döndürür; sonraki turda yeniden deneyin.
Teslimat tavanları: 10.000 cari (tek çağrı) · ekstre parça başına 20.000 satır, toplam 250.000 satır (elle Excel yüklemeyle aynı) · 5.000 bakiye kaydı (tek çağrı). Aşımda 413.
Anahtar: Profil → Entegrasyon → "Yeni anahtar" → Tam erişim yeter (gönderimi muhasebe personeli panelden yapar).
Gece cari güncellemesi: Profil → Entegrasyon → yoklama kartında "Cari rehberini her gün ERP'den güncelle" açıksa her gün 02:00 (İstanbul) sonrasındaki ilk yoklamada counterparties talebi kendiliğinden açılır (scheduled: true). Programınız için fark yoktur: claim → complete { counterparties }. Program o gün hiç yoklamazsa talep de açılmaz; salt okunur anahtarın yoklaması açmaz.

Hata kodları

HTTP	code	Ne zaman	Ne yapmalı
401	`unauthenticated`	Anahtar yok / geçersiz / iptal	Anahtarı ve ortamı (`mai_test_` ↔ test) kontrol edin.
403	`insufficient_scope`	Anahtar salt okunur ya da ilgili yazma kapsamı yok	Tam erişimli anahtar üretin.
404	`not_found`	Talep bu firmaya ait değil / silinmiş	Listeyi yeniden çekin.
409	`request_not_active · request_already_claimed`	Talep süresi dolmuş / iptal / başka anahtar almış	Veriyi atın; yeni talep gelirse yeniden yapın.
413	`payload_too_large`	Tek çağrı tavanı aşıldı	Cari listesini parçalara bölün (≤10.000); ekstre parçasını küçültün (≤20.000 satır/parça) — toplam 250.000 satır ya da 128 MB parça verisi üstüyse dönemi bölün / açıklamaları kısaltın; bakiye ≤5.000 kayıt.
402	`quota_exceeded`	Paketin dosya satır tavanı aşıldı (ekstre parçası; aşan ilk parçada, veri yazılmadan)	Talep `failed` olur, sebep panelde görünür; firma sahibi paketi görüşür, sonra yeni talep bırakılır.
422	`request_kind_mismatch · request_params_mismatch · unprocessable`	Gövde türü talebe uymuyor / para birimi farklı / kayıt doğrulanamadı	`details[]` alan bazında söyler. Talep `failed` olur (sebep panelde); aynı veriyi yeniden göndermeyin — muhasebe personeli yeni talep bırakır.
429	`rate_limited`	Dakikada 12 yoklama aşıldı; anahtar başına bir dosya analizi zaten sürüyor (ekstre teslimatı); aynı talebe bir teslimat zaten sürüyor; başka bir toplu aktarım kilidi tutuyor	`Retry-After` kadar bekleyin ve sonraki turda yeniden deneyin. Rezervasyon `pending`'e döner; aynı talebe süren teslimat varsa ona dokunulmaz — bitince tekrarınız aynı `completed` yanıtını alır.

Hata zarfı

Her hata aynı biçimde döner: { error: { code, message, details[] }, request_id }. request_id değerini destek taleplerinde iletin. Genel liste için Hata Kodları sayfasına bakın.