Entegratörler İçin

Doğrudan JSON API veya hazır UBL kullanan entegratörlerin yeni bir SMS gönderme endpointi çağırması beklenmez. Entegratörün kendi doğrulama sürecinde elde ettiği bilgiler, zaten kullanılan e-müstahsil makbuzu oluşturma veya güncelleme endpointine eklenmelidir.

Entegratörlerin kullandığı endpointler

Yeni doğrulama davranışı, entegratörlerin zaten kullandığı oluşturma ve güncelleme endpointlerine eklenecektir. Endpoint adresleri değişmeyecek; request ve response modelleri genişletilecektir.

JSON endpointleri

UBL endpointleri

Sorgulama response değişikliği

Veri Sorumluluk Tablosu

Aktivasyon sonrasında doğrudan entegrasyon kullanan sistemlerin API çağrısından önce sağlaması gereken doğrulama verileri aşağıdaki sorumluluk sınırına göre hazırlanmalıdır.

Senaryo Bazlı Hazırlık Matrisi

Request model değişiklikleri

OutgoingCreditNoteRequestModel, üst seviyedeki yöntem alanı ve iki doğrulama nesnesiyle genişletilecektir. Aktivasyon sonrasında yöntem veya alt alanlar eksik gönderilmemelidir.

Planlanan JSON model örneği

Örnek, normal bir e-Müstahsil Makbuzu için gereken belge alanlarıyla doğrulama alanlarını birlikte içerir ve JSON olarak doğrudan kopyalanabilir.

{
  "CreditNoteExternalId": "ERP-MM-2026-001",
  "ProfileId": "EARSIVBELGE",
  "CreditNoteTypeCode": "MUSTAHSILMAKBUZ",
  "DocumentCurrencyCode": "TRY",
  "IssueDate": "2026-08-01T09:00:00",
  "AccountingSupplierParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "TCKN",
          "Value": "12345678901"
        }
      ],
      "PartyName": "Ahmet Çiftçi",
      "PostalAddress": {
        "CityName": "Denizli",
        "Country": {
          "Name": "Türkiye"
        }
      }
    }
  },
  "AccountingCustomerParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "VKN",
          "Value": "1234567890"
        }
      ],
      "PartyName": "Örnek Tarım Ürünleri A.Ş."
    }
  },
  "LegalMonetaryTotal": {
    "LineExtensionAmount": 5000,
    "TaxExclusiveAmount": 5000,
    "TaxInclusiveAmount": 5000,
    "PayableAmount": 5000
  },
  "TaxTotal": [
    {
      "TaxAmount": 0,
      "TaxSubtotal": [
        {
          "TaxableAmount": 5000,
          "TaxAmount": 0,
          "Percent": 0,
          "TaxCategory": {
            "TaxScheme": {
              "TaxTypeCode": "0015"
            }
          }
        }
      ]
    }
  ],
  "CreditNoteLine": [
    {
      "Id": "1",
      "CreditedQuantity": {
        "UnitCode": "KGM",
        "Value": 1000
      },
      "LineExtensionAmount": 5000,
      "Item": {
        "Name": "Yaş Sebze"
      },
      "Price": 5,
      "TaxTotal": {
        "TaxAmount": 0,
        "TaxSubtotal": [
          {
            "TaxableAmount": 5000,
            "TaxAmount": 0,
            "Percent": 0,
            "TaxCategory": {
              "TaxScheme": {
                "TaxTypeCode": "0015"
              }
            }
          }
        ]
      }
    }
  ],
  "VerificationMethod": "SMS",
  "VerificationInfo": {
    "Code": "482193",
    "PhoneNumber": "905551112233"
  },
  "VerificationProvider": {
    "ApplicationName": "SMS_SAGLAYICI_ADI",
    "Vkn": "1234567890"
  }
}

UBL model değişiklikleri

Planlanan UBL kullanım örneği

Aşağıdaki parçalar mevcut AccountingCustomerParty ve AccountingSupplierParty taraflarının Party düğümlerine eklenmelidir. Örnekte gösterilmeyen kimlik, unvan, adres ve vergi bilgileri mevcut UBL yapısında korunmalıdır.

<!-- Üreticinin doğruladığı kod ve kodun gönderildiği telefon -->
<cac:AccountingCustomerParty>
  <cac:Party>
    <!-- Mevcut PartyIdentification, PartyName ve PostalAddress alanları -->
    <cac:Contact>
      <cbc:ID>482193</cbc:ID>
      <cbc:Name>SMS</cbc:Name>
      <cbc:Telephone>905551112233</cbc:Telephone>
    </cac:Contact>
  </cac:Party>
</cac:AccountingCustomerParty>

