ERP'nizi sat.net.tr'ye bağlayın
Cari ve talep verilerinizi kendi sisteminizden aktarın, ihale ve sipariş durumlarını geri okuyun. REST ve SOAP arayüzlerinin ikisi de aynı çekirdeği kullanır — hangisini seçerseniz davranış aynıdır.
Bölüm 1
Genel bakış
SatNET entegrasyonu, alıcı firmanın ERP sistemiyle sat.net.tr arasında çift yönlü bir veri akışı kurar.
Entegrasyon iki yönlüdür: ERP'den dışa aktarım (cari ve talep verisi SatNET'e girer) ve geri-okuma(ihalenin güncel durumu, teklif sayısı, kazanan ve sipariş bilgisi ERP'ye döner).
- Cari aktarımı:ERP'deki tedarikçi/cari listeniz SatNET'e aday firma (prospect) olarak aktarılır; platforma davet ve eşleştirme süreçlerinde kullanılır.
- Talep aktarımı:ERP'de açılan satın alma talebi SatNET'te ihaleye dönüşür. Varsayılan davranış taslak oluşturmaktır; alıcı ekip
İhalelerimekranında gözden geçirip yayınlar. - Durum geri-okuma: Gönderdiğiniz taleplerin güncel durumunu (taslak / yayında / kapandı / iptal), teklif sayısını, kazananı ve varsa siparişi periyodik olarak sorgularsınız.
Tek çekirdek, iki protokol
| REST | SOAP | |
|---|---|---|
| Adres | /api/v1/entegrasyon/… | /api/soap/entegrasyon |
| Veri biçimi | JSON (UTF-8) | XML — SOAP 1.1 ve 1.2 |
| Sözleşme | Bu sayfa | GET /api/soap/entegrasyon?wsdl |
| Uygun olduğu durum | Modern ERP, orta katman servisi, betik/entegratör | WSDL üzerinden istemci üreten .NET / Java tabanlı ERP |
Tüm alan adları Türkçedir (Türk ERP ürünleriyle uyum için). Tüm tarihler ISO-8601 biçiminde ve UTC olarak alınır/verilir; para birimi kodu TRY, USD, EUR olabilir.
Bölüm 2
Kimlik doğrulama
Her istek, firmanıza özel bir API anahtarıyla imzalanır. Anahtar hem kimliği hem de hangi firmanın verisine eriştiğinizi belirler.
Anahtar nasıl alınır?
Firma sahibi hesabıyla giriş yapıp Panel → Entegrasyon ekranından, ihtiyaç duyduğunuz yetkilerle kendi anahtarınızı self-servis üretebilir ve iptal edebilirsiniz. Pro (SRM) veya Kurumsal (SCM) aboneliği gerekir. Anahtarın tam değeri yalnızca üretildiği anda bir kez görüntülenir; sistemde yalnız SHA-256 özeti saklanır. Kaybedilen anahtar geri getirilemez, yenisi üretilir. Yardım, ek yetki veya firma onayı için destek@sat.net.tr adresine yazabilirsiniz.
Anahtar biçimi: satnet_live_ ön eki + 64 karakter onaltılık değer.
satnet_live_4bbf4964d4c7a1e2… (toplam 76 karakter)REST tarafında
Standart Authorization: Bearer başlığı kullanılır.
Authorization: Bearer satnet_live_4bbf4964d4c7a1e2…SOAP tarafında
İki yol da geçerlidir; ikisi birden gönderilirse HTTP başlığı önceliklidir.
- Aynı
Authorization: Bearer …HTTP başlığı. - HTTP başlığı ayarlayamayan ERP araçları için SOAP zarfının başlığındaki
<ApiAnahtari>elemanı.
<soapenv:Header>
<ApiAnahtari>satnet_live_4bbf4964d4c7a1e2…</ApiAnahtari>
</soapenv:Header>Anahtarı gizli tutun
Kiracı izolasyonu: Sorgular her zaman anahtarın bağlı olduğu firmayla sınırlıdır. Başka bir firmanın dış referansı veya ihale numarası sorgulansa bile sonuç dönmez; ilgili değer bulunamadi listesine düşer.
Bölüm 3
Yetkiler (scope)
Her anahtara, yalnızca ihtiyaç duyduğu işlemleri kapsayan yetkiler tanımlanır. Yetkisi olmayan bir uca yapılan istek 403 ile reddedilir.
| Yetki | Ne sağlar | Kullanan uçlar | Durum |
|---|---|---|---|
cari:write | Cari (aday firma) içe aktarımı | POST /api/v1/entegrasyon/cariler · CariAktar | Kullanılabilir |
cari:read | Cari sorgulama (VKN/ad → resmi unvan + SatNET üyeliği; iletişim PII'si dönmez) | GET /api/v1/entegrasyon/cariler?vergiNo= | ?ad= | Kullanılabilir (REST) |
talep:write | Talep girişi (ERP talebi → SatNET ihalesi) | POST /api/v1/entegrasyon/talepler · TalepAktar | Kullanılabilir |
durum:read | İhale/sipariş durumu + teklif SAYISI + kazanan (özet) | /api/v1/entegrasyon/talepler/durum · DurumSorgula | Kullanılabilir |
teklif:read | Teklif DETAYI (fiyat/kalem, maskeli) geri-okuma | /api/v1/entegrasyon/talepler/teklifler · TeklifSorgula | Kullanılabilir |
siparis:read | Sipariş DETAYI (kalemler + üretim/sevk olayları) geri-okuma; taraf olduğun siparişler | GET /api/v1/entegrasyon/siparisler · SiparisSorgula | Kullanılabilir |
siparis:write | Sipariş üretim/sevk/teslim olayı yazma (SCM zaman çizelgesi); durum makinesini değiştirmez | POST /api/v1/entegrasyon/siparisler/durum · SiparisDurumBildir | Kullanılabilir |
katalog:write | ERP malzeme kartı kataloğu içe aktarımı | /api/v1/entegrasyon/katalog · KatalogAktar | Kullanılabilir |
katalog:read | Katalog sorgulama (yalnız kendi kartlarınız) | /api/v1/entegrasyon/katalog · KatalogSorgula | Kullanılabilir |
Katalogda tekillik firmaya göredir
disReferans ile eşlenir ve bu referans yalnız kendi firmanız içindetekildir — ERP'nizdeki malzeme numarasını olduğu gibi gönderebilirsiniz, başka bir firmanın aynı numarayı kullanması sizi etkilemez. Tekrar gönderim boş alanları ezmez: göndermediğiniz alan (birim, kategori, aktif) mevcut değeriyle kalır. Bir kartı kullanımdan kaldırmak için aktif: falsegönderin.En az yetki ilkesine uyun: yalnızca talep aktaran bir entegrasyon için talep:write ve durum:read yeterlidir. Farklı sistemler için ayrı anahtarlar isteyin — böylece biri iptal edildiğinde diğerleri etkilenmez.
Bölüm 4
REST uçları
Taban adres: https://sat.net.tr. Tüm istek ve yanıt gövdeleri UTF-8 JSON'dur.
POST https://sat.net.tr/api/v1/entegrasyon/cariler
Authorization: Bearer satnet_live_4bbf4964d4c7…
Content-Type: application/json; charset=utf-84.1 · Cari aktarımı — POST /api/v1/entegrasyon/cariler
Yetki: cari:write. ERP'deki cari listenizi SatNET'e aday firma olarak aktarır. Anahtar alan vergi numarasıdır (VKN 10 hane / TCKN 11 hane; VKN algoritması doğrulanır). Aynı vergi numarası tekrar gönderildiğinde yeni kayıt açılmaz, mevcut kayıt güncellenir ve boş gönderilen alanlar mevcut değerleri silmez. Tek istekte 1–1000 cari gönderilebilir.
{
"cariler": [
{
"vergiNo": "1234567890",
"unvan": "Demir Makine San. Tic. Ltd. Şti.",
"yetkiliAd": "Ayşe",
"yetkiliSoyad": "Demir",
"yetkiliGorev": "Satış Müdürü",
"eposta": "ayse.demir@ornekfirma.com.tr",
"telefon": "0222 000 00 00",
"gsm": "0555 000 00 00",
"adres": "Organize Sanayi Bölgesi 5. Cadde No:12",
"il": "Eskişehir",
"web": "https://ornekfirma.com.tr",
"sektor": "Makine imalat",
"cariKod": "120.01.0042"
}
]
}Yalnızca vergiNo zorunludur; diğer tüm alanlar isteğe bağlıdır.
| Alan | Tip | Açıklama |
|---|---|---|
vergiNo | metin (zorunlu) | VKN (10 hane) veya TCKN (11 hane). Kayıt anahtarıdır. |
unvan | metin | Firma unvanı (en çok 350 karakter). |
yetkiliAd, yetkiliSoyad, yetkiliGorev | metin | İlgili kişi bilgileri. |
eposta, telefon, gsm, web | metin | İletişim bilgileri. |
adres, il, sektor | metin | Adres ve sınıflandırma bilgileri. |
cariKod | metin | ERP tarafındaki cari kodunuz; eşleştirme için saklanır. |
{
"ozet": { "toplam": 2, "eklendi": 1, "guncellendi": 0, "hatali": 1 },
"sonuc": [
{ "vergiNo": "1234567890", "durum": "eklendi" },
{
"vergiNo": "12345",
"durum": "hata",
"mesaj": "Geçersiz vergi numarası (VKN 10 / TCKN 11 hane)"
}
]
}Kayıt bazlı sonuç: eklendi · guncellendi · hata. Bir kaydın hatalı olması diğerlerini engellemez; istek yine 200 döner ve hatalı satırlar sonuc içinde işaretlenir.
4.2 · Talep aktarımı — POST /api/v1/entegrasyon/talepler
Yetki: talep:write. ERP'deki satın alma talebini SatNET ihalesine dönüştürür. Tek istekte 1–200 talep, her talepte 1–200 kalem gönderilebilir.
POST https://sat.net.tr/api/v1/entegrasyon/talepler
{
"talepler": [
{
"baslik": "Rulman ve keçe alımı",
"aciklama": "Bakım stoğu için yıllık ihtiyaç.",
"disReferans": "ERP-2026-000184",
"sonTeklifTarihi": "2026-08-15T17:00:00.000Z",
"paraBirimi": "TRY",
"teslimatAdresi": "Organize Sanayi Bölgesi 5. Cadde No:12 Bursa",
"kategoriIds": [12],
"yayinla": false,
"kalemler": [
{
"kalemAdi": "6204 2RS Rulman",
"miktar": 250,
"birim": "adet",
"hedefBirimFiyat": 12.50
},
{
"kalemAdi": "Yağ keçesi 25x40x7",
"miktar": 40,
"birim": "adet",
"aciklama": "NBR, çift dudaklı"
}
]
}
]
}| Alan | Tip | Açıklama |
|---|---|---|
baslik | metin (zorunlu) | İhale başlığı. |
kalemler | dizi (zorunlu, 1–200) | Her kalemde kalemAdi ve miktar zorunlu; birim (adet/kg/m…), aciklama, hedefBirimFiyat isteğe bağlı. Tanınmayan birim varsayılana (adet) düşer. |
disReferans | metin (en çok 60) | ERP talep numaranız. İdempotentlik anahtarıdır — bkz. Bölüm 7. |
sonTeklifTarihi | ISO-8601 tarih | Verilmezse bugünden 7 gün sonrası atanır. |
aciklama | metin | İhale açıklaması / şartname özeti. |
paraBirimi | metin | TRY / USD / EUR. |
teslimatAdresi | metin | Verilmezse firma kayıtlı adresi kullanılır. |
kategoriIds | sayı dizisi | SatNET kategori numaraları. Yayınlama için gereklidir. |
yayinla | mantıksal | Varsayılan false → taslak. true ise otomatik yayınlanmaya çalışılır. |
ihaleTuru, alimTuru, gorunurluk | metin | kapali|eksiltme · endirekt|direkt · acik|davetli. Direkt ve davetli Pro plan gerektirir; verilmezse kapalı/endirekt/açık varsayılır. |
sertifikalar, davetliVknler | metin dizisi | sertifikalar: aranan sertifika kodları (yalnız direkt). davetliVknler: davet edilecek tedarikçi VKN'leri (yalnız davetli; eşleşmeyenler yanıt mesaj'ında uyarı olur). |
otoUzatma, otoUzatmaDk, minDusus, hedefFiyatGoster | mantıksal / sayı | Açık eksiltme ayarları (yalnız eksiltmede etkili) + hedef fiyat görünürlüğü. |
kalem: terminTarihi, muadilKabul | ISO tarih / mantıksal | Kalem bazında termin tarihi ve muadil (eşdeğer) ürün kabulü. |
{
"ozet": { "toplam": 1, "taslak": 1, "yayinlandi": 0, "mevcut": 0, "hatali": 0 },
"sonuc": [
{ "disReferans": "ERP-2026-000184", "durum": "taslak", "demandId": 331 }
]
}Yanıttaki kalemler[] — teklif korelasyonu
kalemler dizisi döner: sira, kalemAdi ve demandDetailId(SatNET kalem id). Bu id'yi ERP tarafında saklayın — teklif geri-okumada (/talepler/teklifler) gelen kalemler aynı demandDetailId ile döner, böylece teklif kalemlerini kendi talep kaleminize birebir bağlarsınız.Varsayılan davranış: taslak
yayinla gönderilmezse veya false ise ihale taslak olarak oluşur; alıcı ekip İhalelerimekranında gözden geçirip yayınlar. Bu, ERP'den gelen bir kaydın istemeden tedarikçilere açılmasını engelleyen kasıtlı bir güvenliktir.
yayinla: true gönderdiğinizde ihale, yayın koşulları (en az bir kategori ve teslimat adresi) sağlanıyorsa otomatik yayınlanır ve sonuç yayinlandi döner. Koşullar eksikse istek hata vermez: ihale taslak kalır, sonuç taslak ve mesaj alanında nedeni belirtilir.
İdempotentlik: disReferans gönderdiğinizde, aynı referansla gelen ikinci istek yeni ihale açmaz. Mevcut ihale mevcut durumu ve aynı demandId ile döner. Böylece ağ hatası sonrası tekrar gönderim güvenlidir.
{
"ozet": { "toplam": 1, "taslak": 0, "yayinlandi": 0, "mevcut": 1, "hatali": 0 },
"sonuc": [
{ "disReferans": "ERP-2026-000184", "durum": "mevcut", "demandId": 331 }
]
}4.3 · Durum sorgulama — GET|POST /api/v1/entegrasyon/talepler/durum
Yetki: durum:read. Bu uç hem GET hem POST kabul eder; ikisi de aynı sonucu üretir. Uzun listeleri URL uzunluğuna takılmadan göndermek için POST tercih edilir.
GET https://sat.net.tr/api/v1/entegrasyon/talepler/durum
?disReferans=ERP-2026-000184,ERP-2026-000185
Authorization: Bearer satnet_live_4bbf4964d4c7…
# Diğer kullanımlar
GET …/durum?ihaleNo=IHL-2026-0001,IHL-2026-0002
GET …/durum?limit=50 # filtre yoksa en yeni 50 ihaleGET parametreleri virgülle çoklu değer alır ve parametre birden çok kez tekrarlanabilir (?disReferans=A&disReferans=B).
POST https://sat.net.tr/api/v1/entegrasyon/talepler/durum
{
"disReferanslar": [
"ERP-2026-000184",
"ERP-2026-000185",
"ERP-2026-000190"
],
"ihaleNolar": ["IHL-2026-0001"],
"limit": 50
}| Parametre | GET | POST | Açıklama |
|---|---|---|---|
| Dış referanslar | disReferans | disReferanslar | En çok 200 değer; her biri 1–60 karakter. |
| İhale numaraları | ihaleNo | ihaleNolar | En çok 200 değer; her biri 1–20 karakter. |
| Limit | limit | limit | 1–200 (varsayılan 50). Yalnızca filtresiz çağrıda etkilidir; en yeni N ihale döner. |
İki filtre listesinin toplamı 200 kaydı aşamaz — aşarsa 422 dogrulama döner. POST gövdesinde limit sayı olmalıdır (metin değil).
{
"sonuclar": [
{
"disReferans": "ERP-2026-000184",
"ihaleNo": "IHL-2026-0001",
"baslik": "Rulman ve keçe alımı",
"durum": "kapandi",
"sonTeklifTarihi": "2026-08-15T17:00:00.000Z",
"olusturmaTarihi": "2026-07-18T20:53:38.049Z",
"teklifSayisi": 4,
"kalemSayisi": 2,
"kazananVar": true,
"kazananUnvan": "Demir Makine San. Tic. Ltd. Şti.",
"siparis": {
"siparisNo": "PO-2026-0007",
"durum": "Onaylandı",
"durumKodu": "acknowledged",
"olusturmaTarihi": "2026-08-16T09:12:00.000Z"
}
},
{
"disReferans": "ERP-2026-000185",
"ihaleNo": "IHL-2026-0002",
"baslik": "Hidrolik hortum alımı",
"durum": "yayinda",
"sonTeklifTarihi": "2026-09-01T17:00:00.000Z",
"olusturmaTarihi": "2026-07-25T11:04:12.310Z",
"teklifSayisi": 3,
"kalemSayisi": 5,
"kazananVar": false
}
],
"bulunamadi": ["ERP-2026-000190"]
}| Alan | Açıklama |
|---|---|
durum | taslak · yayinda · kapandi · iptal. Son teklif tarihi geçmiş yayındaki ihale kapandi sayılır. |
ihaleNo | SatNET ihale numarası (IHL-YYYY-NNNN). Taslak aşamasında null'dur. |
teklifSayisi, kalemSayisi | Alınan teklif adedi ve ihale kalem adedi. |
kazananVar | Kazanan kesinleşti mi? |
kazananUnvan | Yalnızca kazanan kesinleştiğinde bulunur — aksi hâlde alan yanıtta hiç yer almaz. |
siparis | İhaleye bağlı sipariş oluştuysa: siparisNo, durum (Türkçe etiket), durumKodu, olusturmaTarihi. |
bulunamadi | Eşleşmeyen dış referans ve ihale numaraları. ERP tarafında kendi kayıtlarınızı işaretlemek için kullanın. |
Teklif aşamasında kimlik maskelidir
teklifSayisi görünür. Kazanan kesinleştiğinde (veya sipariş oluştuğunda) kazananUnvanalanı yanıta eklenir. Bu, platformun teklif gizliliği politikasının parçasıdır ve REST ile SOAP'ta aynı şekilde uygulanır.4.4 · Teklif detay sorgulama — GET|POST /api/v1/entegrasyon/talepler/teklifler
Yetki: teklif:read. Kendi ihalelerinize gelen tekliflerin fiyat ve kalem detaylarını okur (durum ucu yalnızca teklif sayısını verir; bu uç teklif teklif, kalem kalem fiyat verir). Filtre parametreleri durum ucuyla aynıdır (disReferans(lar) / ihaleNo(lar) / limit).
GET https://sat.net.tr/api/v1/entegrasyon/talepler/teklifler?disReferans=ERP-1001
Authorization: Bearer satnet_live_...{
"sonuclar": [{
"disReferans": "ERP-1001",
"ihaleNo": "IHL-2026-0001",
"baslik": "Rulman alımı",
"durum": "kapandi",
"paraBirimi": "TRY",
"kazananVar": true,
"teklifGorunur": true,
"teklifler": [
{ "maskeAnahtari": "T1", "toplamTutar": 48250.00, "odemeVadesiGun": 30,
"teklifTarihi": "2026-07-20T12:00:00.000Z", "kazanan": true,
"tedarikciUnvan": "Örnek Rulman A.Ş.", "tedarikciVkn": "1234567890",
"kalemler": [ { "demandDetailId": 5567, "birimFiyat": 96.5,
"vergiYuzde": 20, "toplam": 48250.00, "teslimTarihi": null } ] },
{ "maskeAnahtari": "T2", "toplamTutar": 51000.00, "odemeVadesiGun": 60,
"teklifTarihi": "2026-07-21T08:30:00.000Z", "kazanan": false,
"kalemler": [ { "demandDetailId": 5567, "birimFiyat": 102.0,
"vergiYuzde": 20, "toplam": 51000.00, "teslimTarihi": null } ] }
]
}],
"bulunamadi": []
}| Alan | Açıklama |
|---|---|
teklifGorunur | false ise teklifler boştur: kapalı zarf ihalede son teklif tarihi geçmeden teklif detayları dönmez (açık eksiltmede yayından itibaren görünür). |
maskeAnahtari | T1..TN — teklif başına sabit maske etiketi (yeniden okumada değişmez). |
tedarikciUnvan, tedarikciVkn | YALNIZCA kazanan kesinleştiğinde ve yalnız kazanan teklifte bulunur; kaybedenler daima maskelidir. tedarikciVkn ile ERP tarafında cari eşleştirmesi yapabilirsiniz. |
kalemler | Kalem başına demandDetailId, birimFiyat, vergiYuzde, toplam, teslimTarihi. demandDetailId talep yanıtındakiyle aynıdır → kalemleri birebir eşlersiniz. |
Bölüm 5
SOAP servisi
WSDL üzerinden istemci üreten ERP'ler için tek uçlu SOAP servisi. İş mantığı REST ile ortaktır.
Servis adresi: POST https://sat.net.tr/api/soap/entegrasyon
WSDL: GET https://sat.net.tr/api/soap/entegrasyon?wsdl (aynı belge /api/soap/entegrasyon/wsdl adresinden de alınabilir — uzantı bekleyen araçlar için)
Ad alanı: https://sat.net.tr/entegrasyon
WSDL'de iki binding tanımlıdır: EntegrasyonSoap11 ve EntegrasyonSoap12. Yanıt, isteğin SOAP sürümünü aynalar: 1.1 için text/xml, 1.2 için application/soap+xml.
| Operasyon | Yetki | Karşılığı | Yanıt kökü |
|---|---|---|---|
CariAktar | cari:write | POST /api/v1/entegrasyon/cariler | CariAktarYanit |
TalepAktar | talep:write | POST /api/v1/entegrasyon/talepler | TalepAktarYanit |
DurumSorgula | durum:read | GET|POST /api/v1/entegrasyon/talepler/durum | DurumSorgulaYanit |
TeklifSorgula | teklif:read | GET|POST /api/v1/entegrasyon/talepler/teklifler | TeklifSorgulaYanit |
SiparisSorgula | siparis:read | GET /api/v1/entegrasyon/siparisler | SiparisSorgulaYanit |
SiparisDurumBildir | siparis:write | POST /api/v1/entegrasyon/siparisler/durum | SiparisDurumBildirYanit |
Alan adları REST ile aynı semantiktedir, XML geleneğine uygun olarak BaşHarfBüyük yazılır (disReferans → DisReferans). Tek istisna: TalepAktarYanit içinde REST'teki demandId alanı IhaleId adıyla döner.
5.1 · Örnek — TalepAktar
POST https://sat.net.tr/api/soap/entegrasyon
Content-Type: text/xml; charset=utf-8
Authorization: Bearer satnet_live_4bbf4964d4c7…
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<TalepAktar xmlns="https://sat.net.tr/entegrasyon">
<Talepler>
<Talep>
<Baslik>Rulman ve keçe alımı</Baslik>
<DisReferans>ERP-2026-000184</DisReferans>
<SonTeklifTarihi>2026-08-15T17:00:00.000Z</SonTeklifTarihi>
<ParaBirimi>TRY</ParaBirimi>
<TeslimatAdresi>Organize Sanayi Bölgesi 5. Cadde No:12 Bursa</TeslimatAdresi>
<Yayinla>false</Yayinla>
<Kalemler>
<Kalem>
<KalemAdi>6204 2RS Rulman</KalemAdi>
<Miktar>250</Miktar>
<Birim>adet</Birim>
<HedefBirimFiyat>12.50</HedefBirimFiyat>
</Kalem>
<Kalem>
<KalemAdi>Yağ keçesi 25x40x7</KalemAdi>
<Miktar>40</Miktar>
<Birim>adet</Birim>
</Kalem>
</Kalemler>
</Talep>
</Talepler>
</TalepAktar>
</soapenv:Body>
</soapenv:Envelope>HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<TalepAktarYanit xmlns="https://sat.net.tr/entegrasyon">
<Ozet>
<Toplam>1</Toplam>
<Taslak>1</Taslak>
<Yayinlandi>0</Yayinlandi>
<Mevcut>0</Mevcut>
<Hatali>0</Hatali>
</Ozet>
<Sonuc>
<Kayit>
<DisReferans>ERP-2026-000184</DisReferans>
<Durum>taslak</Durum>
<IhaleId>331</IhaleId>
</Kayit>
</Sonuc>
</TalepAktarYanit>
</soap:Body>
</soap:Envelope>5.2 · Örnek — DurumSorgula (kimlik SOAP Header'da)
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<ApiAnahtari>satnet_live_4bbf4964d4c7…</ApiAnahtari>
</soapenv:Header>
<soapenv:Body>
<DurumSorgula xmlns="https://sat.net.tr/entegrasyon">
<DisReferanslar>
<DisReferans>ERP-2026-000184</DisReferans>
<DisReferans>ERP-BULUNMAYAN</DisReferans>
</DisReferanslar>
</DurumSorgula>
</soapenv:Body>
</soapenv:Envelope><?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DurumSorgulaYanit xmlns="https://sat.net.tr/entegrasyon">
<Sonuclar>
<Kayit>
<DisReferans>ERP-2026-000184</DisReferans>
<IhaleNo/>
<Baslik>Rulman ve keçe alımı</Baslik>
<Durum>taslak</Durum>
<SonTeklifTarihi>2026-08-15T17:00:00.000Z</SonTeklifTarihi>
<OlusturmaTarihi>2026-07-18T20:53:38.049Z</OlusturmaTarihi>
<TeklifSayisi>0</TeklifSayisi>
<KalemSayisi>2</KalemSayisi>
<KazananVar>false</KazananVar>
</Kayit>
</Sonuclar>
<Bulunamadi>
<Deger>ERP-BULUNMAYAN</Deger>
</Bulunamadi>
</DurumSorgulaYanit>
</soap:Body>
</soap:Envelope>Boş değerler boş eleman olarak gelir (<IhaleNo/>). Maskeleme gereği KazananUnvan ve Siparis blokları, karşılığı yoksa yanıta hiç yazılmaz. Eşleşmeyen değerler Bulunamadi > Deger altında listelenir.
5.3 · Fault biçimi
Tüm hatalar SOAP Fault olarak döner ve HTTP 500 durumu kullanılır — bu, .NET ve Java istemcilerinin Fault gövdesini ayrıştırabilmesi için SOAP 1.1 sözleşmesinin gereğidir. Makine tarafından okunacak kod detail > Hata > Kod alanındadır.
HTTP/1.1 500 Internal Server Error
Content-Type: text/xml; charset=utf-8
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>Bu anahtarda 'talep:write' yetkisi yok.</faultstring>
<detail>
<Hata xmlns="https://sat.net.tr/entegrasyon">
<Kod>yetki_yok</Kod>
<Mesaj>Bu anahtarda 'talep:write' yetkisi yok.</Mesaj>
</Hata>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>SOAP 1.2 ile gönderilen isteklerde Fault da 1.2 zarfıyla döner: soap:Code > soap:Value değeri soap:Sender veya soap:Receiver olur.
5.4 · Sınırlar ve güvenlik
- Azami gövde boyutu 5 MB.
<!DOCTYPE>içeren gövdeler tümüyle reddedilir (XXE koruması); dış varlıklar hiçbir koşulda çözülmez.- Azami iç içe eleman derinliği 50.
- Sayısal alanlarda
250ve12.5(XSD) ile12,5(Türkçe ondalık) kabul edilir. Binlik ayraçlı1.234,56gibi değerler sessizce yanlış okunmak yerinedogrulamahatası üretir. - Metin alanları sayıya dönüştürülmez — başında sıfır olan vergi numaraları (
0123456789) olduğu gibi korunur.
Bölüm 6
Hata kodları
REST hataları tek tip bir JSON gövdesiyle döner; SOAP tarafında aynı kodlar Fault içinde taşınır.
{
"hata": {
"kod": "yetki_yok",
"mesaj": "Bu anahtarda 'talep:write' yetkisi yok."
}
}| Kod | REST durumu | SOAP Fault | Anlamı ve çözüm |
|---|---|---|---|
yetkisiz | 401 | soap:Client | Anahtar yok, biçimi bozuk, iptal edilmiş veya pasif. Authorization başlığını / ApiAnahtari elemanını kontrol edin. |
yetki_yok | 403 | soap:Client | Anahtar geçerli ama bu uç için gerekli yetkiye sahip değil. Yetki eklenmesi için destek ekibine başvurun. |
gecersiz_govde | 400 | soap:Client | Gövde geçerli JSON / XML değil. Content-Type ve karakter kodlamasını (UTF-8) doğrulayın. |
dogrulama | 422 | soap:Client | Şema doğru ama içerik kurallara uymuyor: zorunlu alan eksik, dizi sınırı aşıldı, limit aralık dışı, sayı okunamadı. |
islem | 4xx (genellikle 422) | soap:Client | İş kuralı engeli — örneğin hesaba bağlı aktif kullanıcı bulunmaması. Mesaj alanı nedeni açıklar. |
sunucu_hatasi | 500 | soap:Server | Beklenmeyen sunucu hatası. Geri çekilmeli (exponential backoff) tekrar deneyin; sürerse destek ekibine bildirin. |
bilinmeyen_operasyon | — (yalnız SOAP) | soap:Client | Zarftaki operasyon adı tanınmıyor. Geçerli adlar: CariAktar, TalepAktar, DurumSorgula. |
govde_buyuk | — (yalnız SOAP) | soap:Client | Gövde 5 MB sınırını aştı. İsteği daha küçük partilere bölün. |
guvenlik | — (yalnız SOAP) | soap:Client | Güvenlik kuralı ihlali (örn. DOCTYPE bildirimi, aşırı derinlik). Zarfı sadeleştirin. |
Kısmi başarı hata değildir
sonuc dizisinde durum: "hata" ve bir mesaj ile işaretlenir. Entegrasyonunuz yalnız HTTP durumuna değil, ozet.hatali sayacına ve kayıt bazlı sonuçlara da bakmalıdır.Bölüm 7
İdempotentlik ve iyi uygulamalar
Entegrasyonun tekrar gönderimlere, ağ kopmalarına ve zamanlanmış işlerin çakışmasına dayanıklı olması için.
Tekrar gönderim güvenlidir
Her iki yazma ucu da idempotenttir. Yanıtı alamadığınız bir isteği aynı gövdeyle tekrar göndermekten çekinmeyin — mükerrer kayıt oluşmaz.
- Cariler: anahtar
vergiNo. Tekrar gönderim mevcut kaydı günceller; boş bıraktığınız alanlar mevcut değerleri silmez. - Talepler: anahtar
disReferans. Aynı referans ikinci kez gelirse yeni ihale açılmaz;durum: "mevcut"ve ilk kaydındemandIddeğeri döner.
Dış referans (disReferans) tasarımı
- Her zaman gönderin. Referans göndermeyen istekler idempotentlik korumasından yararlanamaz; tekrar gönderim mükerrer ihale açar.
- ERP'deki talep kaydının değişmez birincil anahtarını kullanın (örn.
ERP-2026-000184). Kullanıcının değiştirebileceği bir alan (başlık, açıklama) referans olmamalı. - En çok 60 karakter. Birden çok ERP veya şirket kodu varsa ön ek verin (
SAP-TR01-000184) — böylece çakışma olmaz. - Referansı kendi tarafınızda da saklayın: durum sorgusu ve
bulunamadilistesi bu değer üzerinden eşleşir.
Toplu gönderim sınırları
| Uç | Sınır |
|---|---|
cariler | İstek başına 1–1000 cari |
talepler | İstek başına 1–200 talep; her talepte 1–200 kalem |
talepler/durum | Filtre listelerinin toplamı en çok 200 değer; filtresiz çağrıda limit 1–200 (varsayılan 50) |
SOAP | Azami gövde 5 MB; aynı içerik sınırları geçerli |
Önerilen çalışma düzeni
- Partileyin.Binlerce kaydı tek istekte değil, 100–500'lük partiler hâlinde gönderin; hata ayıklaması ve yeniden deneme çok daha kolay olur.
- Sıralı çalıştırın. Aynı verinin eşzamanlı iki aktarımını yapmayın; zamanlanmış işiniz bir önceki koşu bitmeden yeniden başlamasın.
- Durum sorgusunu makul aralıkla yapın. Çoğu senaryo için 15–60 dakikada bir yeterlidir. Yalnızca açık (taslak/yayında) ihalelerin referanslarını sorgulayın; sonuçlanmış kayıtları listeden çıkarın.
- Kısmi sonuçları işleyin. Yanıttaki
ozetsayaçlarını ve kayıt bazlıdurum/mesajalanlarını loglayın; yalnızca hatalı kayıtları düzeltip yeniden gönderin. - Geri çekilerek yeniden deneyin. 500 ve ağ hatalarında artan bekleme süreleriyle (örn. 1s, 4s, 16s) en çok birkaç kez deneyin; 4xx hatalarını tekrar denemeden önce gövdeyi düzeltin.
- Test edin. Canlıya almadan önce birkaç kayıtlık bir parti ile uçtan uca deneyin; talepleri
yayinla: falseile gönderip alıcı ekibin taslakları gözden geçirmesini sağlayın.
Yardıma mı ihtiyacınız var?
API anahtarı talebi, yetki eklenmesi, entegrasyon testi veya bu dokümantasyondaki bir konuda soru için bize yazın. Talebinizde firma unvanınızı, vergi numaranızı, kullanmayı planladığınız protokolü (REST/SOAP) ve ihtiyaç duyduğunuz yetkileri belirtirseniz süreç hızlanır.
destek@sat.net.tr