Başlangıç

API Temelleri

Kimlik doğrulama, ortak istek alanları, yanıt zarfı, firma ve açılış/kapanış dönem kimliği.

Bu sayfa, e-Envanter Defteri endpointlerinin ortak oturum, firma, dönem ve yanıt sözleşmesini açıklar. Açılış ve kapanış aynı API modellerini kullanır; birbirinden yalnız tarihleri ve kaynak envanter içeriğiyle ayrılır.

Başlamadan Önce

Hazırlık	Gerekli bilgi	Kontrol
API erişimi	Ortamın Gateway API ana adresi	Test ve canlı adresleri birbirinden ayrılmalıdır.
Kullanıcı	E-posta ve parola	Parola yalnız oturum açma isteğinde gönderilir.
Firma bağlamı	`SecurityFirmUuid`, VKN/TCKN ve şube kodu	Login cevabı, header ve gövde aynı firmayı göstermelidir.
Envanter türü	1 Ocak açılış veya 31 Aralık kapanış	Ara ay, tarih aralığı ve özel hesap dönemi kullanılmaz.

Kimlik Doğrulama

Oturum açma isteğinde yalnızca hesap e-postası ve parola gönderilir. Başarılı cevapta alınan token, sonraki korumalı çağrıların Authorization header'ında kullanılır.

POST/api/Session/Login

API oturumu için yetkilendirme token'ı üretir.

Request	`Email`, `Password`
Response	Token bilgisi

Oturum açma JSON örneğini görüntüle

{
  "Email": "entegrasyon@firma.com",
  "Password": "GUCLU_PAROLANIZ"
}

Header	Değer	Zorunluluk
`Authorization`	`Bearer {token}`	Oturum açma dışındaki korumalı endpointlerde zorunlu.
`SecurityFirmUUID`	İşlem yapılacak firmanın kimliği	Firma bağlamı kullanan işlemlerde gönderilir.
`Content-Type`	`application/json`	JSON gövdeli POST isteklerinde gönderilir.

SecurityFirmUUID kullanıcı kimliği değildir. Firma değiştirildiğinde çağrılar yeni firma kimliğiyle sürdürülmelidir.

Güvenlik: Parola, token, envanter içeriği ve kişisel verileri loglamayın. Destek kayıtlarında yalnız gerekli işlem kimliklerini ve maskelenmiş değerleri kullanın.

Firma ve Envanter Dönemi

Alan	Açılış	Kapanış
`IdentificationNumber`	Firmanın VKN/TCKN'si
`BranchCode`	Şube yoksa `0000`
`PeriodStart`	`YYYY-01-01`	`YYYY-12-31`
`PeriodEnd`	`YYYY-01-01`	`YYYY-12-31`

PeriodStart ve PeriodEnd bir yıllık tarih aralığı değildir. Açılışta iki alan da aynı yılın 1 Ocak gününü, kapanışta iki alan da aynı yılın 31 Aralık gününü taşır. Firma, şube ve bu tek günlük tarih birlikte kayıt anahtarıdır; dönen Uuid sonraki tüm adımlarda saklanır.

Yanıt Zarfı

ServiceResponse<T> içindeki Data, Messages[], StatusCode ve IsSuccessful birlikte değerlendirilir. Sayfalı listelerde TotalRows ve TotalPages alanları bulunur. HTTP 200 yalnızca taşıma katmanının cevabıdır; envanterin GİB'de tamamlandığı anlamına gelmez.

{
  "Data": true,
  "Messages": [],
  "StackTrace": null,
  "StatusCode": 200,
  "TotalRows": 0,
  "TotalPages": 0,
  "IsSuccessful": true
}

Belirsiz sonuç: Timeout veya bağlantı kopmasında yeni kayıt açmadan önce firma, tarih ve Uuid ile mevcut özet sorgulanmalıdır.

Başarı Ölçütü

İstek cevabında IsSuccessful=true olmalı ve hata mesajı bulunmamalıdır.
Özet kaydı beklenen bir sonraki CurrentStatus değerine ilerlemelidir.
Onay öncesinde envanter ve berat önizlemelerindeki firma, şube, tarih, parça ve kayıt özetleri kaynak sistemle mutabık olmalıdır.
GİB sonucu tamamlandığında CurrentStatus=SentToGib olmalı ve GİB onaylı envanter beratı indirilebilmelidir.
İmzalı envanter XML'i ile GİB onaylı berat aynı Uuid altında arşivlenmelidir.