MegApi — Entegrasyon ve API Dökümantasyonu

MegApi, Mega4Net ERP'nin tüm modüllerine (Cari, Stok, Fatura, Sipariş, Kasa, Banka, Muhasebe ve daha fazlası) internet/HTTP üzerinden erişmenizi sağlayan bir REST API'sidir. Kendi programınızı, web sitenizi, mobil uygulamanızı veya bir scripti, ERP verisiyle güvenli biçimde konuşturursunuz.

MegApi ile neler yapabilirsin?

• Cari (müşteri/tedarikçi) kartlarını listele, oku, ekle, güncelle.
• Stok kartlarını ve bakiyelerini sorgula.
• Fatura, sipariş, irsaliye, teklif oluştur ve oku.
• Kasa/banka hareketlerini, muhasebe fişlerini, raporları çek.
• Kısacası: ERP ekranında elle yaptığın işlemleri programatik olarak yap.

Temel ilkeler

Adres (Base URL)

Ön Koşullar — Başlamadan önce elinde ne olmalı?

İlk isteğini atmadan önce aşağıdaki 5 şeye ihtiyacın var. Hepsini bir kenara not et; Hızlı Başlangıç'ta tek tek kullanacağız.

• Base URL — hangi adrese istek atacağın (https://megapi.erp.tr veya http://localhost:8090).
• Firma Kodu — bağlanacağın ERP firmasının kodu (ör. AL24). ERP yöneticinden öğren.
• Çalışma Yılı — hangi mali yıl (ör. 2026).
• Kullanıcı Kodu + Şifre — ERP'deki kullanıcı hesabın (ERP'ye giriş yaptığın bilgiler).
• API Anahtarı (ApiKey) — entegrasyona özel gizli anahtar. Aşağıda nasıl alınacağı anlatılıyor.

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

1. MegaYönet paneline gir

   Tarayıcıda https://megayonet.erp.tr adresine git ve yönetici hesabınla giriş yap.

2. Lisanslar menüsüne geç

   Sol menüden Lisanslar'ı aç. Burada mevcut anahtarları görür, yenisini oluşturabilirsin.

3. Yeni anahtar oluştur

   Yeni Anahtar de, bir ad ver ve oluştur. Ham anahtar değeri yalnızca bir kez gösterilir — hemen kopyalayıp güvenli bir yere kaydet (kaybedersen yenisini üretmen gerekir).

Bir de HTTP aracı lazım

İstek atmak için iki kolay yol var. Birini seç:

Hızlı Başlangıç (5 dakika)

Mantık çok basit ve sadece iki adım: (1) Giriş yap, bir token al. (2) O token ile istediğin veriyi çek. Aşağıda hem curl hem Postman için tek tek anlatılıyor.

1. Giriş yap → Token al (POST /api/v1/auth/login)

   Ön Koşullar'da topladığın 5 bilgiyi gönderiyorsun. Karşılığında bir token (uzun bir metin) alıyorsun. Token, “ben yetkili biriyim” kimlik kartın gibidir.

   curl ile:

   curl -s -X POST https://megapi.erp.tr/api/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{
       "FirmaKodu":     "AL24",
       "CalismaYili":   2026,
       "ApiKey":        "BURAYA_API_ANAHTARINIZ",
       "KullaniciKodu": "admin",
       "Sifre":         "PAROLANIZ"
     }'

   Postman ile:

   1. Sol üstten New → HTTP Request.
   2. Yöntemi POST yap; adres kutusuna https://megapi.erp.tr/api/v1/auth/login yaz.
   3. Body sekmesine geç → raw seç → sağdaki tipi JSON yap.
   4. Yukarıdaki { ... } gövdesini yapıştır, kendi bilgilerinle doldur.
   5. Send de.

   Ne göreceksin (yanıt): Data.Token içinde token gelir.

   { "result": [ {
     "StatusCode": 200,
     "Data": {
       "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
       "TokenType": "Bearer",
       "ExpiresAt": "2026-06-24T12:00:00Z",
       "KullaniciKod": "admin", "FirmCode": "AL24", "CalismaYili": 2026, "IsAdmin": true
     },
     "ErrorMessage": null, "IsError": false
   } ] }

   👉 Bu uzun Token değerini kopyala. Bir sonraki adımda kullanacağız.

