ARYD MELODİ ÇİKOLATA LOGO WEB API

Kullanım Dokümanı v1.0

İçindekiler

1. Genel Bilgiler

Base URL: {host}/api
Authentication: Basic Authentication (tüm isteklerde zorunludur)
Content-Type: application/json
JSON Serialization: Newtonsoft.Json

Bu API, LOGO ERP sistemine müşteri ve satış siparişi kayıtları oluşturmak için kullanılır.

2. Kimlik Doğrulama

Tüm API isteklerinde Basic Authentication kullanılmalıdır. Authorization header'ına aşağıdaki formatta kimlik bilgileri gönderilmelidir:

Authorization: Basic {base64(username:password)}
⚠️ Önemli: Kimlik doğrulama bilgileri olmadan yapılan istekler 401 Unauthorized hatası döndürecektir.

3. Endpoint: POST /api/CreateRecordInLogo

POST /api/CreateRecordInLogo

Açıklama

Bu endpoint, LOGO ERP sistemine cari (müşteri) kartı ve satış siparişi kaydı oluşturur. Cari bilgisi gönderilirse önce cari kartı oluşturulur veya güncellenir; ardından sipariş LOGO'ya kaydedilir.

⚠️ Önemli: Hem müşteri hem sipariş bilgileri gönderilebilir, ancak en az birinin gönderilmesi zorunludur.

İstek Yapısı

İstek üç ana bölümden oluşur:

1. LOGO_FIRMA_BILGILERI ZORUNLU

Alan Adı Tip Zorunlu Açıklama Örnek
LOGO_FIRMA_NUMARASI string ✓ LOGO firma numarası (min 3 karakter) "999", "001"
LOGO_DONEM_NUMARASI string ✓ LOGO dönem numarası (min 2 karakter) "01", "12"
LOGO_KULLANICI_ADI string ✓ LOGO kullanıcı adı "LOGO"
LOGO_KULLANICI_PAROLASI string ✓ LOGO kullanıcı parolası "3571"

2. CARI (MUSTERI) OPSIYONEL

LOGO Cari Hesap kartı oluşturma veya güncelleme için kullanılır. JSON alan adı musteri olsa da LOGO tarafında kayıt cari kartdır.

Cari ödeme planı: ODEME_PLANI_KODU gönderilirse LOGO cari kartında PAYMENT_CODE alanına yazılır (ör. 30GUN). Zoho senkronizasyonuna gönderilmez.

Zorunlu Cari (Müşteri) Alanları

Alan Adı Tip Açıklama
MUSTERI_KODU string Müşteri kodu (CARI_KODU olarak LOGO'ya kaydedilir)
MUSTERI_UNVANI string Müşteri unvanı (Ad-soyad gönderilmelidir)
MUSTERI_AD string Şahıs caride (TC_KIMLIK_NUMARASI) zorunlu; tüzel caride opsiyonel. LOGO NAME alanına yazılır.
MUSTERI_SOYAD string Şahıs caride (TC_KIMLIK_NUMARASI) zorunlu; tüzel caride opsiyonel. LOGO SURNAME alanına yazılır.
VERGI_NUMARASI string Vergi Kimlik No (VKN). TC_KIMLIK_NUMARASI ile tam olarak biri zorunludur; ikisi birden gönderilemez.
TC_KIMLIK_NUMARASI string T.C. Kimlik No. VERGI_NUMARASI ile tam olarak biri zorunludur; ikisi birden gönderilemez.
ULKE string Ülke adı
ULKE_KODU string Ülke kodu (ISO formatı önerilir)

Opsiyonel Cari (Müşteri) Alanları

Alan Adı Tip Açıklama
E_POSTA string E-posta adresi
TELEFON1 string Telefon numarası 1
TELEFON2 string Telefon numarası 2
IL string İl adı
IL_KODU string İl kodu
ILCE string İlçe adı
ILCE_KODU string İlçe kodu
ADRES1 string Adres satırı 1
ADRES2 string Adres satırı 2
VERGI_DAIRESI string Vergi dairesi
YABANCI_MUSTERI string Yabancı müşteri flag (0: Türk, 1: Yabancı). Varsayılan: "0"
OZEL_KOD string Özel kod (AUXIL_CODE olarak LOGO'ya kaydedilir)
ODEME_PLANI_KODU string Ödeme planı kodu (PAYMENT_CODE olarak LOGO'ya kaydedilir)

3.2. SEVKIYAT ADRESI OPSIYONEL

Gönderilirse LOGO'da doArpShipLic (SHIPINFO) objesine yazılır ve cari ile sipariş arasında işlenir. Aynı SEVKIYAT_ADRESI_KODU varsa güncellenir, yoksa yeni oluşturulur. Sipariş başlığındaki SEVKIYAT_ADRESI_KODU (SHIPLOC_CODE) bu adrese bağlanır.

Zorunlu Alanlar

Alan Adı Tip LOGO Alanı Açıklama
CARI_KODU string ARP_CODE Adresin bağlı olduğu cari (müşteri) kodu
SEVKIYAT_ADRESI_KODU string CODE Sevkiyat adresi (hesap) kodu
IL string CITY İl
ILCE string TOWN İlçe
POSTA_KODU string POSTAL_CODE Posta kodu
ULKE string COUNTRY Ülke (varsayılan: "Türkiye")
ULKE_KODU string COUNTRY_CODE Ülke kodu (varsayılan: "TR")

Opsiyonel Alanlar

Alan Adı Tip LOGO Alanı Açıklama
IL_KODU string CITY_CODE İl kodu
ILCE_KODU string TOWN_CODE İlçe kodu
ACIKLAMA string DESCRIPTION Açıklama
UNVAN string TITLE Ünvan
ADRES1 / ADRES2 string ADDRESS1 / ADDRESS2 Adres satırları
SEMT string DISTRICT Semt
TELEFON1 / TELEFON2 string TELEPHONE1 / TELEPHONE2 Telefon
YETKILI string INCHANGE Yetkili kişi
EPOSTA string EMAIL_ADDR E-posta
OZEL_KOD string AUXIL_CODE Özel kod
YETKI_KODU string AUTH_CODE Yetki kodu

3.3. SIPARIS OPSIYONEL

Zorunlu Sipariş Alanları

Alan Adı Tip Açıklama
SIPARIS_NO string Sipariş numarası. "~" gönderilirse LOGO otomatik numara atar. Varsayılan: "~"
MUSTERI_KODU string Siparişin bağlı olduğu müşteri kodu
SIPARIS_TARIHI DateTime Sipariş tarihi (ISO 8601 formatı)
OZEL_KOD string Özel kod
DOVIZ_TURU string Döviz türü (TL, USD, EUR, GBP). Varsayılan: "TL"
TICARI_ISLEM_GRUBU string Ticari işlem grubu (zorunlu).
KALEMLER Array Sipariş kalemleri listesi (en az 1 kalem olmalı)

Opsiyonel Sipariş Alanları

Alan Adı Tip Açıklama
OZEL_KOD string Özel kod
TICARI_ISLEM_GRUBU string Ticari işlem grubu
BELGE_NO string Belge numarası
YETKI_KODU string Yetki kodu
ACIKLAMA1 string Açıklama 1
ACIKLAMA2 string Açıklama 2
ACIKLAMA3 string Açıklama 3
ACIKLAMA4 string Açıklama 4
ACIKLAMA5 string Açıklama 5
ACIKLAMA6 string Açıklama 6
SINIRSIZ_ACIKLAMA string Sınırsız açıklama (255 karakterden uzunsa otomatik bölünür)
DOKUMAN_IZLEME_NUMARASI string Doküman izleme numarası
ODEME_PLANI_KODU string Sipariş ödeme planı kodu (PAYMENT_CODE olarak LOGO sipariş fişine kaydedilir)
PROJE_KODU string Proje kodu.
SEVKIYAT_ADRESI_KODU string Sevkiyat adresi kodu.

KALEMLER (Sipariş Kalemleri)

Her kalem bir SiparisKalemi nesnesidir. Kalemler 4 tipte olabilir (HIZMET, MALZEME, MASRAF, INDIRIM):

1. HIZMET veya MALZEME Kalemi

Alan Adı Tip Zorunlu Açıklama
SATIR_TURU string ✓ "HIZMET" veya "MALZEME" olmalı
SATIR_KODU string ✓ Satır (Hizmet/Malzeme vb.) kodu
MIKTAR double ✓ Miktar (0'dan büyük olmalı)
BIRIM_FIYAT double Birim fiyat (opsiyonel; gönderilmezse veya 0 ise LOGO'ya 0 yazılır)
BIRIM_KODU string ✓ Birim kodu
KDV_ORANI int ✓ KDV oranı (%)
KDV_DAHIL string KDV dahil mi? ("E" veya "H"). Varsayılan: "H"
HIZMET_ACIKLAMASI string Hizmet açıklaması
SATIR_ACIKLAMASI string Satır açıklaması
HAREKET_OZEL_KODU1 string Hareket özel kodu 1
HAREKET_OZEL_KODU2 string Hareket özel kodu 2
SINIRSIZ_ACIKLAMA string Sınırsız açıklama
TESLIM_TARIHI datetime Teslim tarihi (satır bazlı). LOGO sipariş satırında DUE_DATE alanına yazılır. Gönderilmezse sipariş tarihi (SIPARIS_TARIHI) kullanılır.

2. MASRAF Kalemi

Alan Adı Tip Zorunlu Açıklama
SATIR_TURU string ✓ "MASRAF" olmalı
MASRAF_TUTARI double ✓ Masraf tutarı (0'dan büyük olmalı)
KDV_ORANI int ✓ KDV oranı (%)
KDV_DAHIL string KDV dahil mi? ("E" veya "H"). Varsayılan: "H"
SATIR_ACIKLAMASI string Satır açıklaması
HAREKET_OZEL_KODU1 string Hareket özel kodu 1
HAREKET_OZEL_KODU2 string Hareket özel kodu 2
SINIRSIZ_ACIKLAMA string Sınırsız açıklama

3. INDIRIM Kalemi

Alan Adı Tip Zorunlu Açıklama
SATIR_TURU string ✓ "INDIRIM" olmalı
INDIRIM_KODU string ✓ İndirim kodu
INDIRIM_TUTARI double ✓ İndirim tutarı (0'dan büyük olmalı)
SATIR_ACIKLAMASI string Satır açıklaması
HAREKET_OZEL_KODU1 string Hareket özel kodu 1
HAREKET_OZEL_KODU2 string Hareket özel kodu 2
SINIRSIZ_ACIKLAMA string Sınırsız açıklama
⚠️ Önemli: SATIR_TURU alanı sadece "HIZMET", "MASRAF" veya "INDIRIM" değerlerini kabul eder.

Örnek İstekler

Tam Örnek (Müşteri + Sipariş)

{
    "logo_firma_bilgileri": {
        "LOGO_FIRMA_NUMARASI": "999",
        "LOGO_DONEM_NUMARASI": "01",
        "LOGO_KULLANICI_ADI": "LOGO",
        "LOGO_KULLANICI_PAROLASI": "3571"
    },
    "musteri": {
        "MUSTERI_KODU": "120.258729872",
        "MUSTERI_UNVANI": "Ahmet Yılmaz",
        "MUSTERI_AD": "Ahmet",
        "MUSTERI_SOYAD": "Yılmaz",
        "E_POSTA": "ahmet.yilmaz@example.com",
        "TELEFON1": "05321234567",
        "TELEFON2": "02121234567",
        "IL_KODU": "34",
        "IL": "İSTANBUL",
        "ILCE_KODU": "23",
        "ILCE": "KADIKÖY",
        "ULKE": "TÜRKİYE",
        "ULKE_KODU": "TR",
        "ADRES1": "Bağdat Caddesi No:123",
        "ADRES2": "Daire: 5",
        "VERGI_NUMARASI": "",
        "TC_KIMLIK_NUMARASI": "12345678901",
        "VERGI_DAIRESI": "Kadıköy",
        "YABANCI_MUSTERI": "0",
        "OZEL_KOD": "TEST",
        "ODEME_PLANI_KODU": "30GUN",
    },
    "sevkiyat_adresi": {
        "CARI_KODU": "120.258729872",
        "SEVKIYAT_ADRESI_KODU": "SEVK01",
        "ACIKLAMA": "Merkez Depo",
        "UNVAN": "Ahmet Yılmaz",
        "ADRES1": "Bağdat Caddesi No:123",
        "ADRES2": "Daire: 5",
        "SEMT": "Göztepe",
        "ILCE": "KADIKÖY",
        "IL": "İSTANBUL",
        "ULKE": "Türkiye",
        "ULKE_KODU": "TR",
        "POSTA_KODU": "34730",
        "TELEFON1": "05321234567",
        "EPOSTA": "ahmet.yilmaz@example.com",
        "YETKILI": "Ahmet Yılmaz"
    },
    "siparis": {
        "SIPARIS_NO": "~",
        "MUSTERI_KODU": "120.258729872",
        "SIPARIS_TARIHI": "2025-12-12T00:00:00",
        "OZEL_KOD": "SP001",
        "DOVIZ_TURU": "USD",
        "TICARI_ISLEM_GRUBU": "",
        "PROJE_KODU": "",
        "SEVKIYAT_ADRESI_KODU": "SEVK01",
        "KALEMLER": [
            {
                "SATIR_TURU": "HIZMET",
                "SATIR_KODU": "SATIS0011",
                "MIKTAR": 1,
                "BIRIM_FIYAT": 10000,
                "BIRIM_KODU": "ADET",
                "KDV_ORANI": 20,
                "KDV_DAHIL": "H",
                "TESLIM_TARIHI": "2025-12-15T00:00:00"
            },
            {
                "SATIR_TURU": "MASRAF",
                "MASRAF_TUTARI": 100,
                "KDV_ORANI": 20,
                "KDV_DAHIL": "H"
            },
            {
                "SATIR_TURU": "INDIRIM",
                "INDIRIM_KODU": "OSYM2",
                "INDIRIM_TUTARI": 5000
            }
        ]
    }
}

Sadece Müşteri Örneği

{
    "logo_firma_bilgileri": {
        "LOGO_FIRMA_NUMARASI": "999",
        "LOGO_DONEM_NUMARASI": "01",
        "LOGO_KULLANICI_ADI": "LOGO",
        "LOGO_KULLANICI_PAROLASI": "3571"
    },
    "musteri": {
        "MUSTERI_KODU": "120.258729872",
        "MUSTERI_UNVANI": "Ahmet Yılmaz",
        "MUSTERI_AD": "Ahmet",
        "MUSTERI_SOYAD": "Yılmaz",
        "ULKE": "TÜRKİYE",
        "ULKE_KODU": "TR",
        "VERGI_NUMARASI": "",
        "TC_KIMLIK_NUMARASI": "12345678901",
        "ODEME_PLANI_KODU": "30GUN"
    },
    "siparis": null
}

Yanıt Formatı

Başarılı Yanıt (200 OK)

{
    "message": "İşlem başarılı",
    "success": true,
    "ORDER_RESULT": {
        "LOGO_FICHENO": "SP2025001",
        "LOGO_REFERENCE": 12345,
        "LOGO_FIRM": 999,
        "LOGO_RESULT": "Başarılı"
    },
    "CUSTOMER_RESULT": {
        "LOGO_CUSTOMER_CODE": "120.258729872",
        "LOGO_REFERENCE": 67890,
        "LOGO_FIRM": 999,
        "LOGO_RESULT": "Başarılı"
    }
}

Validasyon Hatası (400 Bad Request)

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-xxx-xxx",
    "errors": {
        "musteri.MUSTERI_KODU": [
            "MUSTERI_KODU alanı zorunludur."
        ],
        "siparis.KALEMLER[0].SATIR_KODU": [
            "İlgili satır türü için SATIR_KODU alanı zorunludur."
        ]
    }
}

LOGO Bağlantı Hatası (400 Bad Request)

{
    "message": "LOGO bağlantı hatası",
    "success": false,
    "errors": [
        "1 - Kullanıcı adı veya parola hatalı"
    ]
}

Yanıt Alanları

ORDER_RESULT

Alan Adı Tip Açıklama
LOGO_FICHENO string LOGO'da oluşturulan sipariş fiş numarası
LOGO_REFERENCE int LOGO'da oluşturulan sipariş referans numarası
LOGO_FIRM int LOGO firma numarası
LOGO_RESULT string İşlem sonucu mesajı

CUSTOMER_RESULT

Alan Adı Tip Açıklama
LOGO_CUSTOMER_CODE string LOGO'da oluşturulan/güncellenen müşteri kodu
LOGO_REFERENCE int LOGO'da oluşturulan/güncellenen müşteri referans numarası
LOGO_FIRM int LOGO firma numarası
LOGO_RESULT string İşlem sonucu mesajı

Not: Eğer müşteri gönderilmemişse CUSTOMER_RESULT null olur.

Önemli Notlar

4. Endpoint: GET /api/GetSalesOrderStatus

GET /api/GetSalesOrderStatus

Açıklama

Bu endpoint, LOGO ERP satış siparişlerinin (ORFLINE) sevkiyat / kapanış durumunu firma + dönem bazında döner. Sipariş satırı bazında sevk edilen, bekleyen miktar ve satır/sipariş durumları hesaplanır.

⚠️ Önemli: LOGO_FIRMA_NO ve LOGO_DONEM_NO her zaman zorunludur. Filtre olarak ya SIPARIS_NO ya da BASLANGIC_TARIHI + BITIS_TARIHI gönderilmelidir. SIPARIS_NO gönderilmezse tarih aralığı zorunludur.

Query Parametreleri

Parametre Tip Zorunlu Açıklama
LOGO_FIRMA_NO string ✓ LOGO firma numarası (hangi firmadan çekileceği). Örn: "999"
LOGO_DONEM_NO string ✓ LOGO dönem numarası. Örn: "01"
SIPARIS_NO string Koşullu Sipariş fiş numarası (ORFICHE.FICHENO). Tekil sipariş sorgusu için. Tarih aralığı yerine kullanılır.
BASLANGIC_TARIHI date (yyyy-MM-dd) Koşullu Sipariş tarihi başlangıç. SIPARIS_NO gönderilmediğinde BITIS_TARIHI ile birlikte zorunludur.
BITIS_TARIHI date (yyyy-MM-dd) Koşullu Sipariş tarihi bitiş. SIPARIS_NO gönderilmediğinde BASLANGIC_TARIHI ile birlikte zorunludur.

Örnek İstekler

1. Tarih aralığı ile

GET /api/GetSalesOrderStatus?LOGO_FIRMA_NO=999&LOGO_DONEM_NO=01&BASLANGIC_TARIHI=2026-01-01&BITIS_TARIHI=2026-12-31

2. Sipariş numarası ile

GET /api/GetSalesOrderStatus?LOGO_FIRMA_NO=999&LOGO_DONEM_NO=01&SIPARIS_NO=SIP2026000001

Dönen Alanlar

Alan Adı Tip LOGO Kaynağı Açıklama
SIPARIS_NO string ORFICHE.FICHENO Sipariş fiş numarası
SIPARIS_TARIHI datetime ORFICHE.DATE_ Sipariş tarihi
SATIR_NO int ORFLINE.LINENO_ Sipariş satır numarası
CARI_KODU string CLCARD.CODE Cari (müşteri) kodu
CARI_ADI string CLCARD.DEFINITION_ Cari (müşteri) ünvanı
URUN_KODU string ITEMS.CODE Malzeme/ürün kodu
URUN_ADI string ITEMS.NAME Malzeme/ürün adı
SIP_MIKTARI double ORFLINE.AMOUNT Sipariş miktarı
SEVKEDILEN double ORFLINE.SHIPPEDAMOUNT Sevk edilen miktar
BEKLEYEN double hesaplanan Bekleyen miktar (Sipariş - Sevk edilen)
SATIR_DURUMU string hesaplanan Satır durumu: "Kapandi", "Bekleyen" veya "Kismi"
TOPLAM_SATIR int hesaplanan Siparişteki toplam satır sayısı
KAPANAN_SATIR int hesaplanan Tamamı sevk edilmiş (kapanan) satır sayısı
HIC_SEVK_EDILMEYEN_SATIR int hesaplanan Hiç sevk edilmemiş satır sayısı
SIPARIS_STATU string hesaplanan Sipariş geneli durumu: "Tamami Kapandi", "Bekleyen Siparis" veya "Kismi Kapandi"

Örnek Yanıt (200 OK)

{
    "success": true,
    "data": [
        {
            "SIPARIS_NO": "SIP2026000001",
            "SIPARIS_TARIHI": "2026-01-05T00:00:00",
            "SATIR_NO": 1,
            "CARI_KODU": "120.01.001",
            "CARI_ADI": "Ahmet Yılmaz",
            "URUN_KODU": "MALZ01",
            "URUN_ADI": "Test Ürün",
            "SIP_MIKTARI": 10,
            "SEVKEDILEN": 4,
            "BEKLEYEN": 6,
            "SATIR_DURUMU": "Kismi",
            "TOPLAM_SATIR": 3,
            "KAPANAN_SATIR": 1,
            "HIC_SEVK_EDILMEYEN_SATIR": 1,
            "SIPARIS_STATU": "Kismi Kapandi"
        }
    ]
}

5. HTTP Status Kodları

Kod Açıklama

6. Sorun Giderme

Yaygın Hatalar ve Çözümleri

Hata: "SATIR_TURU alanı sadece 'HIZMET', 'MASRAF' veya 'INDIRIM' değerlerini kabul eder."

Çözüm: SATIR_TURU alanını doğru değerlerden biriyle gönderin.

Hata: "İlgili satır türü için SATIR_KODU alanı zorunludur."

Çözüm: SATIR_TURU "HIZMET" veya "MALZEME" ise, SATIR_KODU, MIKTAR, BIRIM_KODU ve KDV_ORANI alanlarını doldurun. BIRIM_FIYAT opsiyoneldir.

Hata: LOGO bağlantı hatası

Çözüm: logo_firma_bilgileri içindeki bilgilerin doğruluğunu kontrol edin. Firma numarası, dönem numarası, kullanıcı adı ve parolasının doğru olduğundan emin olun.

Hata: 401 Unauthorized

Çözüm: Basic Authentication bilgilerinizi kontrol edin. Authorization header'ının doğru formatta gönderildiğinden emin olun.

Hata: Fiyat bulunamadı

Çözüm: Hizmet kodunun doğru olduğundan ve LOGO sisteminde tanımlı olduğundan emin olun. Döviz kodunun geçerli bir değer olduğunu kontrol edin (TL, USD, EUR, GBP).

En İyi Uygulamalar

Destek ve İletişim

API kullanımı hakkında sorularınız veya sorunlarınız için: