A referência de API do AWS Marketplace foi reestruturada. Para obter mais informações sobre as operações de API suportadas, consulte a Referência de API do AWS Marketplace.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Trabalhe com a API do Contrato como comprador

Um contrato é um documento que vincula duas partes, incluindo o proponente e o aceitante (geralmente, o comprador) e define os termos e condições aplicáveis entre eles.

O comprador cria um AgreementRequest, que gera uma cotação. Essa cotação inclui todas as informações relevantes, como as cobranças estimadas que serão incorridas durante a vigência do contrato, o que é fundamental para a decisão de compra do comprador. Se o comprador estiver satisfeito com a cotação, ele poderá aceitá-la AgreementRequest antes que ela expire. O Contrato é criado após a aceitação do AgreementRequest. Durante esse processo, o administrador do comprador ou a persona do comprador podem associar o pedido de compra às cobranças. Finalmente, com base nos termos e condições do contrato ativo, o comprador recebe uma fatura e recebe uma Licença para usar o produto.

Pré-requisitos: Descubra produtos e ofertas

Antes de criar um contrato, use a API AWS Marketplace Discovery para descobrir o produto e obter os agreementProposalId detalhes do prazo e do prazo necessários para construir umCreateAgreementRequest. pricingModel

Para obter informações detalhadas sobre como descobrir produtos e preços, consulteDescubra produtos e preços.

Um aceitador pode realizar as seguintes tarefas usando essa API:

Gere uma cotação

Use CreateAgreementRequest para gerar uma cotação. É necessário fornecer:

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

Construindo os termos solicitados

Para construirrequestedTerms, você precisa determinar duas coisas:

Termos exigidos por modelo de preços

O pricingModel.PricingModel campo na GetOfferresposta determina quais termos devem ser incluídos em suaCreateAgreementRequest.

Os seguintes termos devem ser incluídos em cada contrato quando presentes na oferta: LegalTermSupportTerm,ValidityTerm,, RenewalTerm e.

CONTRATO

Todos os termos devolvidos por GetOfferTermssão exigidos em um únicoCreateAgreementRequest.

USO

A criação do contrato depende dos termos presentes na oferta:

BYOL

Aceite ByolPricingTerm junto com os termos obrigatórios.

Configurações de termos

A maioria dos termos exige apenas o id formulário GetOfferTerms. Os seguintes tipos de termos exigem um fornecimento pelo comprador, configuration além do: id

ConfigurableUpfrontPricingTermConfiguration

Use o exemplo abaixo para localizar os valores necessários paraConfigurableUpfrontPricingTermConfiguration.

Exemplo de GetOfferTerms resposta:

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

Exemplo de RequestedTerm carga útil paraConfigurableUpfrontPricingTerm:

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

RenewalTermConfiguration

Exemplo de RequestedTerm carga útil paraRenewalTerm:

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

VariablePaymentTermConfiguration

Exemplo de RequestedTerm carga útil paraVariablePaymentTerm:

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

Aceite uma oferta

Primeiro, gere uma cotação conforme descrito emGere uma cotação. Em seguida, use AcceptAgreementRequest para aceitar a cotação e criar o contrato. Você deve ligar AcceptAgreementRequest antes que a solicitação de contrato expire. Opcionalmente, você pode associar um número de ordem de compra durante a aceitação.

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

Substituir um contrato existente

Construa um CreateAgreementRequest conforme descrito emGere uma cotação, mas intent defina REPLACE e sourceAgreementIdentifier forneça o contrato a ser substituído. Em seguida, ligue AcceptAgreementRequest para concluir a substituição.

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

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

Alterar um acordo existente

Para modificar a configuração do prazo em um contrato existente, intent defina como AMEND e forneçasourceAgreementIdentifier. Ao contrário de um novo acordo, não agreementProposalIdentifier é necessário. Inclua somente os termos cuja configuração você deseja alterar. Em seguida, ligue AcceptAgreementRequest para aplicar a emenda.

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

Ativar ou desativar a renovação automática

Use CreateAgreementRequest com a AMEND intenção de ativar a renovação automática.

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

Cancelar um contrato

Use CancelAgreement para cancelar um contrato de uso. Para outros tipos de contrato, o comprador deve entrar em contato com o vendedor para iniciar o cancelamento.

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

Contratos de pesquisa

Use SearchAgreements para pesquisar todos os contratos dos quais você participa como aceitante. A pesquisa retorna uma lista de contratos com informações básicas do contrato.

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

Descreva um contrato

Use DescribeAgreement para visualizar detalhes sobre um contrato, como o proponente, o aceitante, a data de início e a data de término.

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

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

Obtenha os termos do contrato

Use GetAgreementTerms para obter detalhes sobre os termos de um contrato do qual você participa como aceitante.

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

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

Obtenha direitos de contrato

Use GetAgreementEntitlements para obter uma visão em nível de contrato do status e dos detalhes dos direitos vinculados ao seu contrato.

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

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

Obtenha um token de registro

Use GetAgreementEntitlements para obter um token de registro. Esse token de curta duração (válido por 30 minutos) é exigido pelos aceitantes para configurar uma conta com os proponentes. Atualmente aplicável apenas para contratos de compra de 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

Listar cobranças do contrato

Use ListAgreementCharges para visualizar as cobranças e os detalhes do pedido de compra associados ao seu contrato.

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

Atualizar pedidos de compra

Use UpdatePurchaseOrders para adicionar um número de pedido de compra depois de assinar um produto. Use o chargeId e chargeRevision da Listar cobranças do contrato resposta. Quando uma ordem de compra é associada a uma cobrança, a fatura gerada para essa cobrança inclui o número da ordem de compra.

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

Listar solicitações de cancelamento

Use ListAgreementCancellationRequests para listar todas as solicitações de cancelamento dos contratos dos quais você participa. Você pode filtrar por contrato, status e outros critérios.

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

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

Obtenha detalhes da solicitação de cancelamento

Use GetAgreementCancellationRequest para recuperar informações detalhadas sobre uma solicitação de cancelamento específica, incluindo status, registros de data e hora e códigos de motivo.

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

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

Aceitar uma solicitação de cancelamento

Use AcceptAgreementCancellationRequest para aprovar uma solicitação de cancelamento iniciada pelo vendedor. Após a aprovação, o fluxo de trabalho de cancelamento do contrato é executado de forma assíncrona. Você também precisa de CancelAgreement permissão porque a aprovação da solicitação de cancelamento leva ao cancelamento do contrato.

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

Rejeitar uma solicitação de cancelamento

Use RejectAgreementCancellationRequest para rejeitar uma solicitação de cancelamento iniciada pelo vendedor. Após a rejeição, o contrato permanece ativo e o vendedor pode criar uma nova solicitação de cancelamento, se necessário.

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

Listar solicitações de pagamento

Use ListAgreementPaymentRequests para listar todas as solicitações de pagamento dos contratos dos quais você participa. Você pode filtrar por contrato, status e outros critérios.

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

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

Obtenha detalhes da solicitação de pagamento

Use GetAgreementPaymentRequest para recuperar informações detalhadas sobre uma solicitação de pagamento específica, incluindo status, registros de data e hora e cobranças associadas.

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

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

Aceitar uma solicitação de pagamento

Use AcceptAgreementPaymentRequest para aprovar uma solicitação de pagamento iniciada pelo vendedor para um contrato ativo.

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

Rejeitar uma solicitação de pagamento

Use RejectAgreementPaymentRequest para rejeitar uma solicitação de pagamento iniciada pelo vendedor. Após a rejeição, o vendedor pode criar uma nova solicitação de pagamento, se necessário.

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