API dokümantasyonu

API Dokümantasyonu

Vergi Merkezi uygulamalarınız için entegrasyon rehberi.

143REST işlemi 93Turkcell işlemi 57Sık sorulan soru

PDF rehberiAynı içeriğin paylaşılabilir sürümü OpenAPI sözleşmesiAlanlar, yanıtlar ve işlem şemaları Postman koleksiyonuYalnızca okuma istekleri

⌘ K

Başlamadan önce

Hesabınızı bağlayın, yetkili firmayı seçin ve doğru işlem akışını kullanın.

Bu rehber, Vergi Merkezi müşteri REST API’sini uygulamasına bağlayan geliştiriciler içindir. Kullanıcı arayüzünde Ajan API olarak geçen servis, normal yazılımlar ve sunucu uygulamaları tarafından da kullanılabilir. Yapay zekâ kullanma zorunluluğu yoktur.

İhtiyaç	Müşteri API yolu	Koşul
Şirket aramak	GET /agent/einvoice/recipients	Firma erişimi, hazırlanmış mükellef indeksi
Resmî belge oluşturmak	/agent/einvoice/operations altında ilgili işlem	Doğrulanmış Turkcell bağlantısı
PDF ve UBL indirmek	GET /agent/einvoice/documents/{id}/{format}	Belge firmasının UBL üzerinden doğrulanması
Gelen fatura ve kabul veya ret	Mevcut accounting/inbox uçları veya işlem kataloğu	İlgili firma ve sağlayıcı servis yetkisi
Muhasebe kaydı oluşturmak	record-invoice ve taslak akışı	Ayrı muhasebe işlemi

Ana servis adresi: https://portal.vergimerkezi.com.tr/api/v1. Bu adresteki işlemler üretim ortamındadır. Rehberin ve Swagger’ın okunması için token gerekmez. API işlem çağrıları için müşteri hesabı ve Bearer token gerekir.

Örneklerdeki 123, 456 ve 789 gibi kimlikler temsilidir. Gerçek company_id değerini companies yanıtından, diğer kimlikleri ilgili oluşturma veya listeleme yanıtından alın. Rehberde gerçek müşteri bilgisi, vergi kimliği veya çalışan API anahtarı bulunmaz.

Kimlik doğrulama ve firma yetkisi

Vergi Merkezi tokenı kullanıcıya aittir. Firma erişimi her ilgili işlemde ayrıca kontrol edilir.

Müşteri hesabınızla portala girin ve gerekiyorsa güncel kullanıcı sözleşmesini kabul edin.
Profil ekranından API token oluşturun veya POST /auth/login kullanın.
Tokenı sunucunuzun gizli değerler deposunda saklayın.
GET /agent/companies ile erişebildiğiniz firmaları alın.
İlgili çağrılarda seçtiğiniz firmanın company_id değerini gönderin.

Her yetkili çağrıda kullanılan başlıklar

Authorization: Bearer YOUR_VERGI_MERKEZI_TOKEN
Accept: application/json
Content-Type: application/json

Token rastgele üretilen opak bir değerdir; JWT değildir. Mevcut müşteri token uygulamasında süreye bağlı bir son kullanma alanı veya refresh token akışı yoktur. 401 mesajı genel olarak geçersiz veya süresi dolmuş token diyebilir. Yeni token üretimi, silinme veya hesap değişikliği erişimi etkileyebilir.

Giriş isteği

POST /auth/login
{
  "email": "developer@example.com",
  "password": "YOUR_ACCOUNT_PASSWORD"
}

Başarılı giriş, temsili yanıt

{
  "success": true,
  "data": {
    "token": "YOUR_NEW_TOKEN",
    "user_id": 123
  }
}

Bu API yalnızca client rolündeki hesapları kabul eder. Yönetici API’sinin tokenları ve kapsamları ayrıdır. Müşteri tokenı, kullanıcının bağlı olduğu firmalar dışındaki verilere erişim sağlamaz. company_id bilgisini portalda son seçili firmadan varsaymayın; çağrı bazında açıkça iletin.

Girişte zorunlu sözleşme onayı eksikse 403 alınır. Onay portalda tamamlanır. Token paylaşımıyla farklı kişilerin hesapları arasında yetki devri yapılmaz. Mevcut müşteri tokenında uygulama bazında ayrı kapsam veya ayrı token iptal uç noktası bulunmaz.

İlk başarılı çağrı

Önce okuma işlemiyle bağlantıyı doğrulayın. Ardından ihtiyacınıza uygun kayıt akışına geçin.

cURL ile firma listesi

export VM_API_BASE="https://portal.vergimerkezi.com.tr/api/v1"
# VM_API_TOKEN degerini guvenli ortam degiskeni olarak saglayin.
curl --connect-timeout 10 --max-time 30 \
  "$VM_API_BASE/agent/companies" \
  --header "Authorization: Bearer $VM_API_TOKEN" \
  --header "Accept: application/json"

Firma listesi, temsili yanıt

{
  "success": true,
  "data": {
    "companies": [
      {"id": 123, "title": "Örnek Firma", "tax_id": "EXAMPLE_TAX_ID", "tax_office": "Örnek"}
    ],
    "currency": "TRY"
  }
}

Python, okuma örneği

import os
import requests

base = "https://portal.vergimerkezi.com.tr/api/v1"
token = os.environ["VM_API_TOKEN"]
company_id = int(os.environ["VM_COMPANY_ID"])
session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {token}",
    "Accept": "application/json",
})

r = session.get(f"{base}/agent/companies", timeout=(10, 30))
r.raise_for_status()
result = r.json()
if result.get("success") is not True:
    raise RuntimeError(result.get("error", "API error"))
if company_id not in {c["id"] for c in result["data"]["companies"]}:
    raise RuntimeError("Selected company is not authorized")

r = session.get(f"{base}/agent/lookup/caris",
                params={"company_id": company_id, "per_page": 20},
                timeout=(10, 30))
r.raise_for_status()
print(r.json()["data"])

JavaScript, sunucu tarafı okuma örneği

const base = "https://portal.vergimerkezi.com.tr/api/v1";
const token = process.env.VM_API_TOKEN;
const companyId = Number(process.env.VM_COMPANY_ID);
if (!token || !Number.isInteger(companyId)) throw new Error("Missing configuration");

