Mengintegrasikan API perlindungan pembelian

Artikel
05/20/2024

Artikel ini menjelaskan cara mengintegrasikan antarmuka pemrograman aplikasi real time (API) di Perlindungan Penipuan Microsoft Dynamics 365.

Untuk memanfaatkan rangkaian lengkap fitur Perlindungan Penipuan, Anda harus mengirim data transaksi Anda ke API Perlindungan Penipuan real time. Dalam pengalaman evaluasi, mengirim data transaksi memungkinkan Anda menganalisis hasil penggunaan Perlindungan Penipuan. Dalam pengalaman perlindungan, Anda juga dapat mematuhi keputusan, berdasarkan aturan yang telah Anda konfigurasi.

Bergantung pada cara Anda menggunakan Perlindungan Penipuan, Anda mungkin menggunakan berbagai set API perlindungan pembelian berikut:

Beli
PurchaseStatus
BankEvent
Penagihan Balik
Pengembalian dana
UpdateAccount
Label

Fase integrasi API

Integrasi API perlindungan pembelian terjadi dalam tiga fase:

Buat aplikasi Microsoft Entra melalui Perlindungan Penipuan.
Membuat token akses.
Hubungi API.

Penting

Anda harus menjadi administrator global di penyewa Azure Anda untuk menyelesaikan proses masuk awal.

Kunjungi portal berikut untuk setiap lingkungan yang ingin Anda gunakan. Masuk, dan terima syarat dan ketentuan jika Anda diminta untuk melakukannya.

Lingkungan kotak pasir
Lingkungan produksi (Anda mungkin sudah menyelesaikan langkah ini dalam produksi selama pendaftaran awal.)

Membuat aplikasi Microsoft Entra

Penting

Anda harus menjadi administrator aplikasi, administrator aplikasi cloud, atau administrator global di penyewa Azure Anda untuk menyelesaikan langkah ini.

Untuk memperoleh token yang diperlukan untuk memanggil API, Anda harus mengonfigurasi dan menggunakan aplikasi Microsoft Entra seperti yang dijelaskan di bagian ini.

Mengonfigurasi aplikasi Microsoft Entra

Untuk mengonfigurasi aplikasi Microsoft Entra, ikuti langkah-langkah berikut.

Di portal Perlindungan Penipuan, di panel navigasi kiri, pilih Integrasi > Buat Penyiapan Aplikasi > Microsoft Entra sekarang.
Lengkapi halaman untuk membuat aplikasi Anda. Kami menyarankan agar Anda membuat satu aplikasi Microsoft Entra untuk setiap lingkungan yang ingin Anda integrasikan dengan Perlindungan Penipuan.
Masukkan atau pilih nilai untuk bidang yang diperlukan berikut ini:
- Nama tampilan aplikasi – Beri aplikasi Anda nama deskriptif. Panjang maksimum adalah 93 karakter.
- Metode autentikasi – Pilih apakah Anda ingin mengautentikasi melalui sertifikat atau rahasia (kata sandi).
Jika Anda memilih metode autentikasi sertifikat, ikuti langkah-langkah berikut:
1. Pilih Pilih file untuk mengunggah kunci publik. (Kunci privat yang cocok diperlukan saat Anda memperoleh token.)
2. Pilih Rahasia untuk membuat kata sandi secara otomatis setelah aplikasi dibuat.
Setelah Anda selesai mengatur bidang yang diperlukan, pilih Buat aplikasi. Halaman konfirmasi meringkas nama, ID, dan thumbprint sertifikat atau rahasia aplikasi Anda, tergantung pada metode autentikasi yang Anda pilih.

Penting

Simpan informasi thumbprint rahasia atau sertifikat Anda untuk referensi di masa mendatang. Rahasia hanya akan ditampilkan sekali.

Membuat aplikasi lain

Untuk membuat aplikasi lain, pilih Buat aplikasi lain. Anda dapat membuat aplikasi sebanyak yang Anda butuhkan untuk menjalankan panggilan API di setiap lingkungan Anda.

Mengelola aplikasi Microsoft Entra yang ada

