efatura-api-spring-boot

Türkçe dokümantasyon için aşağıya bakın / See below for Turkish documentation.

English Summary

A Spring Boot 3.4.4 / Java 17 REST API that wraps Turkey's GİB e-Arşiv (eArchive) electronic invoice portal. This is the only open-source Spring Boot / Java implementation of the GİB eArşiv dispatch API available on GitHub.

What it does

Create, list, fetch, and cancel e-Arşiv invoices (draft + SMS-OTP approval flow)
Export invoices as HTML or PDF (unsigned draft or signed final)
Look up company info by tax/ID number (VKN / TCKN)
Manage user profile on the eArşiv portal
Trigger and verify SMS OTP to approve invoices
Targets both the GİB test portal (earsivportaltest.efatura.gov.tr) and the live portal (earsivportal.efatura.gov.tr) via Spring profiles

Quick start (test environment — no real credentials needed)

git clone https://github.com/iamhusrev/efatura-api-spring-boot.git
cd efatura-api-spring-boot
mvn spring-boot:run -Dspring-boot.run.profiles=test
# Swagger UI: http://localhost:8080/swagger-ui.html
curl -X POST http://localhost:8080/api/auth/test-credentials

Tech stack

Java 17 · Spring Boot 3.4.4 · Spring RestClient · openhtmltopdf 1.0.10 · jsoup 1.17.2 · SpringDoc OpenAPI 2.8.6 · Lombok · JUnit 5 + Mockito

Disclaimer

This is an independent open-source project. It is not affiliated with, endorsed by, or approved by the Turkish Revenue Administration (GİB). All tax and legal responsibilities rest with the user. See DISCLAIMER.md for full details.

Türkçe Dokümantasyon

Türkiye eArşiv (GİB) portalı ile entegre olan Spring Boot tabanlı REST API servisi. Fatura oluşturma, sorgulama, iptal, HTML/PDF çıktı ve firma sorgu işlemlerini tek bir API üzerinden sunar.

⚠️ Sorumluluk Reddi

Bu proje bağımsız bir açık kaynak çalışmasıdır; Gelir İdaresi Başkanlığı (GİB) ile resmi bir ilişkisi yoktur. Üretilen fatura/verilerin doğruluğu ve mevzuata uygunluğu kullanıcının sorumluluğundadır. Üretim kullanımı öncesi mali müşavirinize danışın. Detay için mutlaka DISCLAIMER.md dosyasını okuyun.

Özellikler

✅ Taslak fatura oluşturma, sorgulama, iptal
✅ Fatura HTML ve PDF çıktısı (openhtmltopdf ile)
✅ Tarih aralığına göre fatura listeleme (kestiğin ve sana kesilen ayrı ayrı)
✅ VKN/TCKN ile firma bilgisi sorgulama
✅ Kullanıcı/firma profil bilgilerini getir/güncelle
✅ SMS ile fatura doğrulama
✅ Test ve prod ortamları için ayrı Spring profilleri
✅ Stateless token-based auth (X-Earsiv-Token header)
✅ Swagger UI + OpenAPI 3 dokümantasyonu
✅ Merkezi hata yönetimi (@RestControllerAdvice)

Teknoloji Stack

Kategori	Teknoloji
Dil	Java 17+
Framework	Spring Boot 3.4.4
Build	Maven
HTTP Client	Spring `RestClient` (JDK HttpClient)
PDF Üretim	`openhtmltopdf-pdfbox` 1.0.10
HTML Parsing	`jsoup` 1.17.2
Validation	Jakarta Validation
Boilerplate	Lombok
API Docs	SpringDoc OpenAPI 2.8.6
Test	JUnit 5 + Mockito

Hızlı Başlangıç

# 1. Klonla
git clone https://github.com/iamhusrev/efatura-api-spring-boot.git
cd efatura-api-spring-boot

# 2. Test ortamında ayağa kaldır (GİB test portalı)
mvn spring-boot:run -Dspring-boot.run.profiles=test

# 3. Otomatik test credentials ile token al
curl -X POST http://localhost:8080/api/auth/test-credentials

# 4. Swagger UI'da keşfet
open http://localhost:8080/swagger-ui.html

İlk 5 dakikada Postman collection ile daha hızlı başlamak istersen → Postman ile Test.

Derleme ve Çalıştırma

# Derle
mvn clean compile

# Testleri çalıştır
mvn test

# Test ortamında ayağa kaldır (GİB test: earsivportaltest.efatura.gov.tr)
mvn spring-boot:run -Dspring-boot.run.profiles=test

# Prod ortamında ayağa kaldır (GİB canlı: earsivportal.efatura.gov.tr)
mvn spring-boot:run -Dspring-boot.run.profiles=prod