async function read(path, params = {}) {
  const url = new URL(base + path);
  for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
    signal: AbortSignal.timeout(30000)
  });
  const body = await response.json();
  if (!response.ok || body.success === false) {
    throw new Error(body.error || body.message || `HTTP ${response.status}`);
  }
  return body.data;
}

const { companies } = await read("/agent/companies");
if (!companies.some(c => c.id === companyId)) throw new Error("Unauthorized company");
console.log(await read("/agent/lookup/items", { company_id: companyId, per_page: 20 }));

JavaScript örneği fetch ve AbortSignal.timeout destekleyen sunucu ortamı içindir. Python örneği requests paketini kullanır. Örnekler otomatik token yenilemez ve yazma işlemi yapmaz. İlk gelen firmayı otomatik seçmek yerine, kullanıcı veya uygulama ayarından doğrulanmış firma kimliğini kullanın.

İstek, yanıt ve veri kuralları

Alan adları ve enum değerleri sözleşmenin parçasıdır; arayüzdeki Türkçe etiketlerle değiştirilmez.

Konu	Kural
Taşıma	HTTPS. İstek ve yanıt gövdeleri JSON. UTF 8 metin.
Başlıklar	Authorization: Bearer, Accept: application/json. JSON gövdelerinde Content-Type: application/json.
Kimlikler	Yerel company_id, document_id, cari_id ve item_id tamsayıdır. Sağlayıcı belge UUID’si başka bir kimliktir.
Tarih	Takvim tarihini YYYY-MM-DD biçiminde gönderin. Tarih ile tarih ve saat alanlarını karıştırmayın.
Tutar	JSON sayı kullanın: 120.50. Binlik ayırıcı, TL işareti veya ondalık virgül göndermeyin.
Vergi kimliği	Metin olarak taşıyın; baştaki sıfırları kaybetmeyin.
Boolean	JSON gövdesinde true veya false. Sorgu parametresinde Laravel doğrulaması için 1 veya 0 tercih edin.
Boş değer	İsteğe bağlı alanı göndermemek genellikle en açık yoldur. null kabulü alanın nullable kuralına bağlıdır.
GET parametreleri	Query string içinde gönderilir. company_id ve filtreleri GET gövdesine yerleştirmeyin.
Bilinmeyen alan	Sunucu alanı yok sayabilir. Gönderdiğiniz her alanın saklandığını varsaymayın; yanıttan kontrol edin.

Standart başarılı yanıt

{"success": true, "data": {"document_id": 456, "document_status": "draft"}}

İş kuralı veya yetki hatası

{"success": false, "error": "Geçersiz veya yetkisiz şirket.", "code": 403}

Laravel doğrulama hatası, diğer geçerli biçim

{"message": "company id alanı zorunludur.", "errors": {"company_id": ["company id alanı zorunludur."]}}

Hata okuyucunuz hem error alanını hem message ve errors alanlarını desteklemelidir. Bilgi uçları, ham OpenAPI ve sağlayıcı yanıtları aynı success zarfını kullanmayabilir. Önce HTTP durumunu ve Content-Type değerini değerlendirin.

Sayfalama her liste için aynı değildir. Cari ve stok listelerinde per_page üst sınırı 500, evrak ve ekstrelerde çoğunlukla 200’dür. Yanıttaki current_page, last_page, total ve per_page alanlarını kullanın. page desteğini işlem referansından kontrol edin. Tek bir sayfayı tüm kayıtlar olarak yorumlamayın.

GET /agent/products, Vergi Merkezi’nin hizmet ve kontör kataloğudur. Firmanın stok ve hizmet kartları GET /agent/lookup/items üzerinden okunur. Bu iki katalogdaki kimlikler birbirinin yerine kullanılmaz.

Evrak ve muhasebe akışı

Faturanın muhasebeye alınması, resmî faturanın oluşturulması ve gönderilmesinden farklı bir işlemdir.

GET /agent/companies ile firmayı doğrulayın.
Gider kaydı için gerekiyorsa GET /agent/accounting/categories ile category anahtarını bulun.
Kullanıcı onayı gereken akışta POST /agent/accounting/record-invoice-draft çağırın.
Yanıttaki document_id ve draft_summary bilgilerini kullanıcıya gösterin.
Onaydan sonra POST /agent/accounting/confirm-draft/{id} çağırın.
GET /agent/accounting/document/{id}?company_id=... ile yerel kaydı kontrol edin.

Yerel muhasebe taslağı

POST /agent/accounting/record-invoice-draft
{
  "company_id": 123,
  "type": "gider",
  "invoice_date": "2026-10-30",
  "amount": 120.00,
  "matrah": 100.00,
  "kdv_amount": 20.00,
  "kdv_rate": 20,
  "supplier_name": "Örnek Tedarikçi",
  "invoice_no": "EXAMPLE20260000001",
  "description": "Örnek hizmet gideri",
  "create_booking": true
}

Taslak yanıtının temel alanları, temsili

{
  "success": true,
  "data": {
    "document_id": 456,
    "draft_summary": {
      "invoice_date": "2026-10-30", "type": "gider", "amount": 120.00,
      "supplier_name": "Örnek Tedarikçi", "invoice_no": "EXAMPLE20260000001"
    },
    "confirm_url": "https://portal.vergimerkezi.com.tr/api/v1/agent/accounting/confirm-draft/456"
  }
}

Taslak yanıtında defter tipine göre transaction_id ve transaction_status da bulunabilir. record-invoice doğrudan evrak oluşturur ve create_booking varsayılanı true olduğundan muhasebe fişi de oluşturabilir. Bu uç ayrıca kullanıcı onayı beklemez. Kendi uygulamanızda onay gereksinimini işlemden önce karşılayın.

Defter tipi	Taslak aşaması	Kesinleştirme
Bilanço	create_booking açıksa taslak yevmiye oluşturulabilir	Mevcut taslak muhasebe kaydı posted yapılır
İşletme ve serbest meslek	Evrak taslağı oluşur	Muhasebe hareketi oluşturulur ve evrak tamamlanır

completed veya posted, yerel muhasebe durumudur. Vergi Merkezi müşteri API’sinde bunlar bir GİB kabul durumu değildir. Taslak onayında sonucu yanıt ve evrak detayıyla kontrol edin. create_booking=false değerini bütün sonraki akışları kalıcı olarak kapatan bir anahtar olarak kullanmayın.

Kapalı veya kilitli döneme kayıt ekleme ve bazı güncellemeler 422 ile reddedilir. Taslak veya pending evrak PATCH ile güncellenebilir; tamamlanmış evrak aynı yolla değiştirilemez. Güncelleme muhasebe taslağına da yansıyabildiğinden tutar ve vergi alanlarını birlikte kontrol edin.

Vergi tutarları için amount, matrah ve kdv_amount değerlerini tutarlı iletin. Örnekte 100,00 TL matrah ve 20,00 TL KDV, 120,00 TL toplam eder. İstemcide ondalık para hesabı kullanın, satır ve genel toplamları kontrol edin. Uygulanacak oranı veya istisnayı yazılım tahmin etmemelidir.

Evrak silme iki aşamalıdır: propose-delete özet ve confirm_phrase döndürür; confirm-delete aynı ifadeyle çağrılır. Silme, ilişkili muhasebe kayıtlarını da etkileyebilir. Yerel evrakı silmek resmî faturayı iptal etmez veya ticari faturaya ret göndermez.

Turkcell bağlantısı, şirket arama ve resmî belgeler

Vergi Merkezi Bearer tokenınızla firma arayın, belge oluşturun, gönderin ve özgün dosyaları alın. Turkcell anahtarı sunucuda kalır.

Kılavuzdaki 93 sağlayıcı işlemi sabit bir katalogla bağlandı. Adresler kullanıcı isteğinden alınmaz. e Fatura, e Arşiv, gelen ticari yanıt, statik listeler, e Serbest Meslek Makbuzu, e Müstahsil Makbuzu, e Adisyon ve ilgili Excel işlemleri kapsanır. Hesabınızda açık olmayan bir hizmet için sağlayıcı yetki hatası alınabilir. e İrsaliye ve e Defter ayrı servis sözleşmeleridir; bu fatura kılavuzunun kapsamı değildir.

Adım	İşlem
1	GET /agent/einvoice/capabilities?company_id=123 ile bağlantıyı ve kontörü kontrol edin.
2	Firma ayarlarında doğru Turkcell anahtarı, ortam ve gönderen vergi numarası tanımlanmalıdır. Anahtarı istemciye dağıtmayın.
3	POST /agent/einvoice/connection/verify ile firmanıza ait mevcut bir belgenin UUID bilgisini doğrulayın. Anahtar değiştiğinde doğrulama yenilenir. Yeni hesabın henüz belgesi yoksa firma bağlantısı için platform desteğiyle ilerleyin.
4	Şirket aramasından resmî unvanı, vergi numarasını ve uygun alıcı etiketini seçin.
5	status 0 ile taslak oluşturun. Aynı UUID üzerinden PDF ve UBL indirip alıcı, satır ve toplamları kontrol edin.
6	Gönderim isteğinde status 20, confirm_send true ve sabit idempotency_key kullanın. Sonraki durumu ayrıca sorgulayın.

Mevcut belgeyle firma bağlantısını doğrulama

POST /agent/einvoice/connection/verify
{"company_id":123,"family":"outboxinvoice","proof_document_id":"YOUR_PROVIDER_UUID"}

Bu doğrulama yeni fatura oluşturmaz. Mevcut belgenin UBL içindeki firma kimliğini kontrol eder. Yanlış firmaya ait anahtar veya belge kullanımı reddedilir. Her müşterinin kendi firmasına bağlı anahtarı gerekir; bir anahtarı bütün müşteriler için ortak kullanmayın.

Şirket arama

GET /agent/einvoice/recipients?company_id=123&q=Ornek&limit=20

Alıcı sonucu, temsili

{"success":true,"data":{"items":[{"tax_id":"EXAMPLE_TAX_ID","title":"Örnek Firma","aliases":["urn:mail:example@example.com"],"requires_alias_selection":false}],"count":1,"synced_at":"2026-10-30T00:00:00+00:00"}}

Arama resmî unvan veya tam VKN ve TCKN ile çalışır. Türkçe harf ve büyük küçük harf farklılıkları normalleştirilir. Marka adı resmî unvanda bulunmuyorsa eşleşmeyebilir. API sonuçları veri olarak döndürür; adayları kullanıcıya gösterme ve doğru şirketi seçtirme arayüzün veya ajanın görevidir. Birden fazla alıcı etiketi varsa ilgili posta kutusunu açıkça seçin. Arama cari oluşturmaz ve fatura göndermez.

GİB alıcı listesi yalnızca kayıtlı e Fatura alıcılarını kapsar. Adres ve vergi dairesi bilgilerini içermez. Sonuç bulunmaması her işletme için kesin yokluk kararı değildir. synced_at ve is_stale alanlarını dikkate alın. Liste günlük ve atomik olarak yenilenir; yenileme başarısız olursa önceki geçerli indeks korunur.

Ortak alan	Kullanım
company_id	Her istekte yetkili firma kimliği.
parameters	Sağlayıcı yolundaki id, invoiceid, reportDate ve isStandartXslt gibi değerler.
query	Sağlayıcı sorgu filtreleri. Tanımsız alanlar reddedilir.
payload	Sağlayıcının özgün JSON gövdesi. Ek alanlar, istisna ve özel senaryolar korunur; hukuki anlamları müşteri uygulaması tarafından doğru belirlenmelidir.
idempotency_key	37 yazma işleminde zorunlu. Başlıktaki Idempotency-Key alternatif olabilir.
confirm_send	status 20 gönderiminde JSON true. Varsayılan false.
ubl_base64	Multipart UBL işlemlerinde ham XML dosyasının Base64 değeri. Sunucu invoiceFile olarak yükler. Diğer UBL işlemleri sağlayıcı voucherZip, producerReceiptZip veya eadisyonZip gövdesini kullanır.

e Fatura taslağı, temsili

