Hızlı Başlangıç
Bu rehber, eKüpSoft API'sine sıfırdan entegrasyon yaparken izleyeceğiniz adımları sırasıyla anlatır.
1. Postman dosyalarını indirin
Sayfanın üst kısmındaki "Postman Dosyalarını İndir" linkiyle ekup-postman.zip'i
indirin. Zip; koleksiyon (OutSource.postman_collection.json), environment
(OutSource.postman_environment.json) ve bir README içerir. İkisini de Postman'e
Import edin ve environment'ı seçin.
2. Hangi ortama karşı çalışacağınızı belirleyin
Geliştirme ve entegrasyon testleri için test/sandbox ortamını kullanın — canlı ortama karşı test yapmak gerçek GİB/HSM gönderimine yol açabilir. Ayrıntılar için Test Ortamı / Sandbox sayfasına bakın.
Postman environment'ta baseUrl değişkenini test adresiyle doldurun:
https://webservis.ekupbilisim.com/api/outsource-test
3. Giriş yapıp token alın
Giriş Yap - Login ucuna username/password ile istek atın:
curl -X POST --location 'https://webservis.ekupbilisim.com/api/outsource-test/auth/login' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"username": "VKN_TCKN/KullanıcıAdı",
"password": "Şifre"
}'
Postman kullanıyorsanız dönen JWT, koleksiyondaki test script'i tarafından otomatik
olarak {{token}} değişkenine kaydedilir — elle kopyalamanıza gerek yoktur. Diğer tüm
uçlar bu token'ı Authorization: Bearer {{token}} olarak kullanır.
4. Basit bir istekle ısının
Parametresiz bir uçla başlamak, kimlik doğrulamanızın çalıştığını doğrulamak için iyi bir ilk adımdır, örneğin Nace Listesi:
curl -X GET --location 'https://webservis.ekupbilisim.com/api/outsource-test/nace/list' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'
Başarılı bir cevap {"error": 0, ...} şeklinde döner — cevap zarfının genel yapısı için
Cevap Yapısı bölümüne bakın.
5. İlk belgenizi gönderin ve durumunu sorgulayın
Gerçek entegrasyon akışı belge gönder → durumunu sorgula şeklindedir. Örnek olarak Fatura Gönderim (JSON) ucuyla bir e-Fatura gönderin — tam istek gövdesi o sayfada. Cevap şöyle döner:
{
"error": 0,
"message": "İşlem başarıyla tamamlandı",
"extra": {
"id": "01k1x8rykgcnjv07zgf8h07sey",
"envelopeId": "32a0fa61-1aa9-47ef-123d-30f72e326369",
"signedXml": ["base64"],
"isEInvoice": true
}
}
Dönen envelopeId'yi Fatura Durum Sorgulama ucuna
uuid olarak gönderin:
curl -X POST --location 'https://webservis.ekupbilisim.com/api/outsource-test/invoice/status' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••' \
--data '{
"uuid": ["32a0fa61-1aa9-47ef-123d-30f72e326369"]
}'
Cevapta GİB durumu (gibStatus), zarf bilgisi ve varsa uygulama yanıtı bilgisi döner.
6. Hata aldığınızda
Her endpoint'in kendi dokümantasyon sayfasındaki Cevaplar (Responses) bölümü, o uca özgü olası hataları örnekleriyle listeler. Tüm servislerde görülebilecek hata mesajlarının tek referansı için Hata Kodları Referansı sayfasını kullanın.
7. Aradığınızı bulamıyorsanız
Sayfanın üst kısmındaki arama kutusunu kullanarak endpoint adı, parametre veya hata mesajına göre arama yapabilirsiniz.
8. Canlıya geçiş
Entegrasyonunuz test ortamında sorunsuz çalıştıktan sonra, baseUrl'i canlı adresle
değiştirin:
https://webservis.ekupbilisim.com/api/outsource
Artık gönderdiğiniz belgeler gerçek olarak GİB'e iletilir.