<!-- SMS sağlayıcısının adı ve VKN'si -->
<cac:AccountingSupplierParty>
  <cac:Party>
    <!-- Mevcut PartyIdentification, PartyName ve PostalAddress alanları -->
    <cac:Contact>
      <cac:OtherCommunication>
        <cbc:ChannelCode name="SMS_PROVIDER">SMS_SAGLAYICI_ADI</cbc:ChannelCode>
        <cbc:Value>1234567890</cbc:Value>
      </cac:OtherCommunication>
    </cac:Contact>
  </cac:Party>
</cac:AccountingSupplierParty>

Response model değişiklikleri

OutgoingCreditNoteResponseModel belge detayında, OutgoingCreditNoteHistoryResponseModel ise geçmiş kaydında VerificationMethod değerini taşır. OutgoingCreditNoteStatusForUser kullanıcıya gösterilecek SMS sürecini, mevcut OutgoingCreditNoteStatus ise ana belge durumunu taşımaya devam eder. VerificationMethod grid response modelinde bulunmaz.

Başarılı ve başarısız yanıt örnekleri

Oluşturma ve güncelleme endpointleri işlem sonucunu Data.HasError altında taşır. Portalın kullandığı SMS gönderme ve kod doğrulama endpointlerinde request iş kuralı hatası oluştuğunda ise API hata zarfı döner. Entegrasyon bu iki yanıt biçimini birbirine karıştırmamalıdır.

Başarılı oluşturma yanıtı

{
  "RefreshToken": "",
  "Data": {
    "HasError": false,
    "Errors": [
      {
        "ErrorCode": null,
        "ErrorMessage": null
      }
    ],
    "CreditNoteNumber": "MUS2026000000145",
    "Ettn": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Başarısız oluşturma yanıtı

Aktivasyon sonrasında doğrudan entegrasyonda doğrulama alanlarından biri eksik gönderilirse oluşturma veya güncelleme sonucu aşağıdaki biçimde döner.

{
  "RefreshToken": "",
  "Data": {
    "HasError": true,
    "Errors": [
      {
        "ErrorCode": "SCM0002",
        "ErrorMessage": "VerificationProvider.Vkn zorunlu bir elemandır boş geçilemez!"
      }
    ],
    "CreditNoteNumber": null,
    "Ettn": null
  }
}

Portal SMS endpointi hata yanıtı

Yeni SMS gönderme ve kod doğrulama kontrolleri mevcut API hata zarfını kullanır. Bu endpointler yalnızca VBT Portal tarafından çağrılır; Portal dışındaki kanallar EMM0057 ile reddedilir. Hata ayrımında HTTP durumuyla birlikte ErrorCode dikkate alınmalı; programatik akış değişebilecek mesaj metnine bağlanmamalıdır.

{
  "Type": 2,
  "Type_Desc": "Business",
  "ErrorCode": "EMM0054",
  "Message": "Telefon numarası geçerli bir Türkiye mobil numarası olmalıdır.",
  "Detail": {
    "StackTrace": null,
    "Type": "Vbt.Core.ExceptionHandling.VbtException",
    "InnerExceptions": null
  }
}

Edge-Case Tablosu

Entegratör geçiş kontrol listesi

• VBT aktivasyon duyurusu ve yürürlük tarihi alındı.
• Kullanılan oluşturma ve güncelleme endpointleri belirlendi.
• VerificationMethod = SMS, iki doğrulama nesnesi ve dört alt alan eşlendi.
• Hazır UBL üreten sistemlerde SMS ve SMS_PROVIDER sabitleri eklendi.
• Detay ve geçmiş response parser'ları VerificationMethod alanını okuyacak şekilde güncellendi.
• OutgoingCreditNoteStatusForUser durumları desteklendi.
• Eksiksiz JSON, eksik yöntem, geçersiz yöntem, kısmi JSON, eksiksiz UBL ve kısmi UBL senaryoları test edildi.
• Üretim değişikliği yalnızca duyurulan aktivasyon tarihinde açıldı.

Entegratör durum akışı

Doğrudan entegrasyonda Portalın etkileşimli SMS adımları bulunmaz. Request, doğrulama yöntemi ve doğrulama alanlarının bütünlüğüne göre mevcut belge işleme akışına alınır veya reddedilir.

Entegratör state akışı

Doğrudan JSON veya UBL entegrasyonunda etkileşimli SMS adımları bulunmaz. Request, yöntem ve doğrulama alanları eksiksizse mevcut belge işleme akışına alınır; eksik veya geçersiz yöntem ile kısmi veri doğrudan reddedilir.

Yeni hata kodları ve beklenen davranış

Tablodaki API mesajı sütunu, kaynak projedeki gerçek lokalizasyon metnini gösterir. Yapılacak işlem sütunu ise mesajın entegrasyon veya operasyon tarafında nasıl ele alınacağını açıklar.

Teknik Entegrasyon Soruları