Google Pay ile fiziksel işlemler oluşturma

Bu rehber, fiziksel ürünlerle ilgili işlemleri içeren ve ödeme için Google Pay'i kullanan bir Actions projesi geliştirme sürecinde size yol gösterir.

İşlem akışı

Actions projeniz satıcı tarafından yönetilen ödemeleri kullanarak fiziksel işlemleri gerçekleştirdiğinde aşağıdaki akışı kullanır:

  1. Bilgi toplama (isteğe bağlı) - İşleminizin niteliğine bağlı olarak, görüşmenin başında kullanıcıdan aşağıdaki bilgileri toplamak isteyebilirsiniz:
    1. İşlem gereksinimlerini doğrulayın: Görüşmenin başında, kullanıcının işlem yapmak için gerekli koşulları (ör. alışveriş sepetini oluşturmadan önce ödeme bilgilerinin doğru şekilde yapılandırılması ve kullanılabilir olması) karşıladığını doğrulayın.
    2. Teslimat adresi iste: İşlem için teslimat adresi gerekiyorsa kullanıcıdan bir adres toplayın.
  2. Siparişi oluşturun: Kullanıcıyı satın almak istediği öğeleri seçtiği bir "alışveriş sepeti düzenlemesi" boyunca yönlendirin.
  3. Sipariş önerin - Alışveriş sepeti tamamlandığında, doğruluğu onaylayabilmesi için kullanıcıya siparişi önerin. Sipariş onaylanırsa sipariş ayrıntılarını ve ödeme jetonunu içeren bir yanıt alırsınız.
  4. Siparişi tamamlama ve makbuz gönderme - Sipariş onaylandıktan sonra envanter takibi veya diğer sipariş karşılama hizmetlerini güncelleyin ve kullanıcıya makbuz gönderin.
  5. Sipariş güncellemeleri gönderme - Sipariş karşılama süresi boyunca, Siparişler API'sine PATCH istekleri göndererek kullanıcıya sipariş güncellemeleri sağlayın.

Kısıtlamalar ve inceleme kuralları

İşlem içeren işlemler için ek politikaların geçerli olduğunu unutmayın. İşlem içeren işlemleri incelememiz altı haftayı bulabileceğinden, yayın planınızı planlarken bu süreyi de hesaba katın. İnceleme sürecini kolaylaştırmak için İşleminizi incelemeye göndermeden önce işlemlerle ilgili politikalara ve kurallara uyduğunuzdan emin olun.

Yalnızca aşağıdaki ülkelerde fiziksel ürün satan İşlemleri dağıtabilirsiniz:

Avustralya
Brezilya
Kanada
Endonezya
Japonya
Meksika
Rusya
Singapur
Tayland
Türkiye
Birleşik Krallık
Amerika Birleşik Devletleri

Projenizi oluşturun

İşlem sohbetlerinin kapsamlı örnekleri için Node.js işlem örneğini inceleyin.

Kurulum

İşleminizi oluştururken Actions Console'da işlem gerçekleştirmek istediğinizi belirtmeniz gerekir.

Projenizi ve sipariş karşılamanızı ayarlamak için aşağıdakileri yapın:

  1. Yeni proje oluşturun veya mevcut bir projeyi içe aktarın.
  2. Dağıtma > Dizin bilgileri'ne gidin.
  3. Ek bilgiler > İşlemler bölümünün altında "İşlemleriniz fiziksel ürünlerle ilgili işlemler yapmak için Transaction API'yi kullanıyor mu?" yazan kutuyu işaretleyin.

1. Bilgi toplama (isteğe bağlı)

1a. İşlem şartlarını doğrulayın (isteğe bağlı)

Kullanıcı bir satın alma işlemi yapmak istediğini belirtir belirtmez, kullanıcının bir işlem gerçekleştirebileceğinden emin olmak için bunu kontrol etmelisiniz. Örneğin, çağrıldığında İşleminiz "Ayakkabı siparişi vermek mi yoksa hesap bakiyenizi kontrol etmek mi istersiniz?" sorusunu sorabilir. Kullanıcı "ayakkabı sipariş et" derse devam edebileceğinden emin olmalı ve işleme devam etmesini engelleyen ayarları düzeltme fırsatı sunmalısınız. Bunun için işlem gereksinimleri kontrolü gerçekleştiren bir sahneye geçiş yapmanız gerekir.

İşlem Koşulları Kontrolü sahnesi oluşturma
  1. Sahneler sekmesinden TransactionRequirementsCheck adlı yeni bir Sahne ekleyin.
  2. Slot doldurma bölümünde, yeni bir alan eklemek için + simgesini tıklayın.
  3. Tür seçin'in altında alan türü olarak actions.type.TransactionRequirementsCheckResult'yi seçin.
  4. Alan adı alanında, alana TransactionRequirementsCheck adını girin.
  5. Alan değeri yazma işlevini özelleştir onay kutusunu işaretleyin (varsayılan olarak etkindir).
  6. Kaydet'i tıklayın.

İşlem gereksinimleri kontrolü aşağıdaki sonuçlardan biriyle sonuçlanır:

  • Şartlar karşılanırsa, oturum parametresi bir başarı koşulu ile ayarlanır ve kullanıcının siparişini oluşturma işlemine devam edebilirsiniz.
  • Koşullardan biri veya daha fazlası karşılanamazsa oturum parametresi bir hata koşuluyla ayarlanır. Bu durumda konuşmayı işlem deneyiminden uzaklaştırmalı veya sonlandırmalısınız.
    • Hata durumuyla sonuçlanan hatalar kullanıcı tarafından düzeltilebiliyorsa kullanıcıdan bu sorunları cihazında çözmesi istenir. Konuşma yalnızca sesli bir yüzeyde gerçekleşiyorsa konuşma kullanıcının telefonuna başlatılır.

İşlem Koşullarını İşleme Kontrol sonucu

  1. Sahneler sekmesinden, yeni oluşturduğunuz TransactionRequirementsCheck sahnesini seçin.
  2. Koşul bölümünde, yeni bir koşul eklemek için + simgesini tıklayın.
  3. Başarı koşulunu kontrol etmek için metin alanına aşağıdaki koşul söz dizimini girin:

    scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
    
  4. İmlecinizi yeni eklediğiniz koşulun üzerine getirin ve if scene.slots.status == "FINAL" koşulunun önüne yerleştirmek için yukarı oku tıklayın.

  5. İstemleri gönder'i etkinleştirin ve kullanıcıya bir işlem yapmaya hazır olduğunu bildiren basit bir istem sağlayın:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                You are ready to purchase physical goods.
    
  6. Transition (Geçiş) bölümünde başka bir sahne seçin. Kullanıcının görüşmeye devam etmesine ve işlem gerçekleştirmesine olanak tanıyın.

  7. Koşulu seçin else if scene.slots.status == "FINAL".

  8. İstemleri gönder'i etkinleştirin ve kullanıcıya bir işlem yapamayacağını bildiren basit bir istem sağlayın:

    candidates:
      - first_simple:
          variants:
            - speech: Transaction requirements check failed.
    
  9. Bir kullanıcı işlem yapamıyorsa görüşmeyi sonlandırmak için Geçiş bölümünde Görüşmeyi sonlandır'ı seçin.

Teslimat adresi isteyin

İşleminiz için bir kullanıcının teslimat adresi gerekiyorsa bu adresi kullanıcıdan istemeniz gerekir. Bu, toplam fiyatı, teslimat/teslim alma konumunu belirlemek veya kullanıcının hizmet bölgenizde bulunduğundan emin olmak için yararlı olabilir. Bunun için kullanıcıdan teslimat adresini isteyen bir sahneye geçiş yapmanız gerekir.

Teslimat Adresi Sahnesi Oluştur

  1. Sahneler sekmesinden DeliveryAddress adlı yeni bir sahne ekleyin.
  2. Slot doldurma bölümünde, yeni bir alan eklemek için + simgesini tıklayın.
  3. Tür seçin'in altında, alan türü olarak actions.type.DeliveryAddressValue'yi seçin.
  4. Alan adı alanında, alana TransactionDeliveryAddress adını girin.
  5. Alan değeri yazma işlevini özelleştir onay kutusunu işaretleyin (varsayılan olarak etkindir).
  6. Kaydet'i tıklayın.

Yuvayı yapılandırırken, Asistan'ın dize içeren bir adres alma isteğinin önüne geçmenize olanak tanıyan bir reason sağlayabilirsiniz.Varsayılan neden dizesi, "siparişin nereye gönderileceğini bilmek" şeklindedir. Bu nedenle Asistan, kullanıcıya "Siparişi nereye göndereceğini öğrenmek için teslimat adresinizi öğrenmem gerekiyor" diye sorabilir.

  • Ekranın bulunduğu yüzeylerde kullanıcı işlem için kullanmak istediği adresi seçer. Daha önce adres vermemişlerse yeni bir adres girebilirler.
  • Asistan, yalnızca ses kullanılan yüzeylerde kullanıcıdan işlem için varsayılan adresini paylaşmak için izin ister. Daha önce adres vermediyse görüşme girilmek üzere bir telefona yönlendirilir.

Teslimat Adresi sonucunu işlemek için aşağıdaki adımları uygulayın:

  1. Sahneler sekmesinden, yeni oluşturduğunuz DeliveryAddress sahnesini seçin.
  2. Koşul bölümünde, yeni bir koşul eklemek için + simgesini tıklayın.
  3. Başarı koşulunu kontrol etmek için metin alanına aşağıdaki koşul söz dizimini girin:

    scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"
    
  4. İmlecinizi yeni eklediğiniz koşulun üzerine getirin ve if scene.slots.status == "FINAL" koşulunun önüne yerleştirmek için yukarı oku tıklayın.

  5. İstem gönder'i etkinleştirin ve kullanıcıya adresini aldığınızı bildiren basit bir istem sağlayın:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Great! Your order will be delivered to
                $session.params.TransactionDeliveryAddress.location.postalAddress.locality
                $session.params.TransactionDeliveryAddress.location.postalAddress.administrativeArea
                $session.params.TransactionDeliveryAddress.location.postalAddress.regionCode
                $session.params.TransactionDeliveryAddress.location.postalAddress.postalCode
    
  6. Transition (Geçiş) bölümünde, kullanıcının görüşmeye devam edebilmesi için başka bir sahne seçin.

  7. else if scene.slots.status == "FINAL" koşulunu seçin.

  8. İstemleri gönder'i etkinleştirin ve kullanıcıya bir işlem yapamayacağını bildiren basit bir istem sağlayın:

    candidates:
      - first_simple:
          variants:
            - speech: I failed to get your delivery address.
    
  9. Bir kullanıcı işlem yapamıyorsa görüşmeyi sonlandırmak için Geçiş bölümünde Görüşmeyi sonlandır'ı seçin.

Siparişi oluşturmak

İhtiyacınız olan kullanıcı bilgilerini edindikten sonra, kullanıcıyı sipariş oluşturması için yönlendiren bir "alışveriş sepeti montajı" deneyimi oluşturursunuz. Her İşlemin alışveriş sepeti montaj akışı, ürün veya hizmete uygun şekilde biraz farklıdır.

En temel alışveriş sepeti montaj deneyimi, kullanıcının listeden ürün siparişine eklemek istediği öğeleri seçmesini içerir. Ancak konuşmayı, kullanıcı deneyimini kolaylaştıracak şekilde tasarlayabilirsiniz. Kullanıcının basit bir evet-hayır sorusuyla en son satın aldığı ürünü tekrar sipariş etmesini sağlayan bir alışveriş sepeti montaj deneyimi oluşturabilirsiniz. Ayrıca kullanıcıya en çok "öne çıkan" veya "önerilen" öğelerin bulunduğu bir bant ya da liste kartı sunabilirsiniz.

Kullanıcıya seçeneklerini görsel olarak sunmak için zengin yanıtlar kullanmanızı öneririz. Ancak sohbeti, kullanıcının yalnızca sesini kullanarak alışveriş sepetini oluşturabileceği şekilde tasarlamanızı öneririz. Bazı en iyi uygulamalar ve yüksek kaliteli alışveriş sepeti montaj deneyimlerine ilişkin örnekler için Tasarım yönergelerine bakın.

Sipariş oluşturma

Görüşmeniz boyunca, kullanıcının satın almak istediği öğeleri toplamanız ve ardından bir Order nesnesi oluşturmanız gerekir.

Order en azından aşağıdakileri içermelidir:

  • buyerInfo - Satın alma işlemini yapan kullanıcı hakkında bilgiler.
  • transactionMerchant - Siparişi sağlayan satıcıyla ilgili bilgiler.
  • contents - lineItems olarak listelenen siparişin gerçek içeriği.
  • priceAttributes - Siparişin indirimler ve vergiler dahil toplam maliyeti de dahil olmak üzere siparişle ilgili fiyatlandırma ayrıntıları.

Alışveriş sepetinizi oluşturmak için Order yanıt belgelerini inceleyin. Sıraya bağlı olarak farklı alanlar eklemeniz gerekebileceğini unutmayın.

Aşağıdaki örnek kod, isteğe bağlı alanlar da dahil olmak üzere tam siparişi gösterir:

const order = {
  createTime: '2019-09-24T18:00:00.877Z',
  lastUpdateTime: '2019-09-24T18:00:00.877Z',
  merchantOrderId: orderId, // A unique ID String for the order
  userVisibleOrderId: orderId,
  transactionMerchant: {
    id: 'http://www.example.com',
    name: 'Example Merchant',
  },
  contents: {
    lineItems: [
      {
        id: 'LINE_ITEM_ID',
        name: 'Pizza',
        description: 'A four cheese pizza.',
        priceAttributes: [
          {
            type: 'REGULAR',
            name: 'Item Price',
            state: 'ACTUAL',
            amount: {
              currencyCode: 'USD',
              amountInMicros: 8990000,
            },
            taxIncluded: true,
          },
          {
            type: 'TOTAL',
            name: 'Total Price',
            state: 'ACTUAL',
            amount: {
              currencyCode: 'USD',
              amountInMicros: 9990000,
            },
            taxIncluded: true,
          },
        ],
        notes: [
          'Extra cheese.',
        ],
        purchase: {
          quantity: 1,
          unitMeasure: {
            measure: 1,
            unit: 'POUND',
          },
          itemOptions: [
            {
              id: 'ITEM_OPTION_ID',
              name: 'Pepperoni',
              prices: [
                {
                  type: 'REGULAR',
                  state: 'ACTUAL',
                  name: 'Item Price',
                  amount: {
                    currencyCode: 'USD',
                    amountInMicros: 1000000,
                  },
                  taxIncluded: true,
                },
                {
                  type: 'TOTAL',
                  name: 'Total Price',
                  state: 'ACTUAL',
                  amount: {
                    currencyCode: 'USD',
                    amountInMicros: 1000000,
                  },
                  taxIncluded: true,
                },
              ],
              note: 'Extra pepperoni',
              quantity: 1,
              subOptions: [],
            },
          ],
        },
      },
    ],
  },
  buyerInfo: {
    email: 'janedoe@gmail.com',
    firstName: 'Jane',
    lastName: 'Doe',
    displayName: 'Jane Doe',
  },
  priceAttributes: [
    {
      type: 'SUBTOTAL',
      name: 'Subtotal',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 9990000,
      },
      taxIncluded: true,
    },
    {
      type: 'DELIVERY',
      name: 'Delivery',
      state: 'ACTUAL',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 2000000,
      },
      taxIncluded: true,
    },
    {
      type: 'TAX',
      name: 'Tax',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 3780000,
      },
      taxIncluded: true,
    },
    {
      type: 'TOTAL',
      name: 'Total Price',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 15770000,
      },
      taxIncluded: true,
    },
  ],
  followUpActions: [
    {
      type: 'VIEW_DETAILS',
      title: 'View details',
      openUrlAction: {
        url: 'http://example.com',
      },
    },
    {
      type: 'CALL',
      title: 'Call us',
      openUrlAction: {
        url: 'tel:+16501112222',
      },
    },
    {
      type: 'EMAIL',
      title: 'Email us',
      openUrlAction: {
        url: 'mailto:person@example.com',
      },
    },
  ],
  termsOfServiceUrl: 'http://www.example.com',
  note: 'Sale event',
  promotions: [
    {
      coupon: 'COUPON_CODE',
    },
  ],
  purchase: {
    status: 'CREATED',
    userVisibleStatusLabel: 'CREATED',
    type: 'FOOD',
    returnsInfo: {
      isReturnable: false,
      daysToReturn: 1,
      policyUrl: 'http://www.example.com',
    },
    fulfillmentInfo: {
      id: 'FULFILLMENT_SERVICE_ID',
      fulfillmentType: 'DELIVERY',
      expectedFulfillmentTime: {
        timeIso8601: '2019-09-25T18:00:00.877Z',
      },
      location: location,
      price: {
        type: 'REGULAR',
        name: 'Delivery Price',
        state: 'ACTUAL',
        amount: {
          currencyCode: 'USD',
          amountInMicros: 2000000,
        },
        taxIncluded: true,
      },
      fulfillmentContact: {
        email: 'johnjohnson@gmail.com',
        firstName: 'John',
        lastName: 'Johnson',
        displayName: 'John Johnson',
      },
    },
    purchaseLocationType: 'ONLINE_PURCHASE',
  },
};

Sipariş ve sunum seçenekleri oluşturma

Kullanıcı siparişini onaylamadan önce, önerilen bir sipariş kartı sunulur. Çeşitli sıra ve sunum seçeneklerini ayarlayarak bu kartın kullanıcıya sunulma şeklini özelleştirebilirsiniz.

Aşağıda, teslimat adresi gerektiren bir sipariş vermek için kullanabileceğiniz sipariş ve sunum seçenekleri bulunmaktadır. Sipariş onay kartındaki kullanıcının e-posta adresi de bu kapsamdadır:

const orderOptions = {
      'requestDeliveryAddress': true,
      'userInfoOptions': {
        'userInfoProperties': ['EMAIL']
      }
    };

const presentationOptions = {
      'actionDisplayName': 'PLACE_ORDER'
    };

Ödeme parametreleri oluşturma

paymentParameters nesneniz, kullanmayı planladığınız Google Pay işlemcisine (Stripe, Braintree, ACI vb.) bağlı olarak değişen tokenizasyon parametreleri içerir.

const paymentParamenters = {
      'googlePaymentOption': {
        // facilitationSpec is expected to be a serialized JSON string
        'facilitationSpec': JSON.stringify({
          'apiVersion': 2,
          'apiVersionMinor': 0,
          'merchantInfo': {
            'merchantName': 'Example Merchant',
          },
          'allowedPaymentMethods': [
            {
              'type': 'CARD',
              'parameters': {
                'allowedAuthMethods': ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
                'allowedCardNetworks': [
                  'AMEX', 'DISCOVER', 'JCB', 'MASTERCARD', 'VISA'],
              },
              'tokenizationSpecification': {
                'type': 'PAYMENT_GATEWAY',
                'parameters': {
                  'gateway': 'example',
                  'gatewayMerchantId': 'exampleGatewayMerchantId',
                },
              },
            },
          ],
          'transactionInfo': {
            'totalPriceStatus': 'FINAL',
            'totalPrice': '15.77',
            'currencyCode': 'USD',
          },
        }),
      },
    };

tokenizationSpecification nesnesinin içeriği, her ödeme ağ geçidi için farklıdır. Aşağıdaki tabloda, her ağ geçidi tarafından kullanılan parametreler gösterilmektedir:

ÖRNEK
"parameters": {
  "gateway": "example",
  "gatewayMerchantId": "exampleGatewayMerchantId"
}
ACI
"parameters": {
  "gateway": "aciworldwide",
  "gatewayMerchantId": "YOUR_ENTITY_ID"
}
ADYEN
"parameters": {
  "gateway": "adyen",
  "gatewayMerchantId": "YOUR_MERCHANT_ACCOUNT_NAME"
}
ALFA BANKASI
"parameters": {
  "gateway": "alfabank",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
MAVİ_MEDYA
"parameters": {
  "gateway": "bluemedia",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
MAVİ NAP
"parameters": {
  "gateway": "bluesnap",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
BRAINTREE
"parameters": {
  "gateway": "braintree",
  "braintree:apiVersion": "v1",
  "braintree:sdkVersion": braintree.client.VERSION,
  "braintree:merchantId": "YOUR_BRAINTREE_MERCHANT_ID",
  "braintree:clientKey": "YOUR_BRAINTREE_TOKENIZATION_KEY"
}
CHASE_PAYMENTECH
"parameters": {
  "gateway": "chase",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ACCOUNT_NUMBER"
}
ÖDEME
"parameters": {
  "gateway": "checkoutltd",
  "gatewayMerchantId": "YOUR_PUBLIC_KEY"
}
CLOUDPAYMENTS
"parameters": {
  "gateway": "cloudpayments",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
SİBERKAYNAK
"parameters": {
  "gateway": "cybersource",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
VERİ AKTARIMI
"parameters": {
  "gateway": "datatrans",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
EBANX
"parameters": {
  "gateway": "ebanx",
  "gatewayMerchantId": "YOUR_PUBLIC_INTEGRATION_KEY"
}
FIRST_DATA
"parameters": {
  "gateway": "firstdata",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
GLOBAL_PAYMENTS
"parameters": {
  "gateway": "globalpayments",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
GOPAY
"parameters": {
  "gateway": "gopay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
HITRUST
"parameters": {
  "gateway": "hitrustpay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
SANÇIKARMALAR
"parameters": {
  "gateway": "imsolutions",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
LYRA
"parameters": {
  "gateway": "lyra",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
MPGS
"parameters": {
  "gateway": "mpgs",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
CURRENCY_MAIL_RU
"parameters": {
  "gateway": "moneymailru",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
NEWEBPAY
"parameters": {
  "gateway": "newebpay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
NEXI
"parameters": {
  "gateway": "nexi",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
NMI
"parameters": {
  "gateway": "creditcall",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
ÖDEME GÜVENLİĞİ
"parameters": {
  "gateway": "paysafe",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
ÖDEMELER
"parameters": {
  "gateway": "payture",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
PAYU
"parameters": {
  "gateway": "payu",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
PRZELEWY24
"parameters": {
  "gateway": "przelewy24",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
RBKCURRENCY
"parameters": {
  "gateway": "rbkmoney",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
KIRMIZI BANKA
"parameters": {
  "gateway": "sberbank",
  "gatewayMerchantId": "YOUR_ORGANIZATION_NAME"
}
MEKİT
"parameters": {
  "gateway": "square",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
SORU
"parameters": {
  "gateway": "stripe",
  "stripe:version": "2018-10-31",
  "stripe:publishableKey": "YOUR_PUBLIC_STRIPE_KEY"
}
BAĞLA
"parameters": {
  "gateway": "tappay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
İNDİRİM
"parameters": {
  "gateway": "tinkoff",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
UNITELLER
"parameters": {
  "gateway": "uniteller",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
VANTIV
"parameters": {
  "gateway": "vantiv",
  "vantiv:merchantPayPageId": "YOUR_PAY_PAGE_ID",
  "vantiv:merchantOrderId": "YOUR_ORDER_ID",
  "vantiv:merchantTransactionId": "YOUR_TRANSACTION_ID",
  "vantiv:merchantReportGroup": "*web"
}
WORLDPAY
"parameters": {
  "gateway": "worldpay",
  "gatewayMerchantId": "YOUR_WORLDPAY_MERCHANT_ID"
}
YANDEX
"parameters": {
  "gateway": "yandexcheckout",
  "gatewayMerchantId": "YOUR_SHOP_ID"
}

Sipariş verilerini oturum parametresine kaydet

Sipariş karşılamanızdaki sipariş verilerini bir oturum parametresine kaydedin. Sıra nesnesi aynı oturum için sahnelerde kullanılır.

conv.session.params.order = {
    '@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
    order: order,
    orderOptions: orderOptions,
    presentationOptions: presentationOptions,
    paymentParameters: paymentParameters
};

Siparişi öner

Bir sipariş oluşturduğunuzda, siparişi onaylaması veya reddetmesi için kullanıcıya sunmanız gerekir. Bunun için işlemle ilgili kararı veren bir sahneye geçiş yapmanız gerekir.

İşlem Kararı sahnesi oluşturma

  1. Sahneler sekmesinden TransactionDecision adlı yeni bir sahne ekleyin.
  2. Slot doldurma bölümünde, yeni bir alan eklemek için + simgesini tıklayın.
  3. Tür seçin'in altında, alan türü olarak actions.type.TransactionDecisionValue'yi seçin.
  4. Alan adı alanında, alana TransactionDecision adını girin.
  5. Alan değeri yazma işlevini özelleştir onay kutusunu işaretleyin (varsayılan olarak etkindir).
  6. Alanı yapılandır bölümünde, açılır listeden Oturum parametresini kullan'ı seçin.
  7. Alanı yapılandır bölümünde,siparişi depolamak için kullanılan oturum parametresinin adını metin alanına (ör. $session.params.order) girin.
  8. Kaydet'i tıklayın.

Asistan, bir TransactionDecisionValue yuvasını doldurma girişiminde bulunmak için yerleşik bir deneyim başlatır. Bu deneyimde, ilettiğiniz Order doğrudan "alışveriş sepeti önizleme kartı"nda oluşturulur. Kullanıcı, "sipariş verin" diyebilir, işlemi reddedebilir, kredi kartı veya adres gibi bir ödeme seçeneğini değiştirebilir ya da siparişin içeriğini değiştirme isteğinde bulunabilir.

Kullanıcı bu noktada sipariş için değişiklik isteğinde de bulunabilir. Bu durumda, alışveriş sepeti montajı deneyimini tamamladıktan sonra sipariş karşılama işleminizin sipariş değişikliği isteklerini karşılayabileceğinden emin olmanız gerekir.

İşlem Kararı sonucunu işleme

Bir TransactionDecisionValue slotu doldurulduğunda kullanıcının işlem kararına verdiği yanıt bir oturum parametresinde depolanır. Bu değer şunları içerir:

  • ORDER_ACCEPTED,
  • ORDER_REJECTED,
  • DELIVERY_ADDRESS_UPDATED,
  • CART_CHANGE_REQUESTED
  • USER_CANNOT_TRANSACT.

Bir işlem kararı sonucunu işlemek için:

  1. Sahneler sekmesinden, yeni oluşturduğunuz TransactionDecision sahnesini seçin.
  2. Koşul bölümünde, yeni bir koşul eklemek için + simgesini tıklayın.
  3. Başarı koşulunu kontrol etmek için metin alanına aşağıdaki koşul söz dizimini girin:

    scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
    
  4. İmlecinizi yeni eklediğiniz koşulun üzerine getirin ve if scene.slots.status == "FINAL" koşulunun önüne yerleştirmek için yukarı oku tıklayın.

  5. İstemleri gönder'i etkinleştirin ve kullanıcıya siparişinin tamamlandığını bildiren basit bir istem sağlayın:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Transaction completed! Your order
                $session.params.TransactionDecision.order.merchantOrderId is all
                set!
    
  6. Görüşmeyi sonlandırmak için Geçiş bölümünde Görüşmeyi sonlandır'ı seçin.

  7. Koşul bölümünde, yeni bir koşul eklemek için + simgesini tıklayın.

  8. Hata koşullarını kontrol etmek için metin alanına aşağıdaki koşul söz dizimini girin:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"
    
  9. İmlecinizi yeni eklediğiniz koşulun üzerine getirin ve if scene.slots.status == "FINAL" koşulunun önüne yerleştirmek için yukarı oku tıklayın.

  10. İstemleri gönder'i etkinleştirin ve kullanıcıya siparişin reddedildiğini bildiren basit bir istem sağlayın:

    candidates:
      - first_simple:
          variants:
            - speech: Look like you don't want to order anything. Goodbye.
    
  11. İleti dizisini sonlandırmak için Geçiş bölümünde Görüşmeyi sonlandır'ı seçin.

  12. else if scene.slots.status == "FINAL" koşulunu seçin.

  13. İstemleri gönder'i etkinleştirin ve kullanıcıya bir işlem yapamayacağını bildiren basit bir istem sağlayın:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Transaction failed with status
                $session.params.TransactionDecision.transactionDecision
    
  14. Bir kullanıcı işlem yapamıyorsa görüşmeyi sonlandırmak için Geçiş bölümünde Görüşmeyi sonlandır'ı seçin.

Siparişi kesinleştirme ve makbuz gönderme

TransactionDecisionValue slotu ORDER_ACCEPTED sonucunu döndürdüğünde siparişi "onaylamak" için gereken işlemi (siparişi kendi veritabanınızda devam ettirmek ve kullanıcıdan ücret almak gibi) hemen gerçekleştirmeniz gerekir.

Bu yanıtla görüşmeyi sonlandırabilirsiniz ancak konuşmanın devam etmesini sağlamak için basit bir yanıt eklemeniz gerekir. Bu ilk orderUpdate öğesini sağladığınızda kullanıcı, yanıtınızın geri kalanıyla birlikte "daraltılmış makbuz kartı" görür. Bu kart, kullanıcının Sipariş Geçmişi'nde bulduğu makbuzu yansıtır.

Sipariş onayı sırasında sipariş nesneniz, kullanıcının sipariş için gördüğü kimlik olan bir userVisibleOrderId içerebilir. Bu alan için merchantOrderId yeniden kullanabilirsiniz.

OrderUpdate nesnesinin bir bölümünün bir takip işlem nesnesi içermesi gerekir. Bu nesne, kullanıcının Asistan Sipariş Geçmişi'nde bulabileceği sipariş ayrıntılarının alt kısmında URL düğmeleri olarak gösterilir.

  • Her sipariş için en az bir VIEW_DETAILS takip İşlemi sağlamanız gerekir. Bu, mobil uygulamanızda veya web sitenizde siparişin temsiline bir derin bağlantı içermelidir.
  • İşleminizle ilgili görüşmedeki makbuz kartına ek olarak, işlem gerçekleştirmek için gereken tüm yasal şartları karşılayan resmi bir makbuz da göndermeniz gerekir.

İlk sipariş güncellemesini göndermek için:

  1. Sahneler sekmesinden TransactionDecision sahnenizi seçin.
  2. Koşul bölümünde, başarılı sonucu kontrol eden koşulu seçin. ORDER_ACCEPTED:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
    
  3. Bu koşul için Webhook'unuzu çağırın özelliğini etkinleştirin ve update_order gibi bir amaç işleyici adı sağlayın.

  4. Webhook kodunuza, ilk sipariş güncellemesi göndermek için bir amaç işleyici ekleyin:

    app.handle('update_order', conv => {
      const currentTime = new Date().toISOString();
      let order = conv.session.params.TransactionDecision.order;
      conv.add(new OrderUpdate({
        'updateMask': {
          'paths': [
            'purchase.status',
            'purchase.user_visible_status_label'
          ]
        },
        'order': {
          'merchantOrderId': order.merchantOrderId,
          'lastUpdateTime': currentTime,
          'purchase': {
            'status': 'CONFIRMED',
            'userVisibleStatusLabel': 'Order confirmed'
          },
        },
        'reason': 'Reason string
      }));
    });
    

Sipariş güncellemeleri gönder

Kullanıcıyı siparişin ömrü boyunca durumu hakkında bilgilendirmeniz gerekir. HTTP PATCH isteklerini Siparişler API'sine sipariş durumu ve ayrıntılarıyla göndererek kullanıcı sipariş güncellemelerini gönderin.

Orders API'ye eşzamansız istekler oluşturma

Orders API'ye gönderilen sipariş güncelleme istekleri, erişim jetonuyla yetkilendirilir. Siparişler API'ye YAMA YAYAMAK için Actions Console projenizle ilişkili bir JSON hizmet hesabı anahtarı indirin, ardından hizmet hesabı anahtarını, HTTP isteğinin Authorization başlığına iletilebilecek bir hamiline ait jetonla değiştirin.

Hizmet hesabı anahtarınızı almak için aşağıdaki adımları uygulayın:

  1. Google Cloud konsolunda, Menü değişikliği > API'ler ve Hizmetler > Kimlik bilgileri > Kimlik bilgisi oluştur > Hizmet hesabı anahtarı'na gidin.
  2. Service Account (Hizmet Hesabı) bölümünde New Service Account (Yeni Hizmet Hesabı) seçeneğini belirleyin.
  3. Hizmet hesabını service-account olarak ayarlayın.
  4. RolProje > Sahip olarak ayarlayın.
  5. Anahtar türünü JSON olarak ayarlayın.
  6. Oluştur'u seçin.
  7. Özel bir JSON hizmet hesabı anahtarı yerel makinenize indirilir.

Sipariş güncellemeleri kodunuzda, Google API'leri istemci kitaplığını ve "https://www.googleapis.com/auth/actions.order.developer" kapsamını kullanarak hizmet anahtarınızı hamiline ait jetonla değiştirebilirsiniz. Kurulum adımlarını ve örnekleri API istemci kitaplığı GitHub sayfasında bulabilirsiniz.

Örnek anahtar değişimi için Node.js örneğimizde order-update.js öğesine de başvurabilirsiniz.

Sipariş güncellemeleri gönder

Hizmet hesabı anahtarınızı OAuth hamiline ait jetonla değiştirdikten sonra Orders API'ye sipariş güncellemelerini yetkili PATCH istekleri olarak gönderebilirsiniz.

Siparişler API URL'si: PATCH https://actions.googleapis.com/v3/orders/${orderId}

İsteğinizde aşağıdaki başlıkları sağlayın:

  • Hizmet hesabı anahtarınızı değiştirdiğiniz OAuth hamiline ait jetonla "Authorization: Bearer token".
  • "Content-Type: application/json".

YAMA isteği, aşağıdaki biçimde bir JSON gövdesi almalıdır:

{ "orderUpdate": OrderUpdate }

OrderUpdate nesnesi, aşağıdaki üst düzey alanlardan oluşur:

  • updateMask - Güncellediğiniz siparişin alanları. Sipariş durumunu güncellemek için değeri purchase.status, purchase.userVisibleStatusLabel olarak ayarlayın.
  • order - Güncellemenin içeriği. Siparişin içeriğini güncelliyorsanız değeri, güncellenen Order nesnesine ayarlayın. Siparişin durumunu güncelliyorsanız (örneğin, "CONFIRMED" değerinden "SHIPPED" değerine) nesne aşağıdaki alanları içerir:

    • merchantOrderId: Order nesnenizde ayarladığınız kimlik.
    • lastUpdateTime - Bu güncellemenin zaman damgası.
    • purchase - Aşağıdakileri içeren bir nesne:
      • status - Siparişin PurchaseStatus olarak durumu (ör. "SHIPPED" veya "DELIVERED").
      • userVisibleStatusLabel: Kullanıcının gördüğü ve sipariş durumuyla ilgili ayrıntıları (ör. "Siparişiniz gönderildi ve yola çıktı" gibi) sağlayan bir etiket.
  • userNotification nesnesi. Bu nesnenin dahil edilmesinin, kullanıcının cihazında bir bildirimin görüneceğini garanti etmediğini unutmayın.

Aşağıdaki örnek kod, siparişin durumunu DELIVERED olarak güncelleyen bir OrderUpdate örneğini gösterir:

// Import the 'googleapis' module for authorizing the request.
const {google} = require('googleapis');
// Import the 'request-promise' module for sending an HTTP POST request.
const request = require('request-promise');
// Import the OrderUpdate class from the client library.
const {OrderUpdate} = require('@assistant/conversation');

// Import the service account key used to authorize the request.
// Replacing the string path with a path to your service account key.
// i.e. const serviceAccountKey = require('./service-account.json')

// Create a new JWT client for the Actions API using credentials
// from the service account key.
let jwtClient = new google.auth.JWT(
    serviceAccountKey.client_email,
    null,
    serviceAccountKey.private_key,
    ['https://www.googleapis.com/auth/actions.order.developer'],
    null,
);

// Authorize the client
let tokens = await jwtClient.authorize();

// Declare order update
const orderUpdate = new OrderUpdate({
    updateMask: {
      paths: [
        'purchase.status',
        'purchase.user_visible_status_label'
      ]
    },
    order: {
      merchantOrderId: orderId, // Specify the ID of the order to update
      lastUpdateTime: new Date().toISOString(),
      purchase: {
        status: 'DELIVERED',
        userVisibleStatusLabel: 'Order delivered',
      },
    },
    reason: 'Order status updated to delivered.',
});

// Set up the PATCH request header and body,
// including the authorized token and order update.
let options = {
  method: 'PATCH',
  uri: `https://actions.googleapis.com/v3/orders/${orderId}`,
  auth: {
    bearer: tokens.access_token,
  },
  body: {
    header: {
      isInSandbox: true,
    },
    orderUpdate,
  },
  json: true,
};

// Send the PATCH request to the Orders API.
try {
  await request(options);
} catch (e) {
  console.log(`Error: ${e}`);
}
Satın alma durumunu ayarlama

Sipariş güncellemesinin status öğesi, siparişin mevcut durumunu açıklayıcı olmalıdır. Güncellemenizin order.purchase.status alanında aşağıdaki değerlerden birini kullanın:

  • CREATED - Sipariş, kullanıcı tarafından kabul edilir ve İşleminiz açısından "oluşturulur". Ancak arka uçta manuel işlem yapılması gerekir.
  • CONFIRMED - Sipariş etkin durumda ve sipariş karşılama için işleniyor.
  • IN_PREPARATION: Sipariş, gönderilmeye/teslimat için hazırlanıyor (ör. pişirilen veya paketlenen bir öğe).
  • READY_FOR_PICKUP: Sipariş, alıcı tarafından teslim alınabilir.
  • DELIVERED - Sipariş alıcıya teslim edildi
  • OUT_OF_STOCK - Siparişteki bir veya daha fazla ürün stokta yok.
  • CHANGE_REQUESTED - Kullanıcı siparişte bir değişiklik isteğinde bulundu ve bu değişiklik işleniyor.
  • RETURNED - Sipariş, teslimden sonra kullanıcı tarafından iade edildi.
  • REJECTED - Siparişi işleyemediyseniz, ödeme alamadıysanız veya başka bir şekilde "etkinleştiremediyseniz".
  • CANCELLED - Sipariş kullanıcı tarafından iptal edildi.

İşleminizle ilgili her durum için sipariş güncellemeleri göndermeniz gerekir. Örneğin, işleminiz tamamlandıktan sonra siparişi günlüğe kaydetmek için manuel işlem gerekiyorsa bu ek işlemler tamamlanana kadar CREATED sipariş güncellemesi gönderin. Her sipariş, her durum değerini gerektirmez.

Projenizi test etme

Projenizi test ederken herhangi bir ödeme yöntemi ücreti almadan İşleminizi test etmek için Actions konsolunda korumalı alan modunu etkinleştirebilirsiniz. Korumalı alan modunu etkinleştirmek için aşağıdaki adımları uygulayın:

  1. Actions Console'daki gezinme menüsünde Test et'i tıklayın.
  2. Ayarlar'ı tıklayın.
  3. Geliştirme Korumalı Alanı seçeneğini etkinleştirin.

Fiziksel işlemler için, örneğinizde isInSandbox alanını true olarak da ayarlayabilirsiniz. Bu işlem, Actions konsolundaki korumalı alan modu ayarını etkinleştirmeyle eşdeğerdir. isInSandbox kullanan bir kod snippet'i görmek için Sipariş güncellemelerini gönderme bölümünü inceleyin.

Sorun giderme

Test sırasında herhangi bir sorunla karşılaşırsanız işlemlerle ilgili sorun giderme adımlarımızı okumalısınız.