Se reestructuró la referencia de la API de AWS Marketplace. Para obtener más información sobre las operaciones de API compatibles, consulte la referencia de API de AWS Marketplace.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Trabaja con la API de acuerdos como comprador

Un acuerdo es un documento que vincula a dos partes, incluido el proponente y el aceptante (normalmente, el comprador), y en el que se definen los términos y condiciones aplicables entre ellas.

El comprador crea un AgreementRequest, que genera un presupuesto. Este presupuesto incluye toda la información relevante, como los gastos estimados en los que incurrirá durante la vigencia del acuerdo, lo cual es fundamental para la decisión de compra del comprador. Si el comprador está satisfecho con el presupuesto, puede aceptarlo AgreementRequest antes de que caduque. El Acuerdo se crea tras la aceptación del AgreementRequest. Durante este proceso, el administrador del comprador o la persona compradora pueden asociar la orden de compra a los cargos. Por último, según los términos y condiciones del acuerdo activo, se factura al comprador y se le concede una licencia de uso del producto.

Requisitos previos: Descubra productos y ofertas

Antes de crear un acuerdo, utilice la API AWS Marketplace Discovery para descubrir el producto y obtener los agreementProposalId detalles y condiciones necesarios para crear un CreateAgreementRequest acuerdo. pricingModel

Para obtener información detallada sobre cómo descubrir productos y precios, consulteDescubra los productos y los precios.

Un aceptador puede realizar las siguientes tareas mediante esta API:

Genera una cotización

Se utiliza CreateAgreementRequest para generar una cotización. Debe proporcionar:

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

Construyendo los términos solicitados

Para construirrequestedTerms, necesitas determinar dos cosas:

Términos obligatorios por modelo de precios

El pricingModel.PricingModel campo de la GetOfferrespuesta determina qué términos deben incluirse en suCreateAgreementRequest.

Los siguientes términos deben incluirse en cada acuerdo cuando estén presentes en la oferta: LegalTermSupportTerm,ValidityTerm, yRenewalTerm.

CONTRATO

Todos los términos devueltos por GetOfferTermsson obligatorios en uno soloCreateAgreementRequest.

USO

La creación del acuerdo depende de los términos presentes en la oferta:

BYOL

Acepte ByolPricingTerm junto con las condiciones obligatorias.

Configuraciones de términos

La mayoría de los términos solo requieren el id formulario GetOfferTerms. Los siguientes tipos de términos requieren que el comprador los suministre configuration además del: id

ConfigurableUpfrontPricingTermConfiguration

Usa el siguiente ejemplo para localizar los valores necesariosConfigurableUpfrontPricingTermConfiguration.

Ejemplo de GetOfferTerms respuesta:

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

Ejemplo de RequestedTerm carga útil paraConfigurableUpfrontPricingTerm:

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

RenewalTermConfiguration

Ejemplo de carga RequestedTerm útil para: RenewalTerm

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

VariablePaymentTermConfiguration

Ejemplo de RequestedTerm carga útil paraVariablePaymentTerm:

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

Acepta una oferta

En primer lugar, genere una cotización como se describe enGenera una cotización. A continuación, utilice AcceptAgreementRequest para aceptar la cotización y crear el acuerdo. Debe llamar AcceptAgreementRequest antes de que caduque la solicitud de acuerdo. Si lo desea, puede asociar un número de pedido de compra durante la aceptación.

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

Sustituya un acuerdo existente

Cree un acuerdo CreateAgreementRequest como se describe enGenera una cotización, pero intent configúrelo REPLACE e sourceAgreementIdentifier indíquelo junto con el acuerdo que desee reemplazar. Luego llame AcceptAgreementRequest para completar el reemplazo.

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

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

Modificar un acuerdo existente

Para modificar la configuración temporal de un acuerdo existente, intent configúrelo en AMEND y proporcionesourceAgreementIdentifier. A diferencia de un acuerdo nuevo, no agreementProposalIdentifier es necesario. Incluya únicamente los términos cuya configuración desee cambiar. A continuación, llame AcceptAgreementRequest para aplicar la modificación.

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

Activar o desactivar la renovación automática

Úselo CreateAgreementRequest con la AMEND intención de activar la renovación 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 un acuerdo

Se utiliza CancelAgreement para cancelar un acuerdo de uso. Para otros tipos de acuerdos, el comprador debe ponerse en contacto con el vendedor para iniciar la cancelación.

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

Busca acuerdos

Úselo SearchAgreements para buscar en todos los acuerdos en los que participe como aceptante. La búsqueda devuelve una lista de acuerdos con información básica sobre los acuerdos.

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

Describa un acuerdo

Se utiliza DescribeAgreement para ver los detalles de un acuerdo, como el proponente, el aceptante, la fecha de inicio y la fecha de finalización.

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

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

Obtenga las condiciones del acuerdo

Úselo GetAgreementTerms para obtener detalles sobre los términos de un acuerdo en el que participe como aceptante.

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

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

Obtenga los derechos de un acuerdo

Úselo GetAgreementEntitlements para obtener una visión a nivel de acuerdo del estado y los detalles de los derechos vinculados a su acuerdo.

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

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

Obtén un token de registro

GetAgreementEntitlementsÚselo para obtener un token de registro. Los aceptadores necesitan este token de corta duración (válido durante 30 minutos) para abrir una cuenta con los proponentes. Actualmente solo se aplica a los acuerdos 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

Enumere los cargos del acuerdo

ListAgreementChargesUtilícelo para ver los cargos y los detalles del pedido de compra asociados a su acuerdo.

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

Actualice las órdenes de compra

Se utiliza UpdatePurchaseOrders para añadir un número de pedido de compra después de suscribirse a un producto. Usa el chargeId y el resultado chargeRevision de la Enumere los cargos del acuerdo respuesta. Una vez que un pedido de compra está asociado a un cargo, la factura generada para ese cargo incluye el número del pedido de compra.

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

Enumere las solicitudes de cancelación

ListAgreementCancellationRequestsUtilícela para enumerar todas las solicitudes de cancelación de los acuerdos en los que participa. Puede filtrar por acuerdo, estado y otros criterios.

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

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

Obtén los detalles de la solicitud de cancelación

Se usa GetAgreementCancellationRequest para recuperar información detallada sobre una solicitud de cancelación específica, incluidos el estado, las marcas horarias y los 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']}")

Acepta una solicitud de cancelación

Se utiliza AcceptAgreementCancellationRequest para aprobar una solicitud de cancelación iniciada por el vendedor. Tras la aprobación, el flujo de trabajo de cancelación del acuerdo se ejecuta de forma asíncrona. También necesita CancelAgreement permiso porque la aprobación de la solicitud de cancelación implica la cancelación del acuerdo.

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

Rechazar una solicitud de cancelación

Se utiliza RejectAgreementCancellationRequest para rechazar una solicitud de cancelación iniciada por el vendedor. Tras el rechazo, el acuerdo permanece activo y el vendedor puede crear una nueva solicitud de cancelación si es necesario.

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

Enumere las solicitudes de pago

ListAgreementPaymentRequestsUtilícela para enumerar todas las solicitudes de pago de los acuerdos en los que participa. Puede filtrar por acuerdo, estado y otros criterios.

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

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

Obtenga los detalles de la solicitud de pago

Se usa GetAgreementPaymentRequest para recuperar información detallada sobre una solicitud de pago específica, incluidos el estado, las fechas y los cargos asociados.

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

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

Acepta una solicitud de pago

Se utiliza AcceptAgreementPaymentRequest para aprobar una solicitud de pago iniciada por el vendedor para un acuerdo activo.

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

Rechaza una solicitud de pago

Se utiliza RejectAgreementPaymentRequest para rechazar una solicitud de pago iniciada por el vendedor. Tras el rechazo, el vendedor puede crear una nueva solicitud de pago si es necesario.

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