POST /agent/einvoice/operations/invoice_create
{
  "company_id":123,"idempotency_key":"invoice_example_001",
  "payload":{
    "recordType":1,"status":0,"useManualInvoiceId":false,
    "addressBook":{
      "name":"RECIPIENT_LEGAL_NAME","identificationNumber":"RECIPIENT_TAX_ID",
      "alias":"RECIPIENT_ALIAS","receiverCountry":"Türkiye",
      "receiverCity":"RECIPIENT_CITY","receiverDistrict":"RECIPIENT_DISTRICT",
      "receiverStreet":"RECIPIENT_ADDRESS","receiverTaxOffice":"RECIPIENT_TAX_OFFICE"
    },
    "generalInfoModel":{
      "ettn":"YOUR_NEW_UUID","invoiceProfileType":1,"type":1,
      "issueDate":"2026-10-30","currencyCode":"TRY"
    },
    "invoiceLines":[{
      "inventoryCard":"Örnek hizmet","amount":1,"unitCode":"C62",
      "unitPrice":0.83,"lineExtensionAmount":0.83,"vatRate":20,"vatAmount":0.17,
      "taxes":[{"taxName":"KDV","taxTypeCode":"0015","taxRate":20,"taxAmount":0.17}]
    }]
  }
}

Örnek alanları gerçek ve işleme uygun bilgilerle değiştirin. YOUR_NEW_UUID geçerli ve benzersiz UUID olmalıdır. Yeni anahtar veya UUID üretip belirsiz sonucu tekrar göndermeyin. Yanıttaki data.Id, fatura numarası ve kendi iş referansınızı saklayın. Kayıt numarası ve diğer sağlayıcı özel alanları payload içinde korunur.

Aynı taslağı gönderime verme

POST /agent/einvoice/operations/invoice_updatestatus
{"company_id":123,"idempotency_key":"invoice_send_example_001","confirm_send":true,"payload":{"ids":["YOUR_PROVIDER_UUID"],"status":20}}

Gönderim öncesi belgeye erişim ve taslak durumu doğrulanır. Yerel belge kontörü atomik rezerve edilir. Kesin sağlayıcı doğrulama hatasında rezervasyon iade edilir. Sonucu belirsiz istekte otomatik iade veya tekrar yapılmaz; belge ve rezervasyon uzlaştırılır. Turkcell kontörü ile Vergi Merkezi belge kontörü ayrı bakiyelerdir. Bu entegrasyon kontör satın almaz veya kendiliğinden bakiye eklemez.

Durum ve dosya adresleri

GET /agent/einvoice/documents/YOUR_PROVIDER_UUID/status?company_id=123
GET /agent/einvoice/documents/YOUR_PROVIDER_UUID/pdf?company_id=123
GET /agent/einvoice/documents/YOUR_PROVIDER_UUID/ubl?company_id=123

Vergi Merkezi API’sinden PDF indirme

curl --connect-timeout 10 --max-time 75 \
  "$VM_API_BASE/agent/einvoice/documents/$INVOICE_UUID/pdf?company_id=$VM_COMPANY_ID" \
  --header "Authorization: Bearer $VM_API_TOKEN" \
  --output fatura.pdf \
  --write-out "HTTP %{http_code} Content-Type %{content_type}"

family varsayılanı outboxinvoice. Gelen belge inboxinvoice, e Arşiv earchive, serbest meslek voucher, müstahsil producerreceipt ve adisyon eadisyon olarak seçilir. Dosya biçimleri belge türüne bağlıdır; giden e Fatura için ZIP işlemi yoktur ve 404 döner. PDF ve UBL sağlayıcıdan geldiği gibi aktarılır. PDF özeti çağrılar arasında değişebilir. HTML güvenli indirme başlığı taşır; ZIP akışla aktarılır.

Gelen fatura listesi ve ticari yanıt

GET /agent/accounting/inbox?company_id=123&pageIndex=1&pageSize=100

POST /agent/accounting/inbox/YOUR_PROVIDER_UUID/respond
{"company_id":123,"action":"reject","reason":"İŞLEME_UYGUN_GEREKÇE","idempotency_key":"response_example_001"}

Ticari yanıt kabul veya ret içindir. e Fatura için genel bir silme veya tek taraflı iptal işlemi olarak yorumlanmaz. e Arşiv, makbuz ve adisyon iptal işlemleri kendi sağlayıcı uçlarıyla yapılır; sağlayıcının durum ve mevzuat kontrolleri geçerlidir. Yerel evrak silme işlemi resmî iptal değildir.

GET /agent/einvoice/documents yalnızca bu entegrasyon üzerinden oluşturulmuş belge kimliklerini listeler. Önceden sağlayıcıda bulunan bütün belgeleri kapsamaz. Arayüzden oluşturulan belgeler için katalogdaki withnulllocalreferences işlemleri, gelenler için gelen kutusu kullanılır. Sağlayıcı belgesi oluşturmak kendiliğinden yerel muhasebe fişi üretmez; gerekli muhasebe kaydı ayrı ve tekilleştirilmiş akışla yapılmalıdır.

Excel için önce export, sonra history veya export kimliğiyle download kullanılır; ZIP çıktısı kılavuza göre 24 saat saklanır. Liste tarihlerini YYYY-MM-DD HH:mm:ss biçiminde, başlangıç bitişten önce olacak şekilde gönderin; bitiş gelecekte olamaz. Gönderim, GİB zarf durumu ve ticari yanıt ayrı izlenir.

Kapsam	İşlem sayısı
Giden e Fatura	14
Gelen e Fatura ve ticari yanıt	14
e Arşiv	17
Mükellef listesi	1
Referans listeleri	6
e Müstahsil Makbuzu	12
e Serbest Meslek Makbuzu	13
e Adisyon	16

Resmî kaynak: https://developer.turkcellesirket.com/fatura. Yeni sağlayıcı uçları katalog güncellemesiyle eklenir. Test ortamı ayrı firma ayarı ve geçerli test anahtarı gerektirir.

Cari, stok, tahsilat ve raporlar

İşlem sırasını ve firmaya bağlı kimlikleri koruyun.

Cari oluşturmak için POST /agent/lookup/caris kullanılır. type değeri customer, supplier veya both olabilir. Kurumsal alıcıda title ve category:company; kişide first_name ve last_name kullanımı tercih edilir. name eski kullanım biçimi olarak desteklenir. Başarılı yanıt cari_id döndürür. Bir cari kaydı oluşturmak tek başına resmî fatura kesmez.

Stok veya hizmet kartında type değeri product, service veya raw_material olur. tax_rate verilmezse mevcut servis varsayılanı 20, unit verilmezse adet olur. Vergi oranını işleme uygun biçimde açıkça gönderin. Kart oluşturma ile stok giriş ve çıkışı farklı işlemlerdir.

Cari oluşturma, temsili

{"company_id":123,"type":"customer","category":"company","title":"Örnek Firma","currency":"TRY"}

Hizmet kartı oluşturma, temsili

{"company_id":123,"type":"service","name":"Danışmanlık hizmeti","unit":"adet","tax_rate":20,"is_stock_item":false}

Tahsilat record-collection, cariye yapılan ödeme record-payment üzerinden kaydedilir. Bu uçlar muhasebe, banka veya kasa hareket kaydı oluşturur; bankadan gerçek para transferi başlatmaz. payment_method bank veya card ise aynı firmaya ait bank_account_id gerekir. cash kullanılıyorsa ilgili kasayı cash_register_id ile belirtmek kasa hareketinin izlenmesini sağlar.

Tekrar denemesi yönetilen tahsilat kaydı

{
  "company_id":123, "cari_id":456, "amount":120.00,
  "collection_date":"2026-10-30", "payment_method":"bank", "bank_account_id":789,
  "description":"Örnek tahsilat", "idempotency_key":"YOUR_STABLE_COLLECTION_REFERENCE"
}

Kasa hareketinde type in veya out, stok hareketinde type in veya out kullanılır. Pozitif amount ya da quantity gönderilir; yönü negatif tutarla kodlamayın. Banka virmanında kaynak ve hedef hesap aynı firmaya ait olmalıdır. Gerçek para transferi ile yerel muhasebe kaydını ayırın.

Raporlarda company_id ve çoğunlukla year gereklidir. Mizan ve bazı bilanço raporları defter tipine bağlıdır. İşlem referansında month, include_draft, tarih filtresi ve sayfalama desteğini kontrol edin. Taslakları rapora katmak için ilgili uçta include_draft=1 kullanılabilir; bunu tüm raporlar için ortak parametre saymayın.

Sipariş API’si ödeme bağlantısı üretir; ödeme tamamlandı anlamına gelmez. pricing_key bir kontör paketi, pricing_keys bir hizmet listesi içindir. Oluşturulan order_id ve checkout_url saklanır, ödeme sonucu orderStatus ile sorgulanır. Kuruluş başvurusu da sipariş veya başvuru oluşturabilir ve üretim kaydıdır.

Kuruluş başvurusunda webhook_url alanı vardır. Bu özellik tüm muhasebe veya e Fatura işlemleri için ortak bir webhook garantisi değildir. Bu sürüm genel fatura durum webhook’u veya müşteriye açık imza ve yeniden deneme sözleşmesi sunmaz. Uygun aralıklarla durum sorgulaması kullanın.

Hatalar, hız sınırları ve tekrar deneme

HTTP durumunu, uygulama yanıtını ve işlemin gerçek sonucunu birlikte değerlendirin.

HTTP	Anlam	Yapılacak işlem
200	Okuma başarılı veya desteklenen aynı işlemin tekrarı	success ve data alanlarını inceleyin
201	Yeni kayıt oluşturuldu	Dönen kimliği kalıcı saklayın
401	Bearer eksik veya geçersiz	Tokenı ve Bearer yazımını kontrol edin; sürekli login döngüsü kurmayın
403	Rol, firma erişimi veya girişte sözleşme sorunu	Yetki ve doğru firma ilişkisini kontrol edin
404	Kaynak bulunamadı veya erişilebilir değil	Kimlik ve firma eşleşmesini kontrol edin
405	Yanlış HTTP yöntemi	İşlem referansındaki yöntemi kullanın
422	Alan doğrulaması veya iş kuralı	errors veya error içeriğine göre gövdeyi düzeltin
429	Hız sınırı	Varsa Retry-After başlığını izleyin, aralığı artırın
500 ve diğer 5xx	Sunucu veya bağımlılık hatası	Okumayı sınırlı yeniden deneyin; yazmada önce sonucu uzlaştırın
409	Bağlantı, kontör, eşzamanlılık veya anahtar çakışması	error_code alanını inceleyin
424	Sağlayıcı yetkilendirmesi başarısız	Firma anahtarını ve servis yetkisini kontrol edin
502 veya 504	Sağlayıcı yanıtı alınamadı veya geçersiz	result_uncertain true ise yeni gönderim yapmadan belgeyi uzlaştırın

Rota grubu	Bu sürümdeki sınır
POST /auth/login	Dakikada 10 deneme
Müşteri API okuma tabanı	Dakikada 120 istek
Yazma uçları	Dakikada 30 istek, taban sınırına da tabidir
Rapor uçları	60 dakikada 30 istek, taban sınırına da tabidir
POST /mcp	Dakikada 60 istek
Yeni e belge modülü	Taban dakikada 60; işlem uçları dakikada 30
Şirket arama	Dakikada 30
Bağlantı doğrulaması	Dakikada 10

Sınırlar 30 Ekim 2026 etkin rota ve rapor ayarlarından doğrulandı. Uygulama veya ağ katmanında ek sınırlar olabilir. İstekleri farklı uygulamalardan eşzamanlı gönderirken ortak kota tüketimini göz önünde bulundurun. Dağıtık işlerde merkezî kuyruk ve sınırlı eşzamanlılık kullanın.

GET isteklerinde zaman aşımı veya geçici 5xx için sınırlı, giderek artan bekleme uygulanabilir. POST ve PATCH isteklerini bağlantı koptu diye otomatik tekrarlamayın. Sunucu işlemi tamamlamış, yalnızca yanıt ulaşmamış olabilir.

Tahsilat veya ödemede aynı firma ve aynı yön için aynı anahtar mevcut kaydı döndürebilir; ilk kayıtta 201, tekrarda 200 ve idempotent_replay:true görülür. Anahtarı tek bir işleme bağlayın. Değişen tutar için aynı anahtarı yeniden kullanmayın. Mevcut uygulamada eşzamanlı iki isteği tekilleştiren kesin bir yarış koşulu garantisi verilmez; aynı anahtar için istemci kilidi kullanın.

Hata bildirirken istek zamanı, HTTP yöntemi, yol, gizlenmiş firma kimliği, HTTP durumu, güvenli hata metni ve varsa belge kimliği paylaşın. Authorization başlığını, şifreyi, tam müşteri verisini veya anahtarı loglara ve destek mesajlarına koymayın.

Güvenlik ve yayına geçiş

Entegrasyonun doğruluğunu gerçek işlem etkisi ve belge durumu üzerinden doğrulayın.

