Mali Müşavirlik ve Muhasebe Süreçleri İçin
Yapay Zeka Uyumlu REST API

1. API taban adresi (Base URL)

Tüm istekler bu adrese yapılır. Ortamınıza göre değiştirin.

https://dijital.vergimerkezi.com.tr/api/v1

2. Kimlik doğrulama (Authentication)

Token müşteri hesabınıza aittir; şirket başına ayrı token yoktur. İki yol: (A) Müşteri panelinde Profil — «Yeni token oluştur». (B) Programatik: POST https://dijital.vergimerkezi.com.tr/api/v1/auth/login ile e-posta ve şifre gönderin; yanıtta data.token döner. Her başarılı giriş yeni token üretir ve önceki tokenı geçersiz kılar. Her istekte Authorization: Bearer <token> header'ı gönderin.

Authorization: Bearer YOUR_API_TOKEN

3. Uç noktalar özeti

4. Kod örneği: Şirket listesi (cURL)

Önce Bearer token müşteri kimliğini doğrular; yanıtta bu hesaba bağlı şirketler döner. Sipariş, muhasebe ve rapor isteklerinde işlemin yapılacağı şirket için company_id olarak bu listedeki id kullanılır. Başarılı gövde: success, data (ör. data.companies).

curl -s -X GET "https://dijital.vergimerkezi.com.tr/api/v1/agent/companies" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

5. Kod örneği: Faturayı muhasebeye kaydet (cURL)

Asistan «bu faturayı kaydet» dediğinde gönderilecek örnek. company_id GET companies ile alınır.

Not: Bu uç nokta evrakı doğrudan kaydeder; kullanıcı onayı yoktur. Kullanıcının onaylamasını istiyorsanız record-invoice-draft + confirm-draft akışını tercih edin.

curl -s -X POST "https://dijital.vergimerkezi.com.tr/api/v1/agent/accounting/record-invoice" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": 1,
    "type": "gider",
    "invoice_date": "2026-06-15",
    "amount": 1180.00,
    "supplier_name": "Örnek Tedarikçi A.Ş.",
    "supplier_tax_id": "1234567890",
    "invoice_no": "FTR-2026-001",
    "category": "other",
    "description": "Ofis malzemeleri",
    "matrah": 1000.00,
    "kdv_amount": 180.00,
    "kdv_rate": 18
  }'

6. Kod örneği: Taslak → Onay akışı

Önce taslak oluştur, kullanıcıya özeti göster, onay sonrası confirm-draft ile kesinleştir.

# 1) Taslak oluştur
curl -s -X POST "https://dijital.vergimerkezi.com.tr/api/v1/agent/accounting/record-invoice-draft" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"company_id":1,"type":"gider","invoice_date":"2026-06-15","amount":1180}'

# Yanıt (data içinde): document_id, draft_summary, confirm_url

# 2) Kullanıcı onayladıktan sonra kesinleştir (id = document_id)
curl -s -X POST "https://dijital.vergimerkezi.com.tr/api/v1/agent/accounting/confirm-draft/DOCUMENT_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

İstek gövdesi gerekmez. Taslağı oluşturan kullanıcı ile aynı Bearer token kullanılmalıdır (evrak user_id ile eşleşir).

7. Kod örneği: Evrak silme — iki adımlı onay

Asistan hiçbir zaman tek adımda silme yapamaz. Önce propose-delete ile evrak özetini ve onay ifadesini alır, kullanıcıya gösterir; kullanıcı onaylarsa confirm-delete ile silme işlemi tamamlanır.

# 1) Silme teklifi (evrak özeti + onay ifadesi döner, SİLMEZ)
curl -s -X POST "https://dijital.vergimerkezi.com.tr/api/v1/agent/accounting/propose-delete/DOCUMENT_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Yanıt: data.confirm_phrase = "SİL-DOCUMENT_ID"
# Bu ifadeyi kullanıcıya gösterin ve onayını alın.

# 2) Kullanıcı onayladıktan sonra sil
curl -s -X POST "https://dijital.vergimerkezi.com.tr/api/v1/agent/accounting/confirm-delete/DOCUMENT_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirmation": "SİL-DOCUMENT_ID"}'

Onay ifadesi eşleşmezse ya da dönem kapalıysa 422 döner. Kesinleşmiş (posted) dönem kayıtları silinemez.

8. Kod örneği: Yıllık özet raporu (gelir/gider/net)

«Yıllık kârım ne?» veya «Haziran ayı durumu» gibi sorularda kullanılır. Tüm şirket tipleri için geçerli.

curl -s -X GET "https://dijital.vergimerkezi.com.tr/api/v1/agent/reports/summary?company_id=1&year=2026" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Yanıt data içinde: monthly[] (her ay income, expense, net), total_income, total_expense, total_net.

9. Kod örneği: Python (requests)

import requests

BASE = "https://dijital.vergimerkezi.com.tr/api/v1"
TOKEN = "YOUR_API_TOKEN"
headers = {"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}

# Şirket listesi
r = requests.get(f"{BASE}/agent/companies", headers=headers)
companies = r.json()["data"]["companies"]

# Yıllık özet (ilk şirket)
cid = companies[0]["id"]
r = requests.get(f"{BASE}/agent/reports/summary", params={"company_id": cid, "year": 2026}, headers=headers)
summary = r.json()["data"]