Harici Entegrasyon Dokümanları

ApiKey Erişimi ve İş Ortağı Talebi

Web servisleri kullanabilmek için firmanıza özel API anahtarı tanımlanmalıdır. Anahtarınız varsa aşağıdaki alandan hızlıca kontrol edebilirsiniz. Anahtarınız yoksa iş ortağı talep formunu doldurun.

Giriş ve Kimlik Doğrulama

API erişimi kullanıcı adı/şifre ile değil, firma adına üretilen API anahtarı ile yapılır. Anahtar her istekte `Authorization` veya `X-API-Key` header alanlarından biriyle gönderilmelidir.

Authorization: Bearer API_TOKEN
Content-Type: application/json

Token Yetkileri

Modül Kataloğu

Hızlı Teknoloji RestApi dokümanındaki modüller referans alınarak servis aileleri bizim okunur URL standardımıza çevrilmiştir. Eski uç adlarını sadece karşılaştırma amacıyla gösteriyoruz; entegratörlerin kullanacağı adresler /api/v1 ile başlayan 4C adresleridir. Kaynak karşılaştırma: Hızlı RestApi Swagger.

Giriş, Hesap ve Token

Entegrasyon firması token doğrulama ve hesap bilgisi işlemleri.

Kontör ve Kullanım

Kalan kontör, hareket ve müşteri bazlı kullanım servisleri.

Müşteri, Cari ve Mükellef

Cari kart, GİB mükellef ve müşteri durum sorguları.

e-Fatura ve Genel Belge

Modelden veya UBL XML üzerinden belge oluşturma, listeleme, dosya alma ve iptal.

Uygulama Yanıtı ve İrsaliye

Ticari fatura kabul/ret yanıtları, irsaliye ve irsaliye yanıtları.

e-Defter ve Saklama

e-Defter süreç oluşturma, aktif/yıl bazlı sorgulama, berat işlem kodları, indirme ve sıra yönetimi servisleri.

Diğer e-Belge Modülleri

e-Arşiv, e-SMM, e-Müstahsil, e-Adisyon, e-Döviz ve e-Gider Pusulası servisleri.

XSLT, Tasarım, Kod ve Yardımcı Servisler

Tasarım, stok, prefix, kur, dashboard ve e-posta yardımcı servisleri.

İç WebApi Aracı Servisleri

4C Portal dış entegratörden isteği alır; GİB, e-Belge ve özel entegratör işlemleri için aşağıdaki webapi.4cteknoloji.com aracı servislerine gider. Bu URL’ler dış entegratörlerin çağıracağı URL standardı değildir; dış entegratörler https://eportal-test.4cteknoloji.com/api/v1 altındaki 4C API uçlarını kullanır.

SOAP WSDL Envanteri

REST Swagger Envanteri

Veri Sözlüğü ve Alan Eşleştirme

Entegratörler eski model adlarıyla çalışıyorsa aşağıdaki eşleştirmeyi kullanabilir. Yeni geliştirmelerde sol taraftaki isimler yerine “4C Alanı” sütunundaki JSON alanları tercih edilmelidir.

Kontör Sorgulama

Firmanın toplam, harcanan ve kalan kontör bilgisini döndürür.

curl -H "Authorization: Bearer API_TOKEN" \
  https://eportal-test.4cteknoloji.com/api/v1/credits

{
  "credit": 1000,
  "spent": 120,
  "remaining": 880,
  "document_costs": {
    "efatura": {"label": "E-Fatura", "cost": 2},
    "earsiv": {"label": "E-Arşiv", "cost": 1}
  }
}

Müşteri Sorgulama

VKN/TCKN, unvan, ad veya soyad ile müşteri araması yapılır.

curl -H "Authorization: Bearer API_TOKEN" \
  "https://eportal-test.4cteknoloji.com/api/v1/customers?search=0010969949"

curl -H "Authorization: Bearer API_TOKEN" \
  https://eportal-test.4cteknoloji.com/api/v1/customers/0010969949

e-Fatura Oluşturma ve Gönderme

`send=false` gönderilirse taslak oluşturulur. `send=true` gönderilirse belge, paneldeki “GİB'e Gönder” akışıyla kaydedilir ve e-Fatura kontörü düşülür.

{
  "send": true,
  "scenario": "ticari_fatura",
  "invoice_type": "satis",
  "invoice_date": "2026-07-06",
  "invoice_time": "14:30",
  "currency": "TRY",
  "currency_rate": 1,
  "receiver_tag": "urn:mail:defaultpk@gib.gov.tr",
  "receiver": {
    "vkntckn": "11111111111",
    "title": "Örnek Alıcı LTD ŞTİ",
    "country": "TR",
    "city_id": 34,
    "district_id": 430,
    "address": "Beykoz / İstanbul",
    "email": "muhasebe@example.com"
  },
  "lines": [
    {
      "name": "Danışmanlık Hizmeti",
      "quantity": 1,
      "unit": "C62",
      "unit_price": 1000,
      "vat_rate": 20
    }
  ]
}

Özel Durumlar

e-Defter Süreçleri

e-Defter tarafında portal iki katmanlı çalışır: dış entegratör API isteğini 4C Portal’a gönderir, portal da webapi.4cteknoloji.com üzerindeki e-Defter aracı servisleriyle GİB süreçlerini yürütür. İç WebApi bağlantısı EdefterGateway ile çalışır; dışarı açık /api/v1/edefter uçları aşağıdaki standartta aktif edilmiştir.

Süreç Oluşturma

{
  "period_covered_start": "2026-01-01",
  "content_base64": "UEsDBBQAAAAIA...",
  "content_type": "YEVMİYE",
  "batch_id": 1024,
  "sign_by_integrator": true,
  "transfer": false
}

Aktif Süreç ve Yıl Bazlı Liste

curl -H "Authorization: Bearer API_TOKEN" \
  "https://eportal-test.4cteknoloji.com/api/v1/edefter/read?year=2026"

İşlem Kodları

Hata Kodları

{
  "message": "GİB/e-Belge kural kontrolü başarısız.",
  "errors": {
    "return_invoices": [
      "İade faturalarında iade edilen fatura numarası ve tarihi girilmelidir."
    ]
  }
}

Örnek İstekler

Hesap Bilgisi

curl -H "Authorization: Bearer API_TOKEN" \
  https://eportal-test.4cteknoloji.com/api/v1/me

e-Fatura Listesi

curl -H "Authorization: Bearer API_TOKEN" \
  "https://eportal-test.4cteknoloji.com/api/v1/einvoices?vkntckn=11111111111"

Hazır UBL XML Önizleme

{
  "document_type": "efatura",
  "xml_base64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+..."
}

Servis Testleri

Harici entegrasyon servisleri için feature testleri eklendi. Testler SQLite bellek veritabanında çalışır; canlı müşteri veya fatura verisine dokunmaz.

php artisan test --filter=ExternalApiTest

Canlı Sağlık Kontrolü

curl -i https://eportal-test.4cteknoloji.com/api/v1/credits
# 401 beklenir: API anahtarı zorunlu

curl -H "Authorization: Bearer API_TOKEN" https://eportal-test.4cteknoloji.com/api/v1/me
# 200 beklenir: firma ve token bilgisi döner