Tokenı ve sağlayıcı anahtarını sunucu tarafında saklayın. Ön yüz paketine, mobil uygulama kaynaklarına, tarayıcı localStorage alanına, herkese açık depoya veya URL sorgusuna yerleştirmeyin. HTTPS sertifika doğrulamasını açık tutun. Logları maskeleyin ve dosya erişimini firma bazında sınırlandırın.

CORS tarayıcı erişim kuralıdır. Sunucudan sunucuya çalışan cURL veya backend istemcileri CORS’a bağlı değildir. Mevcut varsayılan origin listesi Vergi Merkezi alan adlarını içerir; harici web uygulamasının doğrudan tarayıcı çağrısı engellenebilir. Gerekli origin için destekle yetkilendirmeyi değerlendirin veya kendi backend’inizi kullanın. CORS hatasını token hatasıyla karıştırmayın.

Idempotency-Key başlığı ve PATCH yöntemi ortak API başlıklarına eklendi. JSON idempotency_key de kullanılabilir. Genel preflight yapılandırması ile gerçek API yanıtlarının origin kuralları farklı olabilir; harici tarayıcı erişimini ayrı doğrulayın. Önerilen kullanım sunucu tarafı entegrasyondur.

Hesap, sözleşme ve firma erişimini doğrulayın.
Token yenilemesinin bağlı uygulamaları nasıl etkilediğini kaydedin.
Önce companies gibi okuma uçlarını, sonra hatalı isteklerin 401, 403 ve 422 sonuçlarını doğrulayın.
Muhasebe yazma testlerini onaylanmış ayrı firma ve veriyle yürütün. Üretimdeki taslak da kalıcı kayıt olabilir.
Idempotency desteklenen ve desteklenmeyen işlemler için ayrı tekrar deneme politikası kurun.
Sağlayıcı testinde gönderici ve alıcı, UBL toplamları, alias, belge notu ve UUID eşleşmesini kontrol edin.
PDF dosyasını açın, HTTP ve dosya türünü doğrulayın; yanıt JSON’unu PDF diye sunmayın.
Gönderim, GİB işleme sonucu, alıcı yanıtı ve iptal durumunu ayrı izleyin.
Beklenmeyen sonuçta otomatik ikinci fatura oluşturmayı durdurun ve mevcut kimlikle uzlaştırın.

Bu doküman güncel kod ve belirtilen kontrollü çağrılardan hazırlanmıştır. Bütün muhasebe yazma uçlarının üretim kabul testi yapıldı anlamına gelmez. Ayrıntılı doğrulama kapsamı son bölümde verilir. KDV, istisna, tevkifat, ihracat ve iptal kararları işlem bilgisi ve yetkili muhasebe değerlendirmesiyle belirlenir.

Sık sorulan sorular

57 uygulama, fatura ve entegrasyon sorusuna doğrudan yanıt.

Bu API sadece yapay zekâ ajanları için mi?

Hayır. HTTP ve JSON destekleyen ERP, e ticaret, muhasebe uygulaması veya özel backend aynı müşteri API’sini kullanabilir.

Dokümantasyonu görmek için giriş gerekiyor mu?

Hayır. Rehber, OpenAPI ve Swagger okunabilir. Gerçek API çağrıları ilgili kimlik doğrulamayı gerektirir.

API tokenını nereden alırım?

Müşteri profilinden oluşturabilir veya POST /auth/login ile alabilirsiniz. Her yeni üretim önceki müşteri tokenını geçersiz kılar.

Her istekte login yapmalı mıyım?

Hayır. Tokenı güvenli saklayıp tekrar kullanın. Sürekli login, diğer entegrasyonların tokenını iptal edebilir.

Token bir JWT mi, ne zaman biter?

Opak bir rastgele değerdir. İncelenen müşteri uygulamasında zaman temelli TTL ve refresh token akışı yoktur. Bu, tokenın süresiz garanti edildiği anlamına gelmez; yenileme ve hesap işlemleri erişimi değiştirir.

Bir kullanıcı için birden fazla bağımsız token var mı?

Bu müşteri modelinde tek api_token alanı vardır. Uygulama bazında bağımsız tokenlar ve kapsamlı yönetici tokenları aynı özellik değildir.

Tokenı unuttum, eski değeri okuyabilir miyim?

Sunucuda hash saklanır. Yeni token üretildiğinde eski entegrasyonları yeni değerle güncelleyin. Profilde e postayla gönderme de token yenileyebilir.

401 alıyorum, neyi kontrol edeyim?

Authorization başlığını, Bearer yazımını, boşlukları, doğru hesabın tokenını ve yakın zamanda başka bir girişin tokenı yenileyip yenilemediğini kontrol edin.

403 ne anlama geliyor?

Müşteri rolü, firmaya erişim veya girişte gerekli sözleşme onayı eksik olabilir. Hata metnini ve company_id değerini kontrol edin.

company_id nereden bulunur?

GET /agent/companies yanıtındaki id alanıdır. Örnek kimliği veya portalda görünen başka bir kayıt numarasını kullanmayın.

Bir token bütün firmalara erişir mi?

Yalnızca kullanıcının yetkili olduğu firmalara erişir. Sağlayıcı anahtarlarının firma yetkileri ayrıca doğrulanmalıdır.

Vergi Merkezi tokenı Turkcell’de de geçerli mi?

Doğrudan Turkcell servisinde geçerli değildir. Yeni Vergi Merkezi e belge API’sinde kendi Bearer tokenınızı kullanırsınız; ilgili firma Turkcell anahtarını sunucu seçer.

record-invoice resmî fatura keser mi?

Mevcut müşteri API’sinde muhasebe evrakı ve gerekirse fiş oluşturur. GİB’e resmî gönderim yapmaz.

confirm-draft faturayı GİB’e gönderir mi?

Yerel muhasebe taslağını kesinleştirir. Resmî gönderim için yeni e belge işlem kataloğu veya ayrıntılı formalize akışı kullanılır.

Taslak oluşturmak zararsız bir deneme mi?

Üretimde kalıcı evrak ve defter tipine bağlı taslak muhasebe kaydı oluşabilir. Ayrı ve onaylanmış test verisi kullanın.

Resmî faturayı nasıl göndereceğim?

Doğrulanmış firma bağlantısıyla yeni e belge işlem kataloğundan taslak oluşturun, PDF ve UBL’yi kontrol edin, ardından aynı UUID’yi status 20 ile gönderin. confirm_send true ve idempotency_key gerekir.

Müşteri API’sinden PDF indirme adresi nedir?

GET /agent/einvoice/documents/{uuid}/pdf?company_id=... . Gerekirse family ile belge türünü belirtin. Vergi Merkezi Bearer tokenı kullanılır; Turkcell anahtarı istemciye verilmez.

Evrak kaydında application/pdf yazıyor ama dosya yok, neden?

Dosyasız muhasebe evrakı kaydı bu MIME bilgisini taşıyabilir. Bu alan gerçek bir PDF dosyasının üretildiğini kanıtlamaz.

PDF’i kendim yeniden üretip gönderebilir miyim?

Resmî dosya ihtiyacında sağlayıcının özgün PDF’ini alın. Görüntüyü yeniden üretmek resmî belge durumunu doğrulamaz.

HTTP 200 faturanın alıcı tarafından kabul edildiği anlamına gelir mi?

Hayır. Taşıma başarısı, sağlayıcı belge durumu, zarf sonucu ve alıcının ticari yanıtı ayrı sinyallerdir.

İptal veya ret işlemini bu API’den yapabilir miyim?

Gelen ticari faturaya kabul ve ret bağlıdır. e Arşiv, makbuz ve adisyon kendi iptal işlemlerini kullanır. e Fatura için genel bir tek taraflı iptal uç noktası sunulmaz.

Gelen faturaları neden göremiyorum?

Firma bağlantısını, bağlantı doğrulamasını, tarih aralığını, isNew filtresini ve sayfalama bilgilerini kontrol edin. Gelen kutusu Turkcell’e bağlıdır.

VKN sorgusu hangi bilgileri getirir?

Bu sürümde VKN sorgusu GİB alıcı indeksine bağlıdır. company_id gerekir. Unvan ve alıcı etiketleri döner; adres ve vergi dairesi bilgisi bu kaynakta yoktur.

Aynı faturayı iki kez göndermemek için ne yapmalıyım?

Yerel kayıt kimliğini, iş referansını ve sağlayıcı UUID’sini saklayın. Zaman aşımında yeni fatura oluşturmadan mevcut durumu sorgulayın. Genel idempotency garantisi varsaymayın.

Idempotency-Key her uçta çalışıyor mu?

Yeni Turkcell kataloğundaki bütün yazma işlemlerinde zorunludur. Eski muhasebe API’sinde tahsilat ve ödeme desteği ayrıdır; bütün eski yazma uçları için genel garanti yoktur.

Aynı idempotency anahtarıyla farklı tutar gönderebilir miyim?

Hayır. Yeni Turkcell modülü bunu 409 idempotency_conflict ile reddeder. Eski tahsilat ve ödeme davranışı farklı olabilir; her anahtarı tek bir mantıksal işleme ayırın.

Tutarları virgülle veya para birimiyle yazabilir miyim?

JSON sayı kullanın. Örneğin 120.50. Para birimini desteklenen ayrı alanda iletin; tutara TL veya binlik ayırıcı eklemeyin.

KDV oranını göndermesem ne olur?

Varsayılanlar uca göre değişir. Örneğin stok kartında varsayılan 20 olabilir. Doğru oranı ve tutarı açıkça iletin; istisnayı varsayılan değerden çıkarmayın.

Yurt dışı müşteriye KDV’siz fatura her zaman kesilebilir mi?

Bu rehber böyle bir vergi kararı vermez. Gerçek alıcı, işlem türü ve istisna koşulları ile yetkili muhasebe değerlendirmesi gerekir. Yurt dışı senaryolar bu canlı doğrulamaya dahil değildir.

Türkiye’deki bir alıcıyla yurt dışı senaryosunu doğrulayabilir miyim?

Türkiye alıcı bilgilerini yabancı alıcı gibi kullanmak doğru bir test verisi oluşturmaz. İşleme uygun gerçek yabancı alıcı ve istisna bilgisi gerekir.

Ticari ve temel senaryo aynı mı?

Sağlayıcıda farklı profillerdir. Bu rehberde doğrulanan doğrudan gönderim yurt içi ticari senaryodur. Diğer profiller için sağlayıcının güncel sözleşmesini kontrol edin.

Birden fazla alıcı aliası çıkarsa ne yapmalıyım?

Sağlayıcının doğruladığı alias listesinde ilgili alıcı adresini seçin. Rastgele e posta adresini alias olarak üretmeyin.

lineAmount ile lineExtensionAmount aynı mı?

Kontrollü doğrulamada satır net tutarı için lineExtensionAmount gerekti. Eski örneği kopyalamak yerine güncel şemayı ve oluşan UBL toplamını kontrol edin.

Yerel document_id ile sağlayıcı UUID’si aynı mı?

Hayır. Farklı sistemlerin kimlikleridir. Kendi veri modelinizde aralarındaki ilişkiyi açıkça saklayın.

Hizmet kataloğu ile firmamın ürün kartları aynı mı?

GET /agent/products Vergi Merkezi hizmet ve kontör kataloğudur. Firmanın stok ve hizmet kartları /agent/lookup/items altında bulunur.

Tahsilat API’si bankadan para çeker mi?

İncelenen uç muhasebe ve hareket kaydı oluşturur. Gerçek para çekme veya banka transferi başlatan bir ödeme servisi değildir.

429 alırsam uygulamayı durdurmalı mıyım?

Varsa Retry-After süresini izleyin, eşzamanlılığı azaltın ve giderek artan bekleme uygulayın. Yazma isteğinin sonucunu bilmeden yeniden göndermeyin.

Bütün raporları dakikada 30 kez alabilir miyim?

Hayır. İncelenen etkin rapor sınırı 60 dakikada 30 istektir. Okuma taban sınırı da geçerlidir.

CORS hatası neden sadece tarayıcıda oluyor?

CORS tarayıcı tarafından uygulanır. İzin verilen origin listesi veya yöntem ve başlık kapsamı harici ön yüzü engelleyebilir. Backend entegrasyonunu ve yetkili origin ayarını değerlendirin.

Postman çalışırken web uygulamam neden çalışmıyor?

Bearer başlığı, preflight, origin, Idempotency-Key ve PATCH yöntemini kontrol edin. Postman’ın başarılı olması tarayıcı CORS izni olduğunu göstermez.

Test hesabını veya ortak test şifresini nereden bulurum?

Bu rehber paylaşılan hesap bilgisi sağlamaz. Test ortamına özel kullanıcı ve yetkiyi Vergi Merkezi ile sağlayıcı destek kanallarından edinin.

Resmî belgeyi değiştirip yeniden gönderebilir miyim?

Gönderilmiş belgenin içeriğini yerel taslak gibi değiştirmeyin. Belgenin durumuna ve yetkili iptal veya düzeltme akışına göre ilerleyin.

Fatura durumları için webhook var mı?

Müşteri REST sözleşmesinde genel bir fatura durum webhook’u yoktur. Kuruluş başvurusundaki webhook_url ayrı bir özelliktir.

Sayfalama olmadan bütün kayıtları alabilir miyim?

Yanıttaki total ve last_page bilgilerini izleyin. per_page üst sınırları vardır; ilk yanıt bütün kayıtları içermeyebilir.

Destek için hangi bilgileri göndereyim?

Zaman, yöntem, yol, HTTP durumu, güvenli hata metni ve gerekli belge kimliğini gönderin. Token, şifre, tam vergi kimliği veya müşteri belgesini açık kanalda paylaşmayın.

Bu rehberdeki bütün işlemler canlıda test edildi mi?

Hayır. 93 sağlayıcı işleminin istek eşlemesi ve 37 yazma işleminin gövde akışı ayrı test ortamında sahte sağlayıcıyla kontrol edildi. Gerçek yeni fatura, iptal veya ret işlemi bu entegrasyon yayını için yapılmadı. Önceki iki yurt içi gönderim ve doğrudan PDF doğrulaması kendi kapsamıyla sınırlıdır.

Şirket adı yazınca API bana soru sorar mı?

API eşleşen şirketleri veri olarak döndürür. Şu şirket mi sorusunu arayüz veya ajan sorar. Vergi numarası ve alıcı etiketi seçilmeden otomatik gönderim yapılmamalıdır.

Şirket araması cari kartı oluşturur mu?

Hayır. Arama ve alıcı seçimi veri okur. Cari kartı oluşturmak ayrı bir muhasebe işlemidir; doğrudan sağlayıcı gövdesi için zorunlu değildir.

Marka adıyla neden şirketi bulamıyorum?

Mükellef kaynağı resmî unvanı içerir. Marka veya internet sitesi adı unvanda yer almayabilir. Resmî unvanı ya da tam vergi numarasını kullanın.

Bağlantı doğrulaması neden gerekiyor?

Yanlış firmaya ait sağlayıcı anahtarının kullanılmasını engellemek için mevcut bir belgenin UBL içindeki firma kimliği kontrol edilir. Anahtar değiştiğinde doğrulama yenilenir.

Turkcell anahtarımı müşteriye vermem gerekir mi?

Hayır. Anahtar platformda firma bazında şifreli saklanır. Geliştirici Vergi Merkezi tokenı ve company_id ile çalışır.

Bir işlem kataloğunda var ama sağlayıcı reddediyor, neden?

Katalog işlemin bağlandığını gösterir. Hesabınıza ait servis lisansı, belge durumu, zorunlu alanlar ve sağlayıcı iş kuralları ayrıca geçerlidir. provider_http_status ve details alanlarını inceleyin.

Turkcell kontörüm var, neden insufficient_credits alıyorum?

Turkcell ve Vergi Merkezi belge bakiyeleri ayrıdır. Mevcut platform kontör tanımı gerekir; bu entegrasyon bakiye üretmez ve satın alma yapmaz.

result_uncertain true aldığımda ne yapmalıyım?

Aynı istek otomatik tekrar edilmez. Sakladığınız UUID ve iş referansıyla belge durumunu doğrulayın. Yeni anahtar ve yeni UUID ile kör tekrar yapmayın; rezervasyonu belgeyle uzlaştırın.

Büyük UBL XML dosyasını nasıl gönderebilirim?

Multipart işlemlerde ham XML’i Base64 yapıp ubl_base64 alanına koyun; ek form alanları payload içindedir. Diğer UBL işlemleri sağlayıcının ZIP ve Base64 alanını kullanır. Genel istek sınırı 16 MB, ZIP çözme sınırı 12 MB, XML sınırı 16 MB olarak uygulanır.

API’de gördüğüm belge listesi bütün geçmiş faturalarım mı?

Hayır. Yeni documents listesi bu entegrasyonun oluşturduğu belgeleri izler. Arayüz geçmişi ve gelen kutusu ayrı sağlayıcı işlemleridir.

Faturalar ve bütün raporlar tek çağrıda döner mi?

Hayır. Gelen kutusunda pageIndex ve pageSize kullanın; sayfa boyutu en fazla 500’dür. Her sağlayıcı listesinin sayfalama kuralları ayrıdır.

İşlem referansı

143 müşteri REST işlemi. Turkcell kılavuzundaki 93 işlem sabit kataloğa bağlıdır. Hesaba özel servis yetkisi ve her işlemde sağlayıcı iş kuralları geçerlidir.

POST/auth/loginKoddan doğrulandıE-posta ve şifre ile API token al

Müşteri (client) hesabı için yeni Bearer token üretir. Başarılı yanıtta dönen token, profil sayfasından oluşturulan token ile aynı şekilde kullanılır. Her başarılı çağrı önceki api_token değerini geçersiz kılar. Sözleşme onayı zorunluysa ve web üzerinden kabul edilmemişse 403 döner.

Alan	Konum ve gereklilik	Tür ve kurallar
email	JSON, zorunlu	string; email
password	JSON, zorunlu	string

Yanıtlar

200: success, data.token, data.user_id; 401: E-posta veya şifre hatalı; 403: Müşteri değil veya sözleşme onayı eksik; 422: Validasyon hatası; 429: Çok fazla deneme (throttle)

Kimlik: Bearer gerekli değil. Alanların iç içe şemaları ve makineyle okunabilir ayrıntılar OpenAPI dosyasındadır.

GET/agent/companiesKoddan doğrulandıŞirket listesi

Oturum açan kullanıcının şirketleri. Sipariş için company_id kullanılır.

Ek sorgu veya JSON alanı tanımlı değil. Varsa yol kimliğini işlem adresine yerleştirin.

Yanıtlar

200: companies, currency; 401: Bearer token eksik veya geçersiz; 403: Rol veya firma yetkisi yok; 422: Alan doğrulaması veya iş kuralı hatası; 429: Hız sınırı