TAM Tahsilat API Geliştirici Dokümantasyonu (v2.0)

Hoş geldiniz. TAM Tahsilat API servisi, harici ERP, CRM veya özel muhasebe yazılımlarınızdaki verilerin (Cari Kartlar, Açık Faturalar, Hesap Hareketleri) TAM Tahsilat bulut sistemiyle güvenli ve anlık olarak senkronize edilmesini sağlar.

Bu dokümantasyon, sistem entegratörleri ve yazılım geliştiriciler için hazırlanmıştır.

1. Genel Bakış ve Yetkilendirme

API servisimiz RESTful mimarisine dayanır ve veri alışverişi için JSON formatını kullanır. Tüm istekler HTTPS protokolü üzerinden şifreli olarak gerçekleştirilmelidir.

Base URL

Tüm API istekleri için temel adres:

URL https://dashboard.tamtahsilat.com/api

Authentication (Kimlik Doğrulama)

API güvenliği, firmanıza özel üretilen API Anahtarı (API Key) ile sağlanır. Bu anahtar, her isteğin Header (Başlık) kısmında gönderilmelidir.

Header Parametresi	Açıklama	Örnek Değer
Content-Type	Veri tipini belirtir.	application/json
X-API-KEY	Firmanıza özel gizli anahtar.	8058ea68...

Uyarı: API Anahtarınızı asla herkese açık alanlarda (GitHub vb.) paylaşmayınız. Anahtarınızın ifşa olduğunu düşünüyorsanız lütfen bizimle iletişime geçiniz.

2. Servisler (Endpoints)

A. Cari Hesap ve Fatura Aktarımı (Upsert)

Bu servis, borçlu cari kartlarını oluşturmak, güncellemek ve bu carilere ait açık faturaları sisteme aktarmak için kullanılır. Sistem "Upsert" mantığıyla çalışır: Kayıt varsa günceller, yoksa yeni oluşturur.

POST /v1/external/sync/

İstek Gövdesi (Request Body) Parametreleri

debtors dizisi içerisinde aşağıdaki nesneleri kabul eder:

Parametre	Tip	Zorunluluk	Açıklama
name	String	Zorunlu	Cari Unvanı / Müşteri Adı.
phone	String	Zorunlu	Müşteri GSM numarası (SMS gönderimi için).
email	String	Opsiyonel	Müşteri E-posta adresi.
tax_no	String	Zorunlu	Vergi No veya T.C. Kimlik No (Eşleştirme bu alan üzerinden yapılır).
external_id	String	Zorunlu	ERP tarafındaki Cari Kodu (CARI-001 vb.).
address	String	Opsiyonel	Cari açık adresi.
city	String	Opsiyonel	İl bilgisi (Örn: İstanbul).
district	String	Opsiyonel	İlçe bilgisi (Örn: Kadıköy).
tax_office	String	Opsiyonel	Vergi Dairesi adı.
invoice_number	String	Zorunlu	Aktarılan faturanın numarası.
debt_amount	Decimal	Zorunlu	Fatura tutarı (Kalan bakiye).
due_date	Date	Zorunlu	Fatura vade tarihi (YYYY-MM-DD formatında).
currency	String	Opsiyonel	Para birimi kodu (TRY, USD, EUR). Varsayılan: TRY.

Örnek JSON İsteği

POST /v1/external/sync/
Headers:
  Content-Type: application/json
  X-API-KEY: "SİZİN_API_ANAHTARINIZ"

{
  "debtors": [
    {
      "name": "Yılmaz İnşaat Ltd. Şti.",
      "phone": "05321234567",
      "email": "muhasebe@yilmazinsaat.com",
      "tax_no": "1234567890",
      "external_id": "CARI-101",
      "address": "Organize Sanayi Bölgesi 1. Cad No:5",
      "city": "Ankara",
      "district": "Yenimahalle",
      "tax_office": "Ostim VD",
      "invoice_number": "FTR-2026-001",
      "debt_amount": "15000.50",
      "due_date": "2026-03-01",
      "currency": "TRY"
    },
    {
      "name": "Global Lojistik A.Ş.",
      "phone": "05559876543",
      "tax_no": "9876543210",
      "external_id": "CARI-102",
      "invoice_number": "EXP-2026-005",
      "debt_amount": "2500.00",
      "due_date": "2026-03-15",
      "currency": "USD"
    }
  ]
}