Setelah membuat aplikasi Microsoft Entra, Anda dapat mengelolanya melalui [portal Azure](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Untuk informasi selengkapnya, lihat Bagaimana dan mengapa aplikasi ditambahkan ke ID Microsoft Entra.

Membuat token akses

Untuk mengintegrasikan sistem Anda dengan Perlindungan Penipuan dengan aman, dapatkan token Microsoft Entra, dan berikan di header setiap panggilan API.

Catatan

Token akses memiliki masa pakai terbatas 60 menit. Sebaiknya Anda menyimpan cache dan menggunakan kembali token hingga hampir kedaluwarsa. Anda kemudian bisa mendapatkan token akses baru.

Informasi berikut diperlukan untuk mendapatkan token.

ID dan informasi yang diperlukan

URI Lingkungan – URI untuk kotak pasir atau lingkungan produksi Anda muncul di tab Konfigurasi halaman API Management di portal Perlindungan Penipuan.
ID Direktori (penyewa) – ID ini adalah pengidentifikasi unik global (GUID) domain penyewa di Azure. Ini muncul di portal Azure dan pada tab Konfigurasi halaman API Management di portal Perlindungan Penipuan.
ID Aplikasi (klien) – ID ini mengidentifikasi aplikasi Microsoft Entra yang telah Anda buat untuk memanggil API. Dapatkan ID dari halaman konfirmasi API Real-time, atau temukan nanti di bawah Pendaftaran aplikasi di portal Azure. Akan ada satu ID untuk setiap aplikasi yang Anda buat.
Thumbprint sertifikat atau rahasia – Dapatkan thumbprint atau rahasia dari halaman konfirmasi API Real-time.
ID Instans – ID ini adalah GUID lingkungan Anda dalam Perlindungan Penipuan. Ini muncul di petak integrasi di dasbor Perlindungan Penipuan.

Contoh: Sampel kode yang menunjukkan cara memperoleh token dengan menggunakan sertifikat atau rahasia Anda

Sampel kode C# berikut memberikan contoh memperoleh token dengan sertifikat atau rahasia Anda. Ganti tempat penampung dengan informasi spesifik Anda. Untuk kedua sampel C#, Anda harus mengimpor paket NuGet Microsoft.Identity.Client.

Untuk sampel dalam bahasa lain, lihat https://aka.ms/aaddev.

Mendapatkan token akses dengan menggunakan ID aplikasi dan kunci sertifikat privat

/// <summary>
/// Gets an access token using an app ID and private certificate key.
/// </summary>
/// <param name="tenantId">Directory (tenant) ID, in GUID format</param>
/// <param name="clientId">Application (client) ID</param>
/// <param name="certPath">File path to the certificate file (pfx) used to authenticate your application to Microsoft Entra ID</param>
/// <param name="certPassword">Password to access to the certificate file's private key</param>
public async Task<string> AcquireTokenWithCertificate(string tenantId, string clientId, string certPath, string certPassword)
{
    var certificate = new X509Certificate2(certPath, certPassword);

    var app = ConfidentialClientApplicationBuilder.Create(clientId)
            .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
            .WithCertificate(certificate)
            .Build();

    var scopes = new string[] { "<API endpoint for INT or PROD>; should be https://api.dfp.microsoft-int.com/.default or https://api.dfp.microsoft.com/.default" };

    try
    {
        var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
        return result.AccessToken;
    }
    catch (MsalServiceException ex)
    {
        //Handle authentication exceptions
        throw ex;
    }
}

Mendapatkan token akses dengan menggunakan ID aplikasi dan rahasia

/// <summary>
/// Gets an access token using an app ID and secret.
/// </summary>
/// <param name="tenantId">Directory (tenant) ID, in GUID format</param>
/// <param name="clientId">Application (client) ID</param>
/// <param name="clientSecret">The secret (password) used to authenticate the client (application) ID</param>
public async Task<string> AcquireTokenWithSecret(string tenantId, string clientId, string clientSecret)

{
    var app = ConfidentialClientApplicationBuilder.Create(clientId)
            .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
            .WithClientSecret(clientSecret)
            .Build();

    var scopes = new string[] { "<API endpoint for INT or PROD>; should be https://api.dfp.microsoft-int.com/.default or https://api.dfp.microsoft.com/.default" };

    try
    {
        var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
        return result.AccessToken;
    }
    catch (MsalServiceException ex)
    {
        //Handle authentication exceptions
        throw ex;
    }
}

Objek AuthenticationResult dalam setiap kasus berisi nilai AccessToken dan properti ExpiresOn yang menunjukkan kapan token akan menjadi tidak valid.

PERMINTAAN POST ke:
- https://login.microsoftonline.com/<Microsoft Entra tenant ID>/oauth2/token
Header:
- Jenis konten: application/x-www-form-urlencoded
Isi (kunci-nilai):
- grant_type: client_credentials
- client_id: {ID Klien Anda dari langkah sebelumnya}
- client_secret: {Rahasia Anda dari langkah sebelumnya}
- sumber daya: https://api.dfp.microsoft.com (untuk int, https://api.dfp.microsoft-int.com)
Respons:
- Gunakan nilai access_token dari respons untuk langkah berikutnya.

Untuk informasi selengkapnya, lihat dokumentasi Azure berikut ini:

Memanggil API

Untuk memanggil API, ikuti langkah-langkah berikut.

Berikan header HTTP yang diperlukan berikut pada setiap permintaan.

Nama header	Nilai Header
Authorization	Gunakan format berikut untuk header ini. (Ganti accesstoken dengan nilai token aktual yang dikembalikan oleh MICROSOFT Entra ID.) Accesstoken pembawa
x-ms-correlation-id	Kirim nilai GUID baru pada setiap set panggilan API yang dibuat bersama-sama.
x-ms-dfpenvid	Kirim nilai GUID ID instans Anda.

Nama header

Nilai Header

Authorization

Gunakan format berikut untuk header ini. (Ganti accesstoken dengan nilai token aktual yang dikembalikan oleh MICROSOFT Entra ID.)

Accesstoken pembawa

x-ms-correlation-id

Kirim nilai GUID baru pada setiap set panggilan API yang dibuat bersama-sama.

x-ms-dfpenvid

Kirim nilai GUID ID instans Anda.

Buat payload berbasis peristiwa. Isi data peristiwa dengan informasi yang relevan dari sistem Anda. Untuk dokumentasi tentang semua peristiwa yang didukung, lihat Dynamics 365 Fraud Protection API.
Gabungkan header (yang mencakup token akses) dan payload, lalu kirimkan ke titik akhir Perlindungan Penipuan Anda.
- PERMINTAAN POST ke:
  - <Base URL>/v1.0/merchantservices/events/purchase
- Header:
  - x-ms-correlation-id: {A GUID, yang harus unik per permintaan}
  - content-type: application/json
  - Otorisasi: {Token dari langkah sebelumnya}
  - x-ms-dfpenvid: {ID lingkungan lingkungan lingkungan target}
- Badan:
  - Dapatkan isi permintaan perlindungan akun sampel dari halaman Swagger bersama.

Catatan

Jika Anda membuat lingkungan baru, sertakan ID lingkungan di header API selama integrasi, sehingga transaksi dapat dirutekan dengan benar.

Opsi berikut dapat diterima untuk x-ms-dfpenvid dalam panggilan API dan perilakunya identik.

Gunakan ID lingkungan untuk lingkungan yang Anda panggil. ID tercantum di halaman Integrasi di bidang ID Lingkungan.
Gunakan pat lengkap ID API Pelanggan dari akar ke lingkungan anak yang Anda panggil menggunakan garis miring (/) sebagai pembagi. Misalnya, /primary/XYZ.
Gunakan jalur lengkap ID lingkungan atau ID API pelanggan dari akar ke lingkungan anak yang Anda panggil menggunakan garis miring (/) sebagai pembagi. Misalnya, 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Untuk menentukan ID API pelanggan saat Anda mengkreat lingkungan, lihat artikel, Mengelola lingkungan.

Praktik terbaik

Setiap token Microsoft Entra tetap berlaku selama 60 menit. Kami menyarankan agar Anda menyimpannya dalam durasi yang lebih singkat dan menggunakannya kembali.
Pastikan HttpClient Anda memiliki koneksi tetap aktif.
Selalu teruskan header x-ms-dfpenvid , dan pastikan itu menunjuk ke lingkungan pedagang yang ingin Anda kirim transaksi atas nama.
Simpan rahasia di penyimpanan rahasia.
Selalu berikan header x-ms-correlation-id untuk sesi penelusuran kesalahan di masa mendatang dengan Perlindungan Penipuan.
Pastikan header x-ms-correlation-id unik untuk setiap transaksi yang dikirim ke Perlindungan Penipuan.

Menampilkan aplikasi sampel

Untuk referensi tambahan, Anda dapat melihat contoh aplikasi pedagang dan dokumentasi pengembang yang menyertainya. Aplikasi sampel memberikan contoh cara memanggil API Perlindungan Penipuan, termasuk peristiwa API seperti mengirim pembaruan akun pelanggan, pengembalian dana, dan penagihan balik secara real time. Dokumentasi untuk aplikasi sampel ditautkan ke kode sampel aktual setiap kali tautan tersebut dimungkinkan. Jika tidak, sampel kode ada langsung dalam dokumentasi.

Untuk panduan tentang cara mengonfigurasi situs sampel untuk penggunaan Anda, lihat Mengonfigurasi situs sampel.

Bagikan melalui

Mengintegrasikan API perlindungan pembelian

Fase integrasi API

Membuat aplikasi Microsoft Entra

Mengonfigurasi aplikasi Microsoft Entra

Membuat aplikasi lain

Mengelola aplikasi Microsoft Entra yang ada

Membuat token akses

ID dan informasi yang diperlukan

Contoh: Sampel kode yang menunjukkan cara memperoleh token dengan menggunakan sertifikat atau rahasia Anda

Mendapatkan token akses dengan menggunakan ID aplikasi dan kunci sertifikat privat

Mendapatkan token akses dengan menggunakan ID aplikasi dan rahasia

Memanggil API

Praktik terbaik

Menampilkan aplikasi sampel

Saran dan Komentar

Sumber Daya Tambahan: