API Temelleri
API Temelleri
Kimlik doğrulama, ortak header, response, hata ve belge kimliği sözleşmeleri.
Başlangıç noktası: Bu sözleşmeler hem giden hem gelen fatura endpointleri için ortaktır. İşleme özgü request ve response alanları yön bazlı API sayfalarında açıklanır.
Kimlik Doğrulama
Önce hesap bilgileriyle token alın. Dönen token'ı sonraki her çağrıda VbtAuthorization header'ına yazın.
POST/api/Account/Token
API oturumu için yetkilendirme token'ı üretir.
| Request | TokenRequestModel — Email, Password |
| Response | TokenResponseModel — Token |
Token JSON örneğini görüntüle
{
"Email": "entegrasyon@firma.com",
"Password": "GUCLU_PAROLANIZ"
}Ortak Header Sözleşmesi
| Header | Değer | Kullanım |
|---|---|---|
Content-Type | application/json | JSON request gövdesi taşıyan çağrılarda kullanılır. |
VbtAuthorization | Token endpointinden dönen değer | Token çağrısı dışındaki korumalı endpointlerde zorunludur. |
Response ve Hata Sözleşmesi
API sonuçları işlem verisini Data alanında taşır. Çağrının HTTP olarak tamamlanması, faturanın GİB veya karşı taraf yaşam döngüsünü tamamladığı anlamına gelmez; işleme ait durum endpointi ayrıca izlenir.
| Kontrol | Entegratör davranışı |
|---|---|
| HTTP başarısı | Response gövdesini ve işlem sonucunu okuyun; yalnız HTTP koduna göre belgeyi tamamlandı saymayın. |
| Doğrulama/iş kuralı hatası | Dönen mesajı request alanıyla eşleştirin, request'i düzelttikten sonra yeniden gönderin. |
| Timeout veya bağlantı kopması | Aynı belgeyi yeni kimlikle oluşturmadan önce ETTN ya da dış referansla sorgulayın. |
| Asenkron sonuç | Giden veya gelen yönün durum endpointini terminal sonuca kadar izleyin. |
Belge Kimlikleri
| Kimlik | Amaç | Kalıcı kullanım |
|---|---|---|
ETTN / UUId | Faturanın uçtan uca teknik kimliği | Sorgulama, durum, çıktı, kabul/red, iptal ve itiraz işlemlerinde ana korelasyon değeri olarak saklanır. |
InvoiceExternalId | Entegratörün dış sistem referansı | Giden fatura oluşturma tekrarlarını ve timeout mutabakatını yönetmek için tekil tutulur. |
InvoiceNumber | Belgenin görünen numarası | ERP ve arşiv kayıtlarında ETTN ile birlikte saklanır; tek başına teknik korelasyon kimliği yerine kullanılmaz. |
API Yüzeyleri ve Sonraki Adım
| İhtiyaç | Kaynak |
|---|---|
| Giden fatura oluşturma, gönderme ve durum takibi | Giden Fatura Entegratör API |
| Gelen faturayı alma, yanıtlama ve ERP'ye işleme | Gelen Fatura Entegratör API |
| Portal ekranlarının kullandığı işlemler | Giden ve gelen Portal API |
| Çalıştırılabilir gövdeler | Giden request örnekleri ve gelen işlem örnekleri |