Başlangıç

API Temelleri

Kimlik doğrulama, ortak istek alanları, yanıt zarfı, firma ve dönem kimliği.

Bu sayfa, ilk API çağrısından dönem sonucunun izlenmesine kadar tüm endpointlerde ortak olan sözleşmeyi açıklar. İşlem örneklerine geçmeden önce oturum, firma bağlamı, dönem anahtarı ve yanıt zarfı birlikte uygulanmalıdır.

Başlamadan Önce

Hazırlık	Gerekli bilgi	Nerede kullanılır?	Kontrol
API erişimi	Ortamın Gateway API ana adresi	Tüm endpoint adreslerinin önünde	Test ve canlı ortam adreslerini karıştırmayın.
Kullanıcı	E-posta ve parola	`POST /api/Session/Login`	Parolayı yalnız oturum açma isteğinde gönderin.
Firma bağlamı	`SecurityFirmUuid`, VKN/TCKN ve şube kodu	Header ve işlem gövdeleri	Login cevabındaki firma ile işlem gövdesindeki firma aynı olmalıdır.
Dönem	Aynı ayın ilk ve son günü	Aktarım, üretim, özet ve gönderim işlemleri	Özel hesap dönemi ve parçalı ay göndermeyin.

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, defter içeriği ve kişisel veriler loglara yazılmamalıdır. Örneklerdeki değerler temsilidir.

Firma ve Dönem Kimliği

Alan	Tür	Kural
`IdentificationNumber`	string	İşlem yapılan firmanın VKN/TCKN'si.
`BranchCode`	string	Şube yoksa `0000`; şube varsa sözleşmedeki dört haneli kod.
`PeriodStart`	ISO 8601 datetime	Aylık dönemin ilk günü.
`PeriodEnd`	ISO 8601 datetime	Aynı ayın son günü.

Bu dört alan birlikte dönem anahtarını oluşturur. Şube kodunun veya tarih saatinin çağrılar arasında değişmesi aynı muhasebe döneminin farklı kayıtlar gibi değerlendirilmesine neden olabilir. Bir kayıt oluşturulduktan sonra response içindeki Uuid yerel ERP kaydına yazılmalı ve sonraki sorgularda birincil teknik izleme anahtarı olarak kullanılmalıdır.

Yanıt Zarfı

Endpointler ServiceResponse<T> döndürür. Data işlem verisini, Messages[] uyarı ve hataları, StatusCode servis sonucunu taşır. IsSuccessful, hata türünde mesaj bulunmadığında true olur. Sayfalı sonuçlarda TotalRows ve TotalPages ayrıca değerlendirilir. Yalnız HTTP 200'e bakarak işlemi tamamlandı saymayın.

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

Hata halinde Messages[] içindeki MessageType, MessageModel.Code, Message ve varsa Argument birlikte okunur:

{
  "Data": false,
  "Messages": [
    {
      "Service": null,
      "Action": "LedgerApproval",
      "MessageModel": {
        "Type": "LedgerMessage",
        "Code": "LedgerSummary.InvalidState"
      },
      "MessageType": 2,
      "Argument": null,
      "Message": "Defter özet durumu, gerçekleştirilmek istenen işlem için uygun değil"
    }
  ],
  "StackTrace": null,
  "StatusCode": 400,
  "TotalRows": 0,
  "TotalPages": 0,
  "IsSuccessful": false
}

Hata anahtarı: MessageType=2 hata seviyesidir. Programatik ayrım için yerelleştirilmiş Message metni yerine MessageModel.Type ve MessageModel.Code alanlarını kullanın. Service ve Action alanlarını yalnız izleme bağlamı olarak saklayın.

Durum	Güvenli davranış
HTTP 401	`Email` ve `Password` ile yeniden oturum açın; aynı işlem gövdesini körlemesine tekrarlamayın.
`Messages[]` hata içeriyor	Mesajı ilgili alan veya durumla eşleştirip düzeltin.
Timeout/bağlantı kopması	Yeni kayıt oluşturmadan önce firma, dönem veya `Uuid` ile mevcut sonucu sorgulayın.
Asenkron süreç başladı	`GetEntity` veya güncel özet sorgusuyla terminal duruma kadar izleyin.

Başarı Ölçütü

Bir çağrının başarılı olması ile e-Defter döneminin tamamlanması farklıdır. Aşağıdaki kanıtların tamamı oluşmadan dönem kapatılmış sayılmamalıdır.

İstek cevabında IsSuccessful=true olmalı ve hata türünde mesaj bulunmamalıdır.
Özet kaydı beklenen bir sonraki CurrentStatus değerine ilerlemelidir.
Onay öncesinde yevmiye, kebir ve berat önizlemeleri kaynak muhasebe toplamlarıyla mutabık olmalıdır.
GİB aşamasında paket sonucu olumlu olmalı ve GİB onaylı berat dosyaları erişilebilir olmalıdır.
İmzalı defterler ile GİB onaylı beratlar aynı firma, şube, dönem ve Uuid altında arşivlenmelidir.