Referensi API AWS Marketplace direstrukturisasi. Untuk informasi selengkapnya tentang operasi API yang didukung, lihat Referensi API AWS Marketplace.

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Bekerja dengan API Perjanjian sebagai pembeli

Perjanjian adalah dokumen yang mengikat dua pihak, termasuk pengusul dan akseptor (umumnya, pembeli) dan mendefinisikan syarat dan ketentuan yang berlaku di antara mereka.

Pembeli membuat AgreementRequest, yang menghasilkan kutipan. Kutipan ini mencakup semua informasi yang relevan, seperti perkiraan biaya yang akan dikeluarkan selama masa perjanjian, yang sangat penting untuk keputusan pembelian pembeli. Jika pembeli puas dengan penawaran, mereka dapat menerima AgreementRequest sebelum kedaluwarsa. Perjanjian dibuat setelah penerimaan AgreementRequest. Selama proses ini, admin pembeli atau persona pembeli dapat mengaitkan pesanan pembelian dengan biaya. Akhirnya, berdasarkan syarat dan ketentuan perjanjian aktif, pembeli ditagih dan diberikan Lisensi untuk menggunakan produk.

Prasyarat: Temukan produk dan penawaran

Sebelum membuat perjanjian, gunakan AWS Marketplace Discovery API untuk menemukan produk dan mendapatkanagreementProposalId,pricingModel, dan rincian istilah yang diperlukan untuk membangunCreateAgreementRequest.

Untuk informasi rinci tentang menemukan produk dan harga, lihatTemukan produk dan harga.

Akseptor dapat melakukan tugas-tugas berikut menggunakan API ini:

Hasilkan penawaran

Gunakan CreateAgreementRequest untuk menghasilkan kutipan. Anda harus memberikan:

response = client.create_agreement_request(
    agreementProposalIdentifier='at-edhtjnbilupjv3xqbphtom77y',
    intent='NEW',
    requestedTerms=[
        {'id': 'term-legal-abc123'},
        {'id': 'term-validity-def456'},
        {
            'id': 'term-configurable-pricing-789',
            'configuration': {
                'configurableUpfrontPricingTermConfiguration': {
                    'selectorValue': 'P12M',
                    'dimensions': [
                        {'dimensionKey': 'Users', 'dimensionValue': 50}
                    ]
                }
            }
        },
        {
            'id': 'term-renewal-012',
            'configuration': {
                'renewalTermConfiguration': {'enableAutoRenew': True}
            }
        }
    ]
)

print(f"Agreement Request ID: {response['agreementRequestId']}")
for charge in response['chargeSummary']['expectedCharges']:
    print(f"  Charge ID: {charge['id']}, Amount: ${charge['amount']}")

Membangun RequestedTerms

Untuk membangunrequestedTerms, Anda perlu menentukan dua hal:

Persyaratan yang diperlukan berdasarkan model harga

pricingModel.PricingModelBidang dalam GetOfferrespons menentukan istilah mana yang harus disertakan dalam AndaCreateAgreementRequest.

Ketentuan berikut harus dimasukkan dalam setiap perjanjian ketika hadir dalam penawaran:LegalTerm,SupportTerm,ValidityTerm, danRenewalTerm.

KONTRAK

Semua persyaratan yang dikembalikan GetOfferTermsoleh diperlukan dalam satuCreateAgreementRequest.

PEMAKAIAN

Pembuatan perjanjian tergantung pada ketentuan yang ada dalam penawaran:

BYOL

Terima ByolPricingTerm bersama dengan persyaratan wajib.

Konfigurasi istilah

Sebagian besar istilah hanya membutuhkan id dari GetOfferTerms. Jenis istilah berikut membutuhkan pembeli yang dipasok configuration selain: id

ConfigurableUpfrontPricingTermConfiguration

Gunakan contoh di bawah ini untuk menemukan nilai yang dibutuhkan untukConfigurableUpfrontPricingTermConfiguration.

Contoh GetOfferTerms respon:

{
  "offerTerms": [
    {
      "configurableUpfrontPricingTerm": {
        "id": "term-34dfb665ebd38eb2d0269a4af454c4f33cd90292ecc7b0f71058175594f67394",
        "currencyCode": "USD",
        "rateCards": [
          {
            "constraints": {
              "multipleDimensionSelection": "Allowed",
              "quantityConfiguration": "Allowed"
            },
            "selector": {
              "type": "Duration",
              "value": "P1M"
            },
            "rateCard": [
              {
                "dimensionKey": "BasicService",
                "displayName": "Basic Service",
                "price": "0",
                "unit": "Units"
              },
              {
                "dimensionKey": "PremiumService",
                "displayName": "Premium Service",
                "price": "0",
                "unit": "Units"
              }
            ]
          }
        ],
        "type": "ConfigurableUpfrontPricingTerm"
      }
    }
  ]
}

Contoh RequestedTerm payload untukConfigurableUpfrontPricingTerm:

{
  "id": "term-43ab7a2445f89dfcb7e1a6a81c92fe08c124125ffad126bea5e5b7915c065166",
  "configuration": {
    "configurableUpfrontPricingTermConfiguration": {
      "selectorValue": "P12M",
      "dimensions": [
        {
          "dimensionKey": "AdminUsers",
          "dimensionValue": 5
        },
        {
          "dimensionKey": "ReadOnlyUsers",
          "dimensionValue": 10
        }
      ]
    }
  }
}

RenewalTermConfiguration

Contoh RequestedTerm payload untukRenewalTerm:

{
  "id": "term-ffcc0100ce0c5468426dc07d0b05cff09ab8447640108d9c95ce1591f0949738",
  "configuration": {
    "renewalTermConfiguration": {
      "enableAutoRenew": false
    }
  }
}

VariablePaymentTermConfiguration

Contoh RequestedTerm payload untukVariablePaymentTerm:

{
  "id": "term-9ab34376c51cd5b4dc995aa0f410b657d58bd577b3f09b34d38afb6964aaaf12",
  "configuration": {
    "variablePaymentTermConfiguration": {
      "paymentRequestApprovalStrategy": "AUTO_APPROVE_ON_EXPIRATION",
      "expirationDuration": "P10D"
    }
  }
}

Menerima penawaran

Pertama, buat kutipan seperti yang dijelaskan dalamHasilkan penawaran. Kemudian, gunakan AcceptAgreementRequest untuk menerima penawaran dan membuat perjanjian. Anda harus menelepon AcceptAgreementRequest sebelum permintaan perjanjian berakhir. Anda dapat secara opsional mengaitkan nomor pesanan pembelian selama penerimaan.

# Use chargeId from CreateAgreementRequest response
response = client.accept_agreement_request(
    agreementRequestId='agrq-abc123',
    purchaseOrders=[
        {
            'chargeId': 'charge-xyz',  # From chargeSummary.expectedCharges[].id
            'purchaseOrderReference': 'PO-2024-001'
        }
    ]
)

print(f"Agreement ID: {response['agreementId']}")

Ganti perjanjian yang ada

Membangun CreateAgreementRequest seperti yang dijelaskan dalamHasilkan penawaran, tetapi diatur intent ke REPLACE dan menyediakan sourceAgreementIdentifier dengan perjanjian untuk menggantikan. Kemudian hubungi AcceptAgreementRequest untuk menyelesaikan penggantian.

response = client.create_agreement_request(
    agreementProposalIdentifier='at-edhtjnbilupjv3xqbphtom77y',
    intent='REPLACE',
    sourceAgreementIdentifier='agmt-existing123'
)

print(f"Agreement Request ID: {response['agreementRequestId']}")

Mengubah perjanjian yang ada

Untuk mengubah konfigurasi istilah pada perjanjian yang ada, tetapkan intent ke AMEND dan sediakansourceAgreementIdentifier. Tidak seperti perjanjian baru, tidak agreementProposalIdentifier diperlukan. Hanya sertakan istilah yang konfigurasinya ingin Anda ubah. Kemudian hubungi AcceptAgreementRequest untuk menerapkan amandemen.

response = client.create_agreement_request(
    intent='AMEND',
    sourceAgreementIdentifier='agmt-existing123',
    requestedTerms=[
        {
            'id': 'term-configurable-pricing-789',
            'configuration': {
                'configurableUpfrontPricingTermConfiguration': {
                    'selectorValue': 'P12M',
                    'dimensions': [
                        {'dimensionKey': 'Users', 'dimensionValue': 100}
                    ]
                }
            }
        }
    ]
)

print(f"Agreement Request ID: {response['agreementRequestId']}")

Mengaktifkan atau menonaktifkan perpanjangan otomatis

Gunakan CreateAgreementRequest dengan AMEND maksud untuk mengaktifkan perpanjangan otomatis.

response = client.create_agreement_request(
    intent='AMEND',
    sourceAgreementIdentifier='agmt-existing123',
    requestedTerms=[
        {
            'id': 'term-renewal-456',
            'configuration': {
                'renewalTermConfiguration': {'enableAutoRenew': True}
            }
        }
    ]
)

print(f"Agreement Request ID: {response['agreementRequestId']}")

Batalkan perjanjian

Gunakan CancelAgreement untuk membatalkan perjanjian penggunaan. Untuk jenis perjanjian lainnya, pembeli harus menghubungi penjual untuk memulai pembatalan.

client.cancel_agreement(
    agreementId='agmt-abc123'
)

Perjanjian pencarian

Gunakan SearchAgreements untuk mencari di semua perjanjian yang Anda ikuti sebagai akseptor. Pencarian mengembalikan daftar perjanjian dengan informasi perjanjian dasar.

response = client.search_agreements(
    catalog='AWSMarketplace',
    filters=[
        {'name': 'PartyType', 'values': ['Acceptor']},
        {'name': 'AgreementType', 'values': ['PurchaseAgreement']},
        {'name': 'Status', 'values': ['ACTIVE']}
    ]
)

for agmt in response['agreementViewSummaries']:
    print(f"  {agmt['agreementId']}: {agmt['status']}")

Jelaskan perjanjian

Gunakan DescribeAgreement untuk melihat detail tentang perjanjian, seperti pengusul, akseptor, tanggal mulai, dan tanggal akhir.

response = client.describe_agreement(
    agreementId='agmt-abc123'
)

print(f"Status: {response['status']}")
print(f"Start: {response['startTime']}")
print(f"End: {response['endTime']}")

Dapatkan ketentuan perjanjian

Gunakan GetAgreementTerms untuk mendapatkan rincian tentang persyaratan dalam perjanjian yang Anda ikuti sebagai akseptor.

response = client.get_agreement_terms(
    agreementId='agmt-abc123'
)

for term in response['acceptedTerms']:
    print(f"  Term: {term}")

Dapatkan hak perjanjian

Gunakan GetAgreementEntitlements untuk mendapatkan pandangan tingkat kesepakatan tentang status dan rincian hak yang terkait dengan perjanjian Anda.

response = client.get_agreement_entitlements(
    agreementId='agmt-abc123'
)

for ent in response['agreementEntitlements']:
    print(f"  {ent['resource']}: {ent['status']}")

Dapatkan token pendaftaran

Gunakan GetAgreementEntitlements untuk mendapatkan token pendaftaran. Token berumur pendek ini (berlaku selama 30 menit) diperlukan oleh akseptor untuk membuat akun dengan pengusul. Saat ini hanya berlaku untuk perjanjian pembelian SaaS.

response = client.get_agreement_entitlements(
    agreementId='agmt-abc123'
)

for ent in response['agreementEntitlements']:
    if 'registrationToken' in ent:
        print(f"Registration Token: {ent['registrationToken']}")
        # Token is valid for 30 minutes

Daftar biaya perjanjian

Gunakan ListAgreementCharges untuk melihat biaya dan detail pesanan pembelian yang terkait dengan perjanjian Anda.

response = client.list_agreement_charges(
    agreementId='agmt-abc123'
)

for charge in response['items']:
    print(f"  {charge['id']} (rev {charge['revision']}): ${charge['amount']}")
    print(f"  PO: {charge.get('purchaseOrderReference', 'N/A')}")

Perbarui pesanan pembelian

Gunakan UpdatePurchaseOrders untuk menambahkan nomor pesanan pembelian setelah berlangganan produk. Gunakan chargeId dan chargeRevision dari Daftar biaya perjanjian respon. Setelah pesanan pembelian dikaitkan dengan biaya, faktur yang dihasilkan untuk biaya itu termasuk nomor pesanan pembelian.

client.update_purchase_orders(
    agreementId='agmt-abc123',
    purchaseOrders=[
        {
            'chargeId': 'charge-xyz',
            'chargeRevision': 1,
            'purchaseOrderReference': 'PO-2024-001'
        }
    ]
)

Daftar permintaan pembatalan

Gunakan ListAgreementCancellationRequests untuk mencantumkan semua permintaan pembatalan untuk perjanjian yang Anda ikuti. Anda dapat memfilter berdasarkan perjanjian, status, dan kriteria lainnya.

response = client.list_agreement_cancellation_requests(
    partyType='Acceptor',
    agreementId='agmt-abc123'
)

for req in response['agreementCancellationRequests']:
    print(f"  {req['agreementCancellationRequestId']}: {req['status']}")

Dapatkan detail permintaan pembatalan

Gunakan GetAgreementCancellationRequest untuk mengambil informasi terperinci tentang permintaan pembatalan tertentu, termasuk status, stempel waktu, dan kode alasan.

response = client.get_agreement_cancellation_request(
    agreementId='agmt-abc123',
    agreementCancellationRequestId='acr-abc123'
)

print(f"Status: {response['status']}")
print(f"Reason: {response['reasonCode']}")

Menerima permintaan pembatalan

Gunakan AcceptAgreementCancellationRequest untuk menyetujui permintaan pembatalan yang diprakarsai oleh penjual. Setelah persetujuan, alur kerja pembatalan perjanjian dijalankan secara asinkron. Anda juga memerlukan CancelAgreement izin karena menyetujui permintaan pembatalan menyebabkan pembatalan perjanjian.

client.accept_agreement_cancellation_request(
    agreementId='agmt-abc123',
    agreementCancellationRequestId='acr-abc123'
)

Tolak permintaan pembatalan

Gunakan RejectAgreementCancellationRequest untuk menolak permintaan pembatalan yang diprakarsai oleh penjual. Setelah penolakan, perjanjian tetap aktif dan penjual dapat membuat permintaan pembatalan baru jika diperlukan.

client.reject_agreement_cancellation_request(
    agreementId='agmt-abc123',
    agreementCancellationRequestId='acr-abc123'
)

Daftar permintaan pembayaran

Gunakan ListAgreementPaymentRequests untuk mencantumkan semua permintaan pembayaran untuk perjanjian yang Anda ikuti. Anda dapat memfilter berdasarkan perjanjian, status, dan kriteria lainnya.

response = client.list_agreement_payment_requests(
    partyType='Acceptor',
    agreementId='agmt-abc123'
)

for req in response['agreementPaymentRequests']:
    print(f"  {req['agreementPaymentRequestId']}: {req['status']}")

Dapatkan detail permintaan pembayaran

Gunakan GetAgreementPaymentRequest untuk mengambil informasi terperinci tentang permintaan pembayaran tertentu, termasuk status, stempel waktu, dan biaya terkait.

response = client.get_agreement_payment_request(
    paymentRequestId='apr-abc123',
    agreementId='agmt-abc123'
)

print(f"Status: {response['status']}")
print(f"Amount: ${response['amount']}")

Menerima permintaan pembayaran

Gunakan AcceptAgreementPaymentRequest untuk menyetujui permintaan pembayaran yang diprakarsai oleh penjual untuk perjanjian aktif.

client.accept_agreement_payment_request(
    paymentRequestId='apr-abc123',
    agreementId='agmt-abc123'
)

Tolak permintaan pembayaran

Gunakan RejectAgreementPaymentRequest untuk menolak permintaan pembayaran yang diprakarsai oleh penjual. Setelah penolakan, penjual dapat membuat permintaan pembayaran baru jika diperlukan.

client.reject_agreement_payment_request(
    paymentRequestId='apr-abc123',
    agreementId='agmt-abc123'
)