# JAR olarak paketle ve çalıştır
mvn clean package
java -jar target/efatura-api-spring-boot-1.0.0-SNAPSHOT.jar --spring.profiles.active=test

Uygulama URL'i: http://localhost:8080 (varsayılan port, SERVER_PORT environment variable ile değiştirilebilir)

Konfigürasyon

Server Port

Varsayılan: 8080
Değiştirmek için: SERVER_PORT environment variable'ını ayarla

# Örnek: port 9000'de çalıştır
SERVER_PORT=9000 mvn spring-boot:run -Dspring-boot.run.profiles=test
# veya JAR ile
java -jar target/efatura-api-*.jar --SERVER_PORT=9000 --spring.profiles.active=test

GİB API Endpoint'leri

GİB endpoint'leri ve login komutu src/main/resources/application*.yml dosyalarında tanımlıdır:

earsiv:
  base-url: https://earsivportal.efatura.gov.tr
  dispatch-path: /earsiv-services/dispatch
  token-path: /earsiv-services/assos-login
  esign-path: /earsiv-services/esign
  download-path: /earsiv-services/download
  login-command: anologin   # test ortamında "login"

Profil	Base URL	Login Command
`test`	`earsivportaltest.efatura.gov.tr`	`login`
`prod` (default)	`earsivportal.efatura.gov.tr`	`anologin`

Kimlik bilgilerini asla koda veya konfig dosyasına gömmeyin. Production'da environment variable veya secret manager kullanın.

Fatura Yaşam Döngüsü

GİB eArşiv portalında tüm faturalar önce taslak olarak doğar, sonra SMS OTP ile onaylanır:

  POST /api/invoices                    (taslak oluştur — onayDurumu: "Onaylanmadı")
         │
         ▼
  POST /api/sms/send                    (GİB'den SMS tetikle — operationId döner)
         │
         ▼
  POST /api/sms/verify  {code, oid,     (kullanıcının girdiği 6 haneli kod)
                         invoices:[ettn]}
         │
         ▼
  Fatura "Onaylandı" statüsüne geçer; HTML/PDF artık imzalı olarak alınabilir.

İp ucu: GET /api/invoices?status=onaysiz ile sadece onay bekleyen faturaları, status=onayli ile imzalı faturaları filtreleyebilirsiniz.

REST Endpoint'leri

Tüm endpoint'ler (/api/auth/* hariç) X-Earsiv-Token header'ı gerektirir.

Method	Endpoint	Açıklama
POST	`/api/auth/login`	Kullanıcı adı + şifre ile giriş
POST	`/api/auth/test-credentials`	Test ortamı için otomatik credential + token
POST	`/api/auth/logout`	Çıkış yap
GET	`/api/company/{taxNumber}`	VKN/TCKN ile firma sorgula
GET	`/api/user-info`	Kullanıcı profilini getir
PUT	`/api/user-info`	Kullanıcı profilini güncelle
POST	`/api/invoices`	Taslak fatura oluştur
GET	`/api/invoices?startDate=&endDate=&status=hepsi\|onayli\|onaysiz`	Kestiği faturaları listele
GET	`/api/invoices/issued-to-me?startDate=&endDate=`	Kesilen faturaları listele
GET	`/api/invoices/{uuid}`	Tek fatura detayı
GET	`/api/invoices/{uuid}/html?signed=true`	Fatura HTML
GET	`/api/invoices/{uuid}/pdf?signed=true`	Fatura PDF
GET	`/api/invoices/{uuid}/download-url?signed=true`	Fatura indirme URL'i
DELETE	`/api/invoices/{uuid}`	Fatura iptal
POST	`/api/sms/send`	SMS doğrulama başlat
POST	`/api/sms/verify`	SMS kodunu doğrula

Tarih formatı: DD/MM/YYYY (örn. 01/03/2026)

Swagger UI

Uygulama ayağa kalktıktan sonra:

Swagger UI: http://localhost:8080/swagger-ui.html
OpenAPI JSON: http://localhost:8080/v3/api-docs

Tüm endpoint'leri tarayıcıdan try-out butonu ile test edebilirsin.

Postman ile Test

Repo içinde hazır Postman koleksiyonu bulunur: postman/

Kurulum

Postman'i aç → Import → postman/efatura-api.postman_collection.json ve postman/efatura-local.postman_environment.json dosyalarını içeri al
Sağ üstten eFatura Local environment'ını seç
Environment değişkenlerine username (VKN/TCKN) ve password bilgilerini gir

Token Otomasyonu

Login isteğini çalıştırdığında cevaptaki token otomatik olarak token değişkenine yazılır (test script'i yapar)
Sonraki tüm istekler X-Earsiv-Token: {{token}} header'ıyla otomatik gider
Login atmadan başka bir isteği çalıştırmaya çalışırsan → collection seviyesindeki pre-request script seni "Token yok!" hatasıyla uyarır
Fatura listeleme yaptığında ilk ETTN otomatik ettn değişkenine yazılır; HTML/PDF/detay istekleri bu değeri kullanır

Tipik Akış

1. Login (test ortamı — otomatik credential)  → token set
2. Kullanıcı bilgilerini getir                → profil kontrol
3. Taslak fatura oluştur                      → yeni ETTN set
4. Fatura HTML / PDF                          → çıktıyı al
5. (Opsiyonel) Fatura iptal

Mimari

Katmanlı (layered) mimari, endpoint → service → HTTP client zinciri:

HTTP İstemcisi
      ↓ (X-Earsiv-Token)
  Controller  ───────→  GlobalExceptionHandler
      ↓
   Service
      ↓
 EarsivApiClient (düşük seviye GIB dispatch)
      ↓
   GİB API (earsivportal.efatura.gov.tr)

Paket özeti:

controller/ — REST endpoint'leri (5 controller)
service/ — İş mantığı; EarsivApiClient ortak GİB dispatch logic'i
model/ — Invoice (47 alan), InvoiceLineItem, UserInformation + DTO'lar + enum'lar
mapper/ — EN ↔ TR key dönüşümü (GİB API Türkçe key ister)
exception/ — Özel exception'lar + @RestControllerAdvice ile merkezi handling
config/ — RestClient bean, @ConfigurationProperties, OpenAPI konfig

Detaylı paket yapısı ve akış diyagramları için → PROJECT_STRUCTURE.md

Katkıda Bulunma

Katkılarınız memnuniyetle karşılanır:

Repoyu fork'la
Bir feature branch aç (git checkout -b feature/yeni-ozellik)
Değişikliklerini commit'le (git commit -m 'feat: yeni özellik eklendi')
Branch'i push'la (git push origin feature/yeni-ozellik)
Pull Request aç

Büyük değişiklikler için önce bir Issue açıp tartışalım.

Hata bulduysan: Issue tracker'dan bildir; mümkünse repro adımlarını ve stack trace'i ekle.

Yasal Uyarı

Bu proje bağımsız bir açık kaynak çalışmasıdır. T.C. Gelir İdaresi Başkanlığı (GİB) tarafından geliştirilmemiş, desteklenmemiş veya onaylanmamıştır.

Bu yazılımla oluşturulan her türlü fatura ve belge üzerindeki mali, hukuki ve cezai sorumluluk tamamen kullanıcıya aittir. Üretim ortamında kullanmadan önce yetkili bir mali müşavire (SMMM/YMM) danışın.

Tam sorumluluk reddi beyanı için → DISCLAIMER.md

Teşekkürler

GİB eArşiv portal ekibi — Public test ortamını kamuya açık tuttukları için.

Lisans

Bu proje MIT lisansı ile lisanslanmıştır. Detaylar için LICENSE dosyasına bakınız.

Kullanım öncesi mutlaka DISCLAIMER.md dosyasındaki sorumluluk reddi beyanını okuyun.

GitHub Topics (önerilen): spring-boot · java · efatura · e-fatura · earsiv · gib · e-invoice · turkey · rest-api · java17

Name		Name	Last commit message	Last commit date
postman		postman
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
DISCLAIMER.md		DISCLAIMER.md
LICENSE		LICENSE
PROJECT_STRUCTURE.md		PROJECT_STRUCTURE.md
README.md		README.md
pom.xml		pom.xml

Navigation Menu

Repository files navigation

efatura-api-spring-boot

English Summary

What it does

Quick start (test environment — no real credentials needed)

Tech stack

Disclaimer

Türkçe Dokümantasyon

⚠️ Sorumluluk Reddi

İçindekiler

Özellikler

Teknoloji Stack

Hızlı Başlangıç

Derleme ve Çalıştırma

Konfigürasyon

Server Port

GİB API Endpoint'leri

Fatura Yaşam Döngüsü

REST Endpoint'leri

Swagger UI

Postman ile Test

Kurulum

Token Otomasyonu

Tipik Akış

Mimari

Katkıda Bulunma

Yasal Uyarı

Teşekkürler

Lisans

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

efatura-api-spring-boot

English Summary

What it does

Quick start (test environment — no real credentials needed)

Tech stack

Disclaimer

Türkçe Dokümantasyon

⚠️ Sorumluluk Reddi

İçindekiler

Özellikler

Teknoloji Stack

Hızlı Başlangıç

Derleme ve Çalıştırma

Konfigürasyon

Server Port

GİB API Endpoint'leri

Fatura Yaşam Döngüsü

REST Endpoint'leri

Swagger UI

Postman ile Test

Kurulum

Token Otomasyonu

Tipik Akış

Mimari

Katkıda Bulunma

Yasal Uyarı

Teşekkürler

Lisans

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages