L'AWS Marketplace API Reference è stato ristrutturato. Per ulteriori informazioni sulle operazioni API supportate, consulta l'AWS Marketplace API Reference.

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Lavora con l'API Agreement come acquirente

Un accordo è un documento che vincola due parti, tra cui il proponente e l'accettante (in genere, l'acquirente) e definisce i termini e le condizioni applicabili tra di esse.

L'acquirente crea un AgreementRequest, che genera un preventivo. Questo preventivo include tutte le informazioni pertinenti, come le spese stimate che verranno sostenute nel corso della durata del contratto, fondamentali per la decisione di acquisto dell'acquirente. Se l'acquirente è soddisfatto del preventivo, può accettarlo AgreementRequest prima della scadenza. L'accordo viene creato dopo l'accettazione del AgreementRequest. Durante questo processo, l'amministratore o la persona dell'acquirente possono associare l'ordine di acquisto agli addebiti. Infine, in base ai termini e alle condizioni del contratto attivo, all'acquirente viene emessa una fattura e viene concessa una licenza per l'utilizzo del prodotto.

Prerequisiti: scopri prodotti e offerte

Prima di creare un accordo, utilizza l'API AWS Marketplace Discovery per scoprire il prodotto e ottenere agreementProposalId i pricingModel dettagli e i termini necessari per creare un. CreateAgreementRequest

Per informazioni dettagliate sulla scoperta di prodotti e prezzi, consultaScopri prodotti e prezzi.

Un accettatore può eseguire le seguenti attività utilizzando questa API:

Genera un preventivo

Utilizza CreateAgreementRequest per generare un preventivo. È necessario fornire:

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']}")

Costruire RequestedTerms

Per costruirerequestedTerms, devi determinare due cose:

Termini richiesti per modello di prezzo

Il pricingModel.PricingModel campo nella GetOfferrisposta determina quali termini devono essere inclusi nel tuoCreateAgreementRequest.

I seguenti termini devono essere inclusi in ogni contratto quando sono presenti nell'offerta: LegalTermSupportTerm,ValidityTerm, eRenewalTerm.

CONTRATTO

Tutti i termini restituiti da GetOfferTermssono obbligatori in un unico documentoCreateAgreementRequest.

UTILIZZO

La creazione del contratto dipende dai termini presenti nell'offerta:

BYOL

Accetta ByolPricingTerm insieme ai termini obbligatori.

Configurazioni dei termini

La maggior parte dei termini richiede solo il moduloid. GetOfferTerms I seguenti tipi di termine richiedono un documento fornito dall'acquirente configuration in aggiunta a: id

ConfigurableUpfrontPricingTermConfiguration

Utilizza l'esempio seguente per individuare i valori necessari perConfigurableUpfrontPricingTermConfiguration.

Esempio GetOfferTerms di risposta:

{
  "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"
      }
    }
  ]
}

Esempio di RequestedTerm payload per: ConfigurableUpfrontPricingTerm

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

RenewalTermConfiguration

Esempio di RequestedTerm payload per: RenewalTerm

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

VariablePaymentTermConfiguration

RequestedTermPayload di esempio perVariablePaymentTerm:

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

Accetta un'offerta

Innanzitutto, genera un preventivo come descritto inGenera un preventivo. Quindi, utilizza AcceptAgreementRequest per accettare il preventivo e creare l'accordo. È necessario chiamare AcceptAgreementRequest prima della scadenza della richiesta di contratto. Facoltativamente, è possibile associare un numero d'ordine di acquisto durante l'accettazione.

# 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']}")

Sostituire un contratto esistente

Costruisci un accordo CreateAgreementRequest come descritto inGenera un preventivo, ma imposta intent REPLACE e fornisci l'sourceAgreementIdentifieraccordo da sostituire. Quindi chiama AcceptAgreementRequest per completare la sostituzione.

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

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

Modificare un accordo esistente

Per modificare la configurazione dei termini su un accordo esistente, imposta intent AMEND e forniscisourceAgreementIdentifier. A differenza di un nuovo accordo, non agreementProposalIdentifier è necessario. Includi solo i termini di cui desideri modificare la configurazione. Quindi chiama AcceptAgreementRequest per applicare l'emendamento.

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']}")

Attivare o disattivare il rinnovo automatico

Utilizzare CreateAgreementRequest con l'AMENDintento di attivare il rinnovo automatico.

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']}")

Annullare un contratto

Utilizzare CancelAgreement per annullare un contratto di utilizzo. Per altri tipi di contratto, l'acquirente deve contattare il venditore per avviare l'annullamento.

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

Cerca accordi

SearchAgreementsUtilizzalo per cercare tra tutti gli accordi a cui partecipi come accettatore. La ricerca restituisce un elenco di accordi con informazioni di base sugli accordi.

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']}")

Descrivi un accordo

DescribeAgreementDa utilizzare per visualizzare i dettagli di un accordo, ad esempio il proponente, l'accettante, la data di inizio e la data di fine.

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

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

Ottieni i termini del contratto

GetAgreementTermsUtilizzalo per ottenere dettagli sui termini di un accordo a cui partecipi in qualità di accettatore.

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

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

Ottieni i diritti contrattuali

GetAgreementEntitlementsUtilizzalo per ottenere una visione a livello di contratto dello stato e dei dettagli dei diritti legati al contratto.

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

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

Ottieni un token di registrazione

GetAgreementEntitlementsUtilizzalo per ottenere un token di registrazione. Questo token di breve durata (valido per 30 minuti) è necessario agli accettanti per creare un account con i proponenti. Attualmente applicabile solo per i contratti di acquisto 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

Elenca i costi del contratto

Utilizzalo ListAgreementCharges per visualizzare gli addebiti e i dettagli degli ordini di acquisto associati al contratto.

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')}")

Aggiornare gli ordini di acquisto

Utilizzato UpdatePurchaseOrders per aggiungere un numero d'ordine di acquisto dopo l'iscrizione a un prodotto. Usa l'chargeIde chargeRevision della Elenca i costi del contratto risposta. Una volta che un ordine di acquisto è associato a un addebito, la fattura generata per tale addebito include il numero dell'ordine di acquisto.

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

Elenca le richieste di cancellazione

Utilizza ListAgreementCancellationRequests per elencare tutte le richieste di cancellazione per gli accordi a cui partecipi. Puoi filtrare per contratto, stato e altri criteri.

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

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

Ottieni i dettagli della richiesta di annullamento

GetAgreementCancellationRequestUtilizzalo per recuperare informazioni dettagliate su una specifica richiesta di cancellazione, inclusi lo stato, i timestamp e i codici motivo.

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

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

Accetta una richiesta di cancellazione

Utilizzato AcceptAgreementCancellationRequest per approvare una richiesta di annullamento avviata dal venditore. Dopo l'approvazione, il flusso di lavoro di annullamento del contratto viene eseguito in modo asincrono. È inoltre necessaria CancelAgreement l'autorizzazione perché l'approvazione della richiesta di annullamento comporta la cancellazione dell'accordo.

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

Rifiuta una richiesta di cancellazione

Utilizzato RejectAgreementCancellationRequest per rifiutare una richiesta di annullamento avviata dal venditore. Dopo il rifiuto, l'accordo rimane attivo e il venditore può creare una nuova richiesta di annullamento, se necessario.

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

Elenca le richieste di pagamento

Utilizza ListAgreementPaymentRequests per elencare tutte le richieste di pagamento per gli accordi a cui partecipi. Puoi filtrare per contratto, stato e altri criteri.

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

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

Ottieni i dettagli della richiesta di pagamento

Consente GetAgreementPaymentRequest di recuperare informazioni dettagliate su una specifica richiesta di pagamento, tra cui lo stato, la data e l'ora e gli addebiti associati.

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

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

Accetta una richiesta di pagamento

Utilizzato AcceptAgreementPaymentRequest per approvare una richiesta di pagamento avviata dal venditore per un contratto attivo.

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

Rifiuta una richiesta di pagamento

Utilizzato RejectAgreementPaymentRequest per rifiutare una richiesta di pagamento avviata dal venditore. Dopo il rifiuto, il venditore può creare una nuova richiesta di pagamento, se necessario.

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