B. Hesap Ekstresi / Hareket Aktarımı

Bu servis, carilerin geçmiş hesap hareketlerini (Ödemeler, İadeler, Virmanlar, Dekontlar) sisteme aktarmak için kullanılır. Müşteri panelinde "Hesap Ekstresi" sekmesinde görüntülenir.

POST /sync-transactions/

İstek Gövdesi (Request Body) Parametreleri

transactions dizisi içerisinde aşağıdaki nesneleri kabul eder:

Parametre	Tip	Zorunluluk	Açıklama
debtor_tax_no	String	Zorunlu	Hareketin ait olduğu carinin Vergi Numarası.
external_id	String	Zorunlu	ERP tarafındaki hareketin benzersiz ID'si (GUID vb.).
type	String	Zorunlu	Hareket Tipi. Kabul edilen değerler: INVOICE (Fatura), PAYMENT (Ödeme), REFUND (İade), OTHER (Diğer).
amount	Decimal	Zorunlu	İşlem tutarı.
date	Date	Zorunlu	İşlem tarihi (YYYY-MM-DD).
description	String	Opsiyonel	İşlem açıklaması (Örn: Havale ile ödeme).
reference_no	String	Opsiyonel	Evrak veya Dekont numarası.
currency	String	Opsiyonel	Para birimi (TRY, USD, EUR).

Örnek JSON İsteği

POST /sync-transactions/
Headers:
  Content-Type: application/json
  X-API-KEY: "SİZİN_API_ANAHTARINIZ"

{
  "transactions": [
    {
      "debtor_tax_no": "1234567890",
      "external_id": "TRX-9991",
      "type": "PAYMENT",
      "date": "2026-02-10",
      "amount": "5000.00",
      "description": "Şubat ayı kısmi ödeme",
      "reference_no": "DEK-0054",
      "currency": "TRY"
    },
    {
      "debtor_tax_no": "1234567890",
      "external_id": "TRX-9992",
      "type": "REFUND",
      "date": "2026-02-11",
      "amount": "1250.00",
      "description": "İade Faturası",
      "reference_no": "IADE-001",
      "currency": "TRY"
    }
  ]
}

3. Yanıt Kodları ve Hata Yönetimi

API, her istek sonucunda standart HTTP durum kodları ve JSON formatında bir yanıt döner.

HTTP Kodu	Durum	Açıklama
200	OK	İstek başarıyla işlendi. Yanıt gövdesinde işlem detayları bulunur.
400	Bad Request	JSON formatı bozuk veya zorunlu alanlar eksik.
401	Unauthorized	API Anahtarı eksik veya geçersiz.
403	Forbidden	IP kısıtlaması veya yetki dışı işlem.
429	Too Many Requests	Limit Aşımı (Günlük işlem limitiniz doldu).
500	Server Error	Sunucu Hatası. Lütfen destek ekibiyle iletişime geçin.

Başarılı Yanıt Örneği (200 OK)

{
    "success": true,
    "created_debtors": 5,
    "updated_debtors": 12,
    "processed_invoices": 17,
    "errors": []
}

Hatalı Yanıt Örneği (400 Bad Request)

{
    "success": false,
    "error": "Zorunlu alan eksik: 'tax_no' alanı boş olamaz."
}

4. Destek ve İletişim

Entegrasyon süreciyle ilgili teknik destek almak için yazılım ekibimizle iletişime geçebilirsiniz.

E-Posta: destek@tamtahsilat.com

Telefon: 0850 840 29 12

Çalışma Saatleri: Hafta içi 09:00 - 17:30