2. Token ile veri çek (GET /api/v1/cari)

   Artık her istekte token'ı bir başlık (header) olarak gönderiyorsun: Authorization: Bearer <token>. Aşağıda ilk 20 cari (müşteri/tedarikçi) kaydını çekiyoruz.

   curl ile:

   curl -s "https://megapi.erp.tr/api/v1/cari?pageSize=20" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

   Postman ile:

   1. Yeni bir istek aç; yöntem GET, adres https://megapi.erp.tr/api/v1/cari?pageSize=20.
   2. Authorization sekmesine geç → Type: Bearer Token → kutuya birinci adımda kopyaladığın token'ı yapıştır.
   3. Send de.

   Ne göreceksin: Data.Items içinde cari kayıtların listesi (aşağıda kısaltılmış).

   { "result": [ {
     "StatusCode": 200,
     "Data": { "Items": [ { "Id": 512, "Kod": "M0001", "Ad": "Yılmaz Ticaret A.Ş.", "Aktif": true } ],
               "TotalCount": 721, "Page": 1, "PageSize": 20, "TotalPages": 37 },
     "ErrorMessage": null, "IsError": false
   } ] }

3. Tebrikler 🎉

   İlk isteğini attın! Token'ın 60 dakika geçerli; süresi dolarsa 1. adımı tekrar yap (veya yenile).

   Sırada ne var?

   • Adım-Adım Senaryolar — cari ekle/güncelle, stok sorgula, fatura kes.
   • API Referansı (Scalar) — tüm uçları tarayıcıda dene.
   • Bir hata mı aldın? → Hata & Sorun Giderme.

Kimlik Doğrulama

İki kademe: API anahtarı (entegrasyonu tanır) + kullanıcı girişi (kişiyi tanır) → karşılığında bir JWT token alırsın, sonra her istekte onu gönderirsin.

Giriş uçları

Giriş gövdesi (alanlar)

Token'ı kullanma

Giriş başarılıysa Data.Token gelir. Sonraki tüm isteklerde şu başlığı ekle:

Authorization: Bearer <token>

Varsayılan ömür 60 dakika. Süre dolmadan yenileyebilirsin:

curl -s -X POST https://megapi.erp.tr/api/v1/auth/refresh \
  -H "Authorization: Bearer $TOKEN"

Çıkış (JWT durumsuzdur; sunucu token'ı iptal etmez, istemci siler — kayıt için istek atılabilir):

curl -s -X POST https://megapi.erp.tr/api/v1/auth/logout \
  -H "Authorization: Bearer $TOKEN"

Giriş hata kodları

Yanıt Zarfı — Bir yanıtı nasıl okurum?

Her yanıt aynı “zarf” içinde gelir. Önce result dizisinin ilk elemanına bak, sonra IsError'ı kontrol et, sonra Data'yı oku. Hepsi bu.

{
  "result": [
    { "StatusCode": 200, "Data": { ... }, "ErrorMessage": null, "IsError": false }
  ]
}

Başarılı (kayıt oluşturma)

{ "result": [ { "StatusCode": 200, "Data": { "Id": 1023 }, "ErrorMessage": null, "IsError": false } ] }

Doğrulama hatası (422)

{ "result": [ {
  "StatusCode": 422,
  "Data": [ "CariKodu zorunludur.", "Ad en az 2 karakter olmalıdır." ],
  "ErrorMessage": "CariKodu zorunludur. | Ad en az 2 karakter olmalıdır.",
  "IsError": true
} ] }

Yetki/oturum hatası (401)

{ "result": [ { "StatusCode": 401, "Data": null, "ErrorMessage": "Geçersiz ApiKey.", "IsError": true } ] }

Sayfalama & Filtreleme

Liste uçları büyük veriyi sayfa sayfa döner. Filtreler ise adresin sonuna ?anahtar=değer şeklinde eklenir.

GET /api/v1/cari?arama=mehmet&aktif=true&page=1&pageSize=50&sortKey=Kod&sortDescending=false

Yanıttaki Data sayfalı yapıdır:

{ "result": [ { "StatusCode": 200, "Data": {
  "Items": [ /* kayıtlar */ ], "TotalCount": 721, "Page": 1, "PageSize": 50, "TotalPages": 15
}, "IsError": false } ] }

Hata Kodları & Sorun Giderme

Bir şey ters gittiğinde IsError: true olur ve bir StatusCode + ErrorMessage gelir. Aşağıdaki tablo en sık karşılaşılanları ve nasıl çözeceğini gösterir.

HTTP kodları

Belirti → Neden → Çözüm

Adım-Adım Senaryolar

Gerçek işler. Hepsinde token'ın hazır olduğunu varsayıyoruz ($TOKEN). Tam alan listeleri için her zaman API Referansı'na bakabilirsin.

1) Cari (müşteri/tedarikçi) listele

Temel URL: /api/v1/cari · Tablo: CarAna

curl -s "https://megapi.erp.tr/api/v1/cari?arama=Yilmaz&kartTipi=3&aktif=true&page=1&pageSize=20" \
  -H "Authorization: Bearer $TOKEN"

