SSS ve Sorun Giderme
Mahsuplaşma modülünde sık karşılaşılan sorular ve hata kodlarının çözümleri.
Hata kodu → açıklama → çözüm
| HTTP / kod | Ne demek? | Çözüm |
|---|---|---|
| 409 — provenance-downgrade | Kapsam zaten daha güçlü bir kaynakla beyan edilmiş; daha zayıf kaynakla tekrar-declare | Aynı veya daha güçlü bir declaration_source gönderin (customer_declaration < official_document < lum_report/gts_report) |
| 409 — dönem çakışması (sayaç) | Aynı alt bölge + aynı ANA ölçüm rolü için çakışan dönem zaten var | Önce mevcut atamanın valid_to'sunu kapatın (PATCH .../meters/assignments/{id}), sonra yeni dönemi atayın |
| 409 — tek-grup EXCLUDE (üye) | Tesis aynı dönemde başka bir grubun üyesi | Önce mevcut üyeliğin valid_to'sunu kapatın, sonra bu gruba ekleyin (bir tesis bir dönemde tek grupta) |
| 409 — state-machine (grup) | Geçersiz group_status geçişi (geri düşme/atlama) | Yalnız ileri-akış (customer_defined → ek1_submitted → grid_operator_confirmed → lum_reported) veya inactive yönünde ilerleyin |
| 409 — EPİAŞ whitelist geçişi | Geçersiz whitelist_status geçişi (adım atlama veya geri gitme) — EPİAŞ API Portal 9-adımlı süreci | Yalnız bir sonraki ileri adıma geçin (not_started → … → active) veya herhangi durumdan blocked'a geçin. "Engelle" arayüzde tek yönlüdür: engellenen hesap için "İlerlet" düğmesi görünmez (ekran "geri dönüş yoktur; yalnız düzenlenebilir" uyarısını verir), yanlışlıkla engellerseniz yeni bir hesap oluşturun (bkz. EPİAŞ Piyasa Fiyatları) |
| 409 — tekil hesap (limit) | Tesis × yıl için hesap zaten var | Mevcut hesabı kullanın / adjust ile düzeltin |
409 — INSUFFICIENT_LIMIT_BALANCE (422 gövdeli) | Kaynak hesabın kalan limiti transfer miktarından az | Transfer miktarını düşürün veya önce hedefe limit ekleyin |
409 — TARIFF_SET_APPROVED_IMMUTABLE | Onaylı/arşivli pakete fiyat/metadata yazma | Paketi arşivleyip yeni bir draft paket oluşturun |
409 — TARIFF_ALREADY_APPROVED | Zaten onaylı/arşivli paketi tekrar onaylama | Yeni bir draft paketle çalışın |
409 — TARIFF_SET_NOT_DELETABLE | Onaylı/arşivli paketi silme denemesi | Yalnız draft silinir; onaylıyı arşivleyin |
409 — TARIFF_PRICE_DUPLICATE | Aynı doğal anahtarlı fiyat satırı (NULLS NOT DISTINCT) | Mevcut satırı düzeltin / farklı boyut (kademe/zaman dilimi) kullanın |
409 — facility_has_dependencies (tesis silme) | Silmek istenen tesise bağlı alt kayıt(lar) var (ölçüm noktası / sayaç ataması / saatlik enerji / grup üyeliği / limit hesabı) | Yanıttaki dependencies sayılarına bakıp önce sayısı > 0 olan bağımlılıkları kaldırın, sonra tesisi silin (hard-delete GERİ ALINAMAZ) |
403 — SUPERUSER_REQUIRED (tesis silme) | Tesis silme yalnız superadmin'e açık; manage:netting yetmez | Süper yönetici ile işlem yapın (buton yalnız superadmin'e görünür) |
422 — CSV_IMPORT_* | CSV boyut/tip/başlık/satır/kodlama/injection ihlali | Aşağıdaki "CSV import" bölümüne bakın |
| 422 — geçersiz referans | FK (scope/subregion/device/facility/kurum) geçersiz veya cross-tenant | Referansı kendi tenant'ınızdaki görünür bir kayda çevirin |
| 422 — Md.6(2) geriye-yasak | valid_from geçmiş fatura dönemine set edilmiş | valid_from'u grubun/mevcut fatura döneminden erken olmayacak şekilde ayarlayın |
| 404 | Kayıt bulunamadı veya tenant izolasyonu reddi | Id'yi ve tenant'ınızı doğrulayın (cross-tenant kayıtlar da 404 döner — enumeration koruması) |
503 — encryption_not_configured / encryption_misconfigured (EPİAŞ hesap) | Kimlik bilgisi şifreleme anahtarı (CREDENTIAL_ENCRYPTION_KEY) sunucuda yok veya geçersiz — açık metin saklamamak için EPİAŞ hesap kaydetme/güncelleme kapatılır (fail-closed) | Sunucu yapılandırmasında şifreleme anahtarını tanımlayın/düzeltin (DevOps). Anahtar hazır olana kadar şifre/abonelik anahtarı içeren hesap işlemleri reddedilir |
Bloklayıcı uygunluk senaryoları (grup neden hesaplanamıyor?)
Bazı sorunlar bir HTTP hatası vermez; bunun yerine grubun uygunluk sonucunu
bloklayıcı (blocking) yapar → grup blocked olur. Bu durumda hesap durmaz
ama bedelsiz riski ile simüle edilir: üretim bedelsiz sanal sayaca
yazılır (Md.6(4)/9(6)). Bu senaryolar uygunluk yanıtında status="fail" ve
severity="blocking" olarak görünür ve her biri aynı zamanda bir Kritik sistem
alarmı üretir.
En sık karşılaşılan üç bloklayıcı senaryo:
| Kural | Ne demek? (sebep) | Ürettiği alarm | Çözüm |
|---|---|---|---|
| R003M — ana üretim sayacı yok | Grupta main_production (ana üretim) ölçüm rolü hiçbir cihaza atanmamış; üretim ölçülemediği için mahsuplaşma hesaplanamaz | Ana sayaç atanmamış (mahsuplasma_main_meter_missing) | Sayaç Atama ve Kanal Eşleme sihirbazından bir cihaza main_production rolü atayın. Atama yapılınca bir sonraki değerlendirmede blok ve alarm otomatik kalkar |
| R007 / R00L — bedelli limit hesabı yok | Mesken-dışı bir grupta bir tüketim tesisinin, grubun fatura yılı için bedelli limit hesabı yok (Md.7/1); bedelli/bedelsiz ayrımı yapılamaz | Bedelli limit tanımsız (mahsuplasma_limit_missing) | İlgili tüketim tesisi için o yıla ait bedelli limit hesabını açın (Limit Hesapları). Mesken gruplarında bu kural muaftır (limit adımı atlanır) |
| R00T — onaylı regüle tarife yok / eşleşmiyor | Cari dönem için onaylı bir regüle (EPDK) tarife seti yok ya da tesisin abone grubuyla eşleşen fiyat kalemi bulunmuyor (Md.11); tutar hesaplanamaz | Onaylı tarife eksik (mahsuplasma_tariff_missing) | Süper yönetici, dönem için regüle tarife paketini içe aktarıp onaylasın; abone grubu eşleşmesini doğrulayın (Regüle Tarifeler). Bu kural PR-6'dan beri CANLI ve bloklayıcıdır |
not_checked bir kural asla "uygun" saymazR003M/R007/R00T bloklayıcı kurallardır: FAIL olurlarsa grup blocked olur. Bazı
bloklayıcı kurallar ise gerekli veri kaynağı bağlanmadığı için not_checked
döner (R008/R009/R011/R00L gibi ileri fazlar). Bir bloklayıcı sınıf kural
çözülemediği sürece grup en fazla not_checked olabilir — asla valid (uygun)
sayılmaz. Ayrıntı: Uygunluk Kuralları.
Sık sorulan sorular
Grubum neden blocked?
blocked, en az bir blocking uygunluk kuralının FAIL olduğu anlamına gelir.
Nedenini görmek için:
GET /api/mahsuplasma/groups/{group_id}/eligibility
Yanıttaki results listesinde status="fail" ve severity="blocking" olan
kural(lar)a ve onların evidence alanına bakın. En yaygın nedenler:
- R001 — grupta
lum_yonetmelik_26dışı bir tesis var, - R002 — tüketim tesisleri aynı abone grubunda değil,
- R003 — çoklu tüketimde farklı tedarikçiler,
- R003M — ana üretim sayacı atanmamış (önce
POST /meters/assign), - R006 — 5.1.ç ilişkilendirme matrisi ihlali,
- R007 — bir tüketim tesisinin bedelli limit hesabı yok (bkz. Limit Hesapları).
Ayrıntı için Uygunluk Kuralları.
"409 dönem çakışması" ne demek?
Sayaç eşlemesinde (/meters/assign) veya üye eklemede (/members) çakışan bir
zaman aralığı var demektir. Zeus, aynı alt bölgedeki aynı ana ölçüm rolünü
(veya bir tesisin grup üyeliğini) çakışan dönemlerde ikiye ayırmaya izin
vermez. Çözüm: eskisini valid_to ile kapatın, yenisini komşu dönemden
başlatın (dönemler [valid_from, valid_to) yarı-açıktır — komşu dönemler
çakışmaz).
Transfer neden reddedildi (INSUFFICIENT_LIMIT_BALANCE)?
Kaynak hesabın kalan bedelli limiti, transfer etmek istediğiniz miktardan
azdır. Kalan limit initial + SUM(hareketler) ile canlı hesaplanır; başka
transferler/düşümler kalanı azaltmış olabilir. Daha az miktar transfer edin
veya kaynağın limitini önce artırın.
CSV import neden 0 satır aldı (imported=0)?
CSV import atomiktir — tek bir hatalı satır bile tüm import'u reddeder.
Yanıttaki errors: [{row, message}] listesi hangi satırın neden reddedildiğini
söyler. Kontrol listesi:
- Tüm zorunlu başlıklar var mı? (
valid_from, billing_period, abone_grubu, price_purpose, price) abone_grubu/price_purpose/time_segmentwhitelist'te mi?price> 0 mı? Tarihler ISO (YYYY-MM-DD) mı?- Hücreler
=,+,@,-, tab ile başlamıyor mu? (CSV-injection reddi) - Dosya ≤ 2 MB ve ≤ 10.000 satır mı?
.csvuzantılı mı? - Paket hâlâ draft mı? (onaylı pakete import yapılamaz)
Bkz. Regüle Tarifeler — CSV import.
not_checked kurallar ne zaman aktifleşecek?
Bazı kurallar, gerekli veri kaynağı henüz bağlanmadığı için not_checked
döner. Aktivasyon fazları:
| Kural | Aktivasyon |
|---|---|
| R007 (limit hesabı) | ✅ PR-4 (aktif) |
| R00T (tarife fiyatı) | ✅ PR-6 (aktif) |
| R010 (transfer tam) | ✅ PR-6 (aktif) |
| R008 (SKTT), R009 (kurulu güç saatlik), R011 (tesis devri), R00L | 🔜 Gerekli veri kaynağı bağlanınca (not_checked döner) |
Bu kurallar aktifleşene kadar not_checked döner ve — kritik — asla valid
sayılmaz: bir blocking sınıfı kural çözülemediği sürece grup en fazla
not_checked olur.
Kapsam oluştururken beyan alanlarını neden yazamıyorum?
Bilinçli bir koruma. Kapsam her zaman declaration_source = 'not_checked' ile
doğar; "aynı resmî taraf" beyanı ayrı bir action ile
(POST /scopes/{id}/declare-same-official-party) ve token kullanıcısı
onaylayan olarak kaydedilir. Bu, beyan kimliğinin spoof edilmesini önler ve
provenance kuralını uygular.
Grup kurulum sihirbazını yarım bıraktım — verilerim kayboldu mu?
Hayır. Sihirbazın taslak mantığı sunucu-taraflıdır: her adımda kaydedilen veri anında backend'e yazılır (tarayıcıda taslak tutulmaz). Yarım kalan kurulum, gruplar listesindeki amber "Kurulum tamamlanmadı" rozetinden veya grup detayındaki "Kurulumu sürdür" butonundan açılır ve sihirbaz kaldığınız adımı sunucudaki kayıtlardan türeterek oradan devam eder. Ayrıntı: Grup Kurulum Sihirbazı.
Rozet, grup "Müşteri tanımlı" durumunda kaldığı sürece görünür — sihirbazı bitirmek grubu resmî yaşam döngüsünde otomatik ilerletmez (Ek-1 gönderimi ayrı bir süreç adımıdır).
Bir tesisi nasıl silerim? "Tesisi Sil" butonunu neden göremiyorum?
Tesis silme yalnızca süper yöneticiye (superadmin) açık, kalıcı bir
işlemdir (hard-delete — geri alınamaz). "Tesisi Sil" butonu tesis detay
sayfasında (/mahsuplasma/facilities/{id}) yalnız superadmin'e görünür; normal
manage:netting yetkisi yetmez. Butona bastığınızda bir onay dialogu çıkar; onay
sonrası kayıt kalıcı silinir.
Silme 409 ile reddedilirse (facility_has_dependencies), tesise bağlı alt
kayıtlar var demektir — yanıt engelleyen bağımlılıkların sayısını gösterir (ölçüm
noktası, sayaç ataması, saatlik enerji, grup üyeliği, limit hesabı). Önce sayısı
> 0 olanları kaldırın, sonra tesisi silin. Ayrıntı:
Kurulum Akışı — Tesis silme.
Alarm listemde "Sistem" rozetli, cihazsız alarmlar var — bunlar ne?
Bunlar mahsuplaşma sistem alarmlarıdır. Cihaz alarmlarının aksine bir cihaza
değil, mahsuplaşma kurulumunuzun bir parçasına (grup / resmî tesis / fatura
dönemi / EPİAŞ bağlantısı) bağlıdırlar; bu yüzden listede cihaz adı yerine
tesis/grup bağlamı ve bir "Sistem" rozeti gösterilir. Modül bunları
otomatik izler — siz oluşturmazsınız ve Alarm Tanımlama (/alarms)
açılır menüsünde göremezsiniz (o menü cihaz-kapsamlı kurallar içindir). Bir
sistem alarmı, işaret ettiği eksik/riskli koşul düzeldiğinde otomatik
kapanır (auto-close) — elle kapatmanız gerekmez.
Tam liste (33 tip: 29 mahsuplaşma + 4 EPİAŞ), önem dereceleri, hangi durumda tetiklendikleri ve hangi tiplerin şu an CANLI (üreticili) olduğu için Sistem Alarmları sayfasına bakın.
Bir mahsuplaşma alarmını nasıl susturur/kapatırım?
Bir sistem alarmının kalıcı çözümü, işaret ettiği eksiği gidermektir (ör. ana sayacı atamak, onaylı tarifeyi girmek, limit hesabı açmak). Koşul düzeldiğinde alarm bir sonraki değerlendirmede otomatik kapanır. Bir alarmı elle onaylayabilir / erteleyebilir / kapatabilirsiniz, ancak koşul sürdüğü sürece bir sonraki taramada yeniden açılır. Bir alarm tipini tümüyle susturmak gerekiyorsa yöneticinizle birlikte ilgili sistem alarm politikasını pasifize edebilirsiniz. Sistem alarmları varsayılan olarak yalnız uygulama-içidir — e-posta / SMS / WhatsApp / push göndermez.