Ana içeriğe geç

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.