{ "result": [{ "StatusCode": 200, "Data": {
  "Items": [ { "Id": 512, "Kod": "M0001", "Ad": "Yılmaz Ticaret A.Ş.",
               "KartTipi": "3", "VerNo": "1234567890", "Sehir": "İstanbul", "Aktif": true } ],
  "TotalCount": 1, "Page": 1, "PageSize": 20, "TotalPages": 1
}, "IsError": false }] }

2) Tek cari oku (ID ile)

curl -s https://megapi.erp.tr/api/v1/cari/512 \
  -H "Authorization: Bearer $TOKEN"

Data, tam kartı (95+ alan) döner — kilit alanlar:

{ "Id": 512, "Kod": "M0001", "Ad": "Yılmaz Ticaret A.Ş.", "KartTipi": "3",
  "HesapTipi": "120", "VerNo": "1234567890", "VerDar": "Fatih",
  "Adres": "Atatürk Cad. No:15", "Sehir": "İstanbul", "Telefon": "02121234567",
  "EpostaAdr": "info@yilmaztic.com", "DvzCinsi": "TL", "Aktif": true }

3) Yeni cari ekle

curl -s -X POST https://megapi.erp.tr/api/v1/cari \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Kod":       "M0099",
    "Ad":        "Test Müşteri Ltd. Şti.",
    "KartTipi":  "3",
    "HesapTipi": "120",
    "VerNo":     "9876543210",
    "VerDar":    "Kadıköy",
    "Adres":     "Bağdat Cad. No:45",
    "Sehir":     "İstanbul",
    "Telefon":   "02169876543",
    "DvzCinsi":  "TL",
    "Aktif":     true
  }'

Yanıt — yeni kaydın Id'si:

{ "result": [{ "StatusCode": 200, "Data": { "Id": 1023 }, "ErrorMessage": null, "IsError": false }] }

4) Cari güncelle

curl -s -X PUT https://megapi.erp.tr/api/v1/cari/1023 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "Kod": "M0099", "Ad": "Test Müşteri Ltd. Şti. (Güncel)", "KartTipi": "3", "DvzCinsi": "TL", "Aktif": true }'

5) Cari pasifleştir (DELETE)

Cari'de DELETE kaydı silmez, pasifleştirir (Aktif = false):

curl -s -X DELETE https://megapi.erp.tr/api/v1/cari/1023 \
  -H "Authorization: Bearer $TOKEN"

6) Stok sorgula

Temel URL: /api/v1/stok · Tablo: StkAna. Aynı CRUD deseni geçerlidir.

curl -s "https://megapi.erp.tr/api/v1/stok?arama=kalem&page=1&pageSize=20" \
  -H "Authorization: Bearer $TOKEN"

7) Fatura oluştur (başlık + kalemler)

Temel URL: /api/v1/fatura · Tablolar: FatHarBas (başlık) + FatHarDet (kalemler). Fatura, bir başlık ve bir veya daha fazla kalemden oluşur.

POST /api/v1/fatura
{
  "Bas":      { "CariKod": "M0001", "Tarih": "2026-06-24", "FaturaTipi": "...", "DvzCinsi": "TL" },
  "Kalemler": [ { "StokKod": "STK001", "Miktar": 10, "BirimFiyat": 25.50 } ]
}

8) Genel geçit ile ham kayıt (gelişmiş)

Tip-güvenli uç yoksa, tablo+alanla doğrudan kayıt:

POST /Api/APIMethods/KayitKaydetV2
{ "TableName": "CarAna", "Operation": "Save",
  "Fields": { "Kod": "M001", "Ad": "Mehmet Demir", "KartTipi": "3" } }

Detay → Genel Tablo Geçidi.

Araçlar — Denemenin en kolay yolları

Kod yazmadan, tarayıcıda tüm API'yi gezip “Try” ile deneyebilirsin.

Scalar — Etkileşimli API Referansı

/scalar/v1 → tüm uçlar, parametreler, gövde şemaları ve canlı deneme. Kullanımı:

1. Sağ üstte Authorize'a tıkla, token'ını yapıştır (önce giriş yapıp token al).
2. Soldan bir uç seç (ör. GET /api/v1/cari).
3. Test Request / Send ile gerçek yanıtı gör.

Swagger UI

/swagger → aynı OpenAPI dokümanının klasik Swagger arayüzü. Authorize → token → Try it out.

Markdown Kılavuz

/docs/kilavuz → kurulum + kullanım kılavuzu (tek sayfa, yazdırmaya uygun).

Postman ipucu — token'ı bir kez yaz

1. Sağ üstten bir Environment oluştur; içine base_url ve token değişkenleri ekle.
2. İsteklerde adresi {{base_url}}/api/v1/cari, Authorization'da Bearer Token'ı {{token}} yap.
3. Giriş yanıtından token'ı kopyalayıp token değişkenine yapıştır — artık her istekte otomatik kullanılır.

API Metotları & Endpoint'ler

Her domain hem modern REST (/api/v1/<domain>) hem RPC alias (/Api/APIMethods/<Domain>ListesiV2 · KaydetV2 · GuncelleV2) sunar.

Tipik CRUD deseni (örnek: Cari)

Kapsanan domainler (55+)

Genel Tablo Geçidi

Genel-amaçlı tablo erişiminin güvenli yolu. Tip-güvenli domain ucu yoksa veya ham tablo erişimi gerekiyorsa kullan.

POST /Api/APIMethods/KayitKaydetV2
{ "TableName": "CarAna", "Operation": "Save",
  "Fields": { "Kod": "M001", "Ad": "Mehmet Demir", "KartTipi": "3" } }

Tablo Alan Yapıları

Domain modelleri Mega4Net SQL tablolarını birebir yansıtır.

Bir kaydın alanlarını nasıl keşfederim?

• API Referansı'ndaki ilgili uç şemasına (request/response model) bak — en kesin yol.
• Ya da Genel Geçit ile geçersiz bir kolon gönder; 422 hatası geçerli alan adlarını keşfetmene yardımcı olur.

Sözlük — Terimler

Geçen terimleri bilmiyorsan buraya bak. Hepsi sade dille.

API

İki programın birbiriyle konuşmasını sağlayan arayüz. Burada: ERP verisine HTTP ile erişim.

REST

API'leri adres (URL) + yöntem (GET/POST…) ile tasarlama yaygın stili.

Endpoint (uç)

İstek attığın tek bir adres, ör. /api/v1/cari.

HTTP yöntemleri

GET oku · POST ekle · PUT güncelle · DELETE sil.

JSON

Veriyi { "anahtar": "değer" } biçiminde taşıyan metin formatı. İstek gövdesi ve yanıtlar JSON'dur.

Header (başlık)

İsteğe eklenen ek bilgi. En önemlisi Authorization (token) ve Content-Type.

Token / JWT

Giriş sonrası aldığın, “yetkiliyim” diyen şifreli metin. 60 dk geçerli.

Bearer

Token'ı gönderme şekli: Authorization: Bearer <token>.

API Anahtarı (ApiKey)

Entegrasyonu tanıyan gizli anahtar. MegaYönet'ten alınır.

Base URL

Tüm adreslerin başı, ör. https://megapi.erp.tr.

Firma Kodu

Bağlanacağın ERP firması. İsteğini o firmanın veritabanına yönlendirir.

Çalışma Yılı

İşlemlerin geçtiği mali yıl, ör. 2026.

Cari

Müşteri/tedarikçi/personel gibi hesap kartı (tablo: CarAna).

Stok

Ürün/malzeme kartı (tablo: StkAna).

Zarf (envelope)

Her yanıtın sarıldığı ortak yapı: result[] + StatusCode/Data/ErrorMessage/IsError.

CRUD

Create/Read/Update/Delete — ekle/oku/güncelle/sil.

Sayfalama

Büyük listeyi page + pageSize ile parça parça alma.

Rate limit (hız sınırı)

Belirli sürede izin verilen istek sayısı (~600/dk/IP). Aşarsan 429.

curl

Komut satırından HTTP isteği atan araç.

Postman

İstekleri görsel olarak hazırlayıp gönderen masaüstü uygulaması.

Sürüm Notları

v1.1 — beta+

• 55+ iş domaini; ~390 endpoint. Eklenenler: Stok Seri/Sayım, Parti, Barkod/Etiket, Cari Fiyat, Cari Tah/Ted, Mali Tablo, İthalat/İhracat, Kod Değiştir, e-Belge (e-Fatura/e-Arşiv/e-İrsaliye/e-SMM).
• Uç-bazlı RBAC + DB-tabanlı API anahtarı + yönetim uçları.
• Token yenileme + hız sınırı + CORS.

v1.0 — beta

• RPC-uyumlu yanıt zarfı + API Key/JWT kimlik doğrulama + çok-firmalı bağlam.
• 44 iş domaini (REST + RPC alias); ~300+ endpoint.
• Genel tablo geçidi (şema-doğrulamalı). Swagger UI + Scalar + OpenAPI.

Yasal & Sorumlu Kullanım

MegApi yalnızca yetkili entegrasyonlar tarafından kullanılır.

Gizlilik

API anahtarı ve kullanıcı bilgileri gizli tutulmalıdır. Anahtar paylaşımı ve yetkisiz erişim yasaktır.

Sorumlu kullanım

Genel tablo geçidi ve toplu işlemler iş kurallarını atlayabildiğinden dikkatli kullanılmalı; tüm yazma işlemleri denetim için loglanır.

© CAL.NET — Mega4Net / MegApi · İletişim: apidestek@erp.tr