Transactions API در 3 مه 2023 منسوخ خواهد شد، قبل از غروب کنش‌های مکالمه در 13 ژوئن 2023. برای اطلاعات بیشتر، غروب کنش‌های مکالمه را ببینید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

با Google Pay تراکنش های فیزیکی ایجاد کنید

این راهنما شما را در فرآیند توسعه یک پروژه Actions راهنمایی می‌کند که تراکنش‌های کالاهای فیزیکی را در بر می‌گیرد و از Google Pay برای پرداخت استفاده می‌کند.

جریان تراکنش

وقتی پروژه Actions شما تراکنش‌های فیزیکی را با استفاده از پرداخت‌های مدیریت‌شده توسط بازرگان انجام می‌دهد، از جریان زیر استفاده می‌کند:

جمع آوری اطلاعات (اختیاری) - بسته به ماهیت تراکنش، ممکن است بخواهید اطلاعات زیر را در ابتدای مکالمه از کاربر جمع آوری کنید:
1. اعتبارسنجی الزامات تراکنش - در ابتدای مکالمه، تأیید کنید که کاربر شرایط لازم برای انجام یک تراکنش را دارد، مانند پیکربندی صحیح اطلاعات پرداخت و در دسترس بودن قبل از ساخت سبد خرید.
2. درخواست یک آدرس تحویل - اگر تراکنش نیاز به یک آدرس تحویل دارد، یک آدرس از کاربر جمع آوری کنید.
سفارش را بسازید - کاربر را از طریق یک "مجموعه سبد خرید" که در آن اقلامی را که می خواهند خریداری کنند، انتخاب کنند.
پیشنهاد سفارش - پس از تکمیل سبد خرید، سفارش را به کاربر پیشنهاد دهید تا بتواند صحت آن را تایید کند. اگر سفارش تأیید شود، پاسخی حاوی جزئیات سفارش و یک رمز پرداخت دریافت خواهید کرد.
سفارش را نهایی کنید و رسید ارسال کنید - با تایید سفارش، ردیابی موجودی یا سایر خدمات تکمیلی خود را به روز کنید و سپس رسید را برای کاربر ارسال کنید.
ارسال به‌روزرسانی‌های سفارش - در طول عمر انجام سفارش، با ارسال درخواست‌های PATCH به Orders API، به‌روزرسانی‌های سفارش را در اختیار کاربر قرار دهید.

محدودیت ها و دستورالعمل های بازبینی

به خاطر داشته باشید که خط‌مشی‌های اضافی برای اقدامات با تراکنش‌ها اعمال می‌شود. بررسی Actions با تراکنش‌ها می‌تواند تا شش هفته طول بکشد، بنابراین هنگام برنامه‌ریزی زمان‌بندی انتشار، آن زمان را در نظر بگیرید. برای تسهیل روند بازبینی، قبل از ارسال Action برای بررسی، مطمئن شوید که از خط‌مشی‌ها و دستورالعمل‌های تراکنش‌ها پیروی می‌کنید.

فقط می‌توانید Actionهایی را اجرا کنید که کالاهای فیزیکی را در کشورهای زیر می‌فروشند:

استرالیا
برزیل
کانادا
اندونزی

ژاپن
مکزیک
روسیه

سنگاپور
تایلند
ترکیه
انگلستان
ایالات متحده آمریکا

پروژه خود را بسازید

برای مثال‌های گسترده از مکالمات تراکنشی، نمونه تراکنش‌های Node.js را مشاهده کنید.

راه اندازی

هنگام ایجاد Action خود، باید مشخص کنید که می‌خواهید تراکنش‌ها را در کنسول Actions انجام دهید.

برای تنظیم پروژه و اجرای خود، موارد زیر را انجام دهید:

یک پروژه جدید ایجاد کنید یا یک پروژه موجود را وارد کنید.
به Deploy > Directory information بروید.
در قسمت اطلاعات اضافی > تراکنش‌ها > کادری را علامت بزنید که می‌گوید «آیا اقدامات شما از API تراکنش‌ها برای انجام تراکنش‌های کالاهای فیزیکی استفاده می‌کند؟».

1. جمع آوری اطلاعات (اختیاری)

1a. اعتبارسنجی الزامات تراکنش (اختیاری)

به محض اینکه کاربر اعلام کرد که مایل به خرید است، باید بررسی کنید که آیا می‌تواند تراکنش را انجام دهد. برای مثال، هنگام فراخوانی، Action شما ممکن است بپرسد: "آیا می‌خواهید کفش سفارش دهید یا موجودی حساب خود را بررسی کنید؟" اگر کاربر می گوید "سفارش سفارش دهید"، باید اطمینان حاصل کنید که آنها می توانند ادامه دهند و به آنها فرصت دهید تا تنظیماتی را که مانع از ادامه تراکنش می شوند، اصلاح کنند. برای انجام این کار، باید به صحنه ای بروید که بررسی الزامات تراکنش را انجام می دهد.

ایجاد صحنه بررسی الزامات معامله

از تب Scenes، یک صحنه جدید با نام TransactionRequirementsCheck اضافه کنید.
در قسمت Slot filling ، روی + کلیک کنید تا یک اسلات جدید اضافه کنید.
در قسمت Select type ، actions.type.TransactionRequirementsCheckResult را به عنوان نوع اسلات انتخاب کنید.
در فیلد نام اسلات، نام اسلات را TransactionRequirementsCheck قرار دهید.
کادر بررسی بازنویسی مقدار اسلات سفارشی را فعال کنید (به طور پیش فرض فعال است).
روی ذخیره کلیک کنید.

بررسی الزامات تراکنش منجر به یکی از نتایج زیر می شود:

در صورت برآورده شدن شرایط، پارامتر جلسه با شرط موفقیت تنظیم می شود و می توانید به ساخت سفارش کاربر ادامه دهید.
اگر یک یا چند مورد از الزامات برآورده نشود، پارامتر جلسه با یک شرط شکست تنظیم می شود. در این مورد، باید مکالمه را از تجربه تراکنش دور کنید یا مکالمه را پایان دهید.
- اگر هر گونه خطایی که منجر به وضعیت خرابی می شود توسط کاربر برطرف شود، از آنها خواسته می شود تا آن مشکلات را در دستگاه خود حل کنند. اگر مکالمه روی یک سطح فقط صوتی انجام شود، یک انتقال به تلفن کاربر آغاز می شود.

رسیدگی به الزامات تراکنش نتایج را بررسی کنید

از تب Scenes ، صحنه تازه ایجاد شده TransactionRequirementsCheck خود را انتخاب کنید.
در قسمت Condition ، روی + کلیک کنید تا یک شرط جدید اضافه کنید.
در قسمت متن، دستور شرط زیر را وارد کنید تا شرایط موفقیت را بررسی کنید:
```
scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
```
نشانگر خود را روی شرطی که به تازگی اضافه کرده اید نگه دارید و روی فلش بالا کلیک کنید تا آن را قبل از قرار دهید if scene.slots.status == "FINAL" .
دستورهای ارسال را فعال کنید و یک اعلان ساده ارائه دهید تا کاربر بداند که آماده انجام معامله است:
```
candidates:
  - first_simple:
      variants:
        - speech: >-
            You are ready to purchase physical goods.
```
در بخش Transition صحنه دیگری را انتخاب کنید، که به کاربر اجازه می دهد مکالمه را ادامه دهد و تراکنش را انجام دهد.
شرط else if scene.slots.status == "FINAL" .
درخواست‌های ارسال را فعال کنید و یک اعلان ساده ارائه دهید که به کاربر اطلاع می‌دهد قادر به انجام تراکنش نیست:
```
candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.
```
در بخش انتقال ، پایان مکالمه را انتخاب کنید تا اگر کاربر قادر به انجام تراکنش نیست، به مکالمه پایان دهید.

درخواست آدرس تحویل

اگر تراکنش شما به آدرس تحویل کاربر نیاز دارد، باید آن را از کاربر درخواست کنید. این ممکن است برای تعیین قیمت کل، محل تحویل/ تحویل، یا برای اطمینان از اینکه کاربر در منطقه خدمات شما است مفید باشد. برای انجام این کار، باید به صحنه ای بروید که از کاربر آدرس تحویل خود را می خواهد.

ایجاد صحنه آدرس تحویل

از برگه Scenes ، یک صحنه جدید با نام DeliveryAddress اضافه کنید.
در قسمت Slot filling ، روی + کلیک کنید تا یک اسلات جدید اضافه کنید.
در قسمت Select type ، actions.type.DeliveryAddressValue را به عنوان نوع اسلات انتخاب کنید.
در قسمت نام شکاف، نام TransactionDeliveryAddress را به شکاف بدهید.
کادر بررسی بازنویسی مقدار اسلات سفارشی را فعال کنید (به طور پیش فرض فعال است).
روی ذخیره کلیک کنید.

هنگام پیکربندی شکاف، می‌توانید reason ارائه کنید که به شما امکان می‌دهد درخواست دستیار برای به دست آوردن آدرس را با یک رشته مقدمه کنید. بنابراین، دستیار ممکن است از کاربر بپرسد: "برای اینکه بدانم سفارش را کجا ارسال کنیم، باید آدرس تحویل شما را دریافت کنم".

در سطوح دارای صفحه نمایش، کاربر انتخاب می کند که از کدام آدرس برای تراکنش استفاده کند. اگر قبلاً آدرسی نداده باشند، می‌توانند آدرس جدیدی وارد کنند.
در سطوح فقط صوتی، دستیار از کاربر اجازه می‌خواهد تا آدرس پیش‌فرض خود را برای تراکنش به اشتراک بگذارد. اگر قبلاً آدرسی نداده باشند، مکالمه برای ورود به تلفن تحویل داده می شود.

برای رسیدگی به نتیجه آدرس تحویل، این مراحل را دنبال کنید:

از تب Scenes ، صحنه DeliveryAddress تازه ایجاد شده خود را انتخاب کنید.
در قسمت Condition ، روی + کلیک کنید تا یک شرط جدید اضافه کنید.
در قسمت متن، دستور شرط زیر را وارد کنید تا شرایط موفقیت را بررسی کنید:
```
scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"
```
نشانگر خود را روی شرطی که به تازگی اضافه کرده اید نگه دارید و روی فلش بالا کلیک کنید تا آن را قبل از قرار دهید if scene.slots.status == "FINAL" .

درخواست‌های ارسال را فعال کنید و یک اعلان ساده ارائه دهید تا کاربر بداند آدرس خود را دریافت کرده‌اید:

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

در بخش انتقال ، صحنه دیگری را انتخاب کنید تا کاربر بتواند مکالمه را ادامه دهد.
شرط else if scene.slots.status == "FINAL" .
دستورهای ارسال را فعال کنید و یک اعلان ساده ارائه دهید تا کاربر بداند قادر به انجام تراکنش نیست:
```
candidates:
  - first_simple:
      variants:
        - speech: I failed to get your delivery address.
```
در بخش انتقال ، پایان مکالمه را انتخاب کنید تا اگر کاربر قادر به انجام تراکنش نیست، به مکالمه پایان دهید.

نظم را بسازید

هنگامی که اطلاعات کاربری مورد نیاز خود را در اختیار داشتید، یک تجربه "مونتاژ سبد خرید" ایجاد خواهید کرد که کاربر را برای ایجاد سفارش راهنمایی می کند. هر Action یک جریان مونتاژ سبد خرید کمی متفاوت خواهد داشت که متناسب با محصول یا خدمات خود باشد.

ابتدایی ترین تجربه مونتاژ سبد خرید این است که کاربر مواردی را از فهرست انتخاب می کند تا به سفارش خود اضافه کند، اگرچه می توانید مکالمه را طوری طراحی کنید که تجربه کاربری را ساده کنید. شما می توانید یک تجربه مونتاژ سبد خرید بسازید که کاربر را قادر می سازد آخرین خرید خود را از طریق یک سوال بله یا خیر دوباره سفارش دهد. همچنین می‌توانید چرخ فلک یا کارت فهرستی از آیتم‌های «ویژه» یا «توصیه‌شده» را به کاربر ارائه دهید.

توصیه می کنیم از پاسخ های غنی برای ارائه گزینه های کاربر به صورت بصری استفاده کنید، اما مکالمه را به گونه ای طراحی کنید که کاربر بتواند تنها با استفاده از صدای خود سبد خرید خود را بسازد. برای برخی از بهترین شیوه‌ها و نمونه‌هایی از تجربیات مونتاژ گاری با کیفیت بالا، دستورالعمل‌های طراحی را ببینید.

یک سفارش ایجاد کنید

در طول مکالمه خود، باید مواردی را که کاربر می خواهد بخرد جمع آوری کنید و سپس یک شیء Order بسازید.

حداقل، Order شما باید حاوی موارد زیر باشد:

buyerInfo - اطلاعاتی در مورد کاربری که خرید می کند.
transactionMerchant - اطلاعاتی در مورد تاجری که سفارش را تسهیل کرده است.
contents - محتویات واقعی سفارش که به عنوان lineItems فهرست شده است.
priceAttributes - جزئیات قیمت در مورد سفارش، از جمله هزینه کل سفارش با تخفیف و مالیات.

برای ساخت سبد خرید خود به مستندات پاسخ Order مراجعه کنید. توجه داشته باشید که بسته به ترتیب ممکن است لازم باشد فیلدهای مختلفی را وارد کنید.

کد نمونه زیر یک سفارش کامل شامل فیلدهای اختیاری را نشان می دهد:

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',
  },
};

گزینه های سفارش و ارائه را ایجاد کنید

قبل از اینکه کاربر سفارش خود را تایید کند، کارت سفارش پیشنهادی به وی ارائه می شود. شما می توانید با تنظیم گزینه های مختلف سفارش و ارائه، نحوه ارائه این کارت به کاربر را سفارشی کنید.

در زیر گزینه های سفارش و ارائه برای سفارشی که نیاز به آدرس تحویل دارد، از جمله ایمیل کاربر در کارت تأیید سفارش آمده است:

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

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

ایجاد پارامترهای پرداخت

شی paymentParameters شما شامل پارامترهای توکن‌سازی خواهد بود که بسته به پردازشگر Google Pay که قصد استفاده از آن را دارید تغییر می‌کند (مانند Stripe، Braintree، ACI، و غیره).

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 برای هر دروازه پرداخت متفاوت خواهد بود. جدول زیر پارامترهای استفاده شده توسط هر دروازه را نشان می دهد:

مثال

"parameters": {
  "gateway": "example",
  "gatewayMerchantId": "exampleGatewayMerchantId"
}

ACI

"parameters": {
  "gateway": "aciworldwide",
  "gatewayMerchantId": "YOUR_ENTITY_ID"
}

آدین

"parameters": {
  "gateway": "adyen",
  "gatewayMerchantId": "YOUR_MERCHANT_ACCOUNT_NAME"
}

آلفا بانک

"parameters": {
  "gateway": "alfabank",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

BLUE_MEDIA

"parameters": {
  "gateway": "bluemedia",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

BLUESNAP

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

تسویه حساب

"parameters": {
  "gateway": "checkoutltd",
  "gatewayMerchantId": "YOUR_PUBLIC_KEY"
}

پرداخت های ابری

"parameters": {
  "gateway": "cloudpayments",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

منبع سایبری

"parameters": {
  "gateway": "cybersource",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}

DATATRANS

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

IMSOLUTIONS

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

MONEY_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"
}

PAYSAFE

"parameters": {
  "gateway": "paysafe",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

پرداخت

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

RBKMONEY

"parameters": {
  "gateway": "rbkmoney",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}

SBERBANK

"parameters": {
  "gateway": "sberbank",
  "gatewayMerchantId": "YOUR_ORGANIZATION_NAME"
}

میدان

"parameters": {
  "gateway": "square",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

راه راه

"parameters": {
  "gateway": "stripe",
  "stripe:version": "2018-10-31",
  "stripe:publishableKey": "YOUR_PUBLIC_STRIPE_KEY"
}

TAPPAY

"parameters": {
  "gateway": "tappay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

TINKOFF

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

داده های سفارش را در پارامتر جلسه ذخیره کنید

از انجام خود، داده های سفارش را در یک پارامتر جلسه ذخیره کنید. شی سفارش در سراسر صحنه ها برای همان جلسه استفاده خواهد شد.

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

سفارش را پیشنهاد دهید

پس از ایجاد یک سفارش، باید آن را به کاربر ارائه دهید تا تأیید یا رد شود. برای انجام این کار، باید به صحنه ای بروید که تصمیم تراکنش را انجام می دهد.

صحنه تصمیم معامله را ایجاد کنید

از تب Scenes ، یک صحنه جدید با نام TransactionDecision اضافه کنید.
در قسمت Slot filling ، روی + کلیک کنید تا یک اسلات جدید اضافه کنید.
در قسمت Select type ، actions.type.TransactionDecisionValue را به عنوان نوع اسلات انتخاب کنید.
در فیلد نام اسلات، نام TransactionDecision را به اسلات بدهید.
کادر بررسی بازنویسی مقدار اسلات سفارشی را فعال کنید (به طور پیش فرض فعال است).
در قسمت پیکربندی شکاف ، از منوی کشویی استفاده از پارامتر جلسه را انتخاب کنید.
در قسمت پیکربندی شکاف، نام پارامتر جلسه مورد استفاده برای ذخیره سفارش را در فیلد متنی وارد کنید (یعنی $session.params.order ).
روی ذخیره کلیک کنید.

در تلاش برای پر کردن شکاف TransactionDecisionValue ، دستیار یک تجربه داخلی را آغاز می‌کند که در آن Order که شما ارسال کرده‌اید مستقیماً روی یک «کارت پیش‌نمایش سبد خرید» ارائه می‌شود. کاربر می تواند بگوید "سفارش دهید"، تراکنش را رد کند، گزینه پرداخت مانند کارت اعتباری یا آدرس را تغییر دهد، یا درخواست تغییر محتویات سفارش را بدهد.

کاربر همچنین ممکن است در این مرحله درخواست تغییر در سفارش را داشته باشد. در این مورد، باید مطمئن شوید که انجام شما می‌تواند درخواست‌های تغییر سفارش را پس از اتمام تجربه مونتاژ سبد خرید انجام دهد.

رسیدگی به نتیجه تصمیم معامله

هنگامی که یک اسلات TransactionDecisionValue پر می شود، پاسخ کاربر به تصمیم تراکنش در یک پارامتر جلسه ذخیره می شود. این مقدار شامل موارد زیر است:

ORDER_ACCEPTED ،
ORDER_REJECTED ،
DELIVERY_ADDRESS_UPDATED ،
CART_CHANGE_REQUESTED
USER_CANNOT_TRANSACT .

برای رسیدگی به نتیجه تصمیم تراکنش:

از تب Scenes ، صحنه TransactionDecision تازه ایجاد شده خود را انتخاب کنید.
در قسمت Condition ، روی + کلیک کنید تا یک شرط جدید اضافه کنید.
در قسمت متن، دستور شرط زیر را وارد کنید تا شرایط موفقیت را بررسی کنید:
```
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
```
نشانگر خود را روی شرطی که به تازگی اضافه کرده اید نگه دارید و روی فلش بالا کلیک کنید تا آن را قبل از قرار دهید if scene.slots.status == "FINAL" .

درخواست‌های ارسال را فعال کنید و یک اعلان ساده ارائه دهید تا کاربر بداند سفارشش تکمیل شده است:

candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction completed! Your order
            $session.params.TransactionDecision.order.merchantOrderId is all
            set!

در بخش انتقال ، پایان مکالمه را برای پایان دادن به مکالمه انتخاب کنید.
در قسمت Condition ، روی + کلیک کنید تا یک شرط جدید اضافه کنید.

در قسمت متن، دستور شرط زیر را برای بررسی شرایط خرابی وارد کنید:

  scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"

نشانگر خود را روی شرطی که به تازگی اضافه کرده اید نگه دارید و روی فلش بالا کلیک کنید تا آن را قبل از قرار دهید if scene.slots.status == "FINAL" .
درخواست‌های ارسال را فعال کنید و یک فرمان ساده ارائه دهید تا کاربر متوجه شود سفارش رد شده است:
```
candidates:
  - first_simple:
      variants:
        - speech: Look like you don't want to order anything. Goodbye.
```
در قسمت Transition، پایان مکالمه را برای پایان دادن به مکالمه انتخاب کنید.
شرط else if scene.slots.status == "FINAL" .

دستورهای ارسال را فعال کنید و یک اعلان ساده ارائه دهید تا کاربر بداند قادر به انجام تراکنش نیست:

candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction failed with status
            $session.params.TransactionDecision.transactionDecision

در بخش انتقال ، پایان مکالمه را انتخاب کنید تا اگر کاربر قادر به انجام تراکنش نیست، به مکالمه پایان دهید.

سفارش را نهایی کنید و رسید ارسال کنید

هنگامی که شکاف TransactionDecisionValue نتیجه ORDER_ACCEPTED را برمی گرداند، باید فوراً هر پردازشی را که برای "تأیید" سفارش لازم است انجام دهید (مانند تداوم آن در پایگاه داده خودتان و هزینه از کاربر).

شما می توانید با این پاسخ مکالمه را به پایان برسانید، اما باید یک پاسخ ساده برای ادامه مکالمه در نظر بگیرید. وقتی این orderUpdate اولیه را ارائه می‌کنید، کاربر یک «کارت رسید جمع‌شده» را به همراه بقیه پاسخ شما می‌بیند. این کارت رسیدی را که کاربر در تاریخچه سفارش خود پیدا می کند منعکس می کند.

در طول تأیید سفارش، شی سفارش شما می‌تواند شامل یک userVisibleOrderId باشد، که شناسه‌ای است که کاربر برای سفارش می‌بیند. می‌توانید از merchantOrderId خود برای این فیلد دوباره استفاده کنید.

بخشی از شی OrderUpdate باید حاوی یک شیء اقدام بعدی باشد که به صورت دکمه های URL در پایین جزئیات سفارش ظاهر می شود که کاربر می تواند در تاریخچه سفارش دستیار خود پیدا کند.

شما باید حداقل یک VIEW_DETAILS اقدام بعدی را با هر سفارش ارائه دهید. این باید حاوی یک پیوند عمیق به نمایش سفارش در برنامه تلفن همراه یا وب سایت شما باشد.
همچنین باید یک رسید رسمی از طریق ایمیل ارسال کنید که تمام شرایط قانونی برای انجام تراکنش را داشته باشد، علاوه بر کارت رسید در مکالمه Action شما.

برای ارسال به‌روزرسانی سفارش اولیه:

از تب Scenes ، صحنه TransactionDecision خود را انتخاب کنید.
در شرایط ، شرطی را انتخاب کنید که نتیجه موفقیت آمیز را بررسی می کند، ORDER_ACCEPTED :
```
  scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
```
برای این شرایط، Call your webhook را فعال کنید و یک نام کنترل کننده قصد، مانند update_order ارائه دهید.

در کد وب هوک خود، یک کنترل کننده قصد برای ارسال به‌روزرسانی سفارش اولیه اضافه کنید:

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
  }));
});

ارسال به روز رسانی سفارش

شما باید کاربر را از وضعیت سفارش در طول عمر آن مطلع کنید. به‌روزرسانی‌های سفارش کاربر را با ارسال درخواست‌های HTTP PATCH به Orders API همراه با وضعیت سفارش و جزئیات ارسال کنید.

درخواست های ناهمزمان را در Orders API تنظیم کنید

درخواست‌های به‌روزرسانی سفارش به Orders API توسط یک نشانه دسترسی مجاز است. برای وصله به‌روزرسانی سفارش در Orders API، یک کلید حساب سرویس JSON مرتبط با پروژه Actions Console خود را دانلود کنید، سپس کلید حساب سرویس را با یک توکن حامل که می‌تواند به سرصفحه Authorization درخواست HTTP منتقل شود، مبادله کنید.

برای بازیابی کلید حساب سرویس خود، مراحل زیر را انجام دهید:

در کنسول Google Cloud ، به منو ☰ > APIs & Services > Credentials > Create credentials > Service key account بروید.
در قسمت Service Account ، New Service Account را انتخاب کنید.
حساب سرویس را روی service-account تنظیم کنید.
Role را روی Project > Owner تنظیم کنید.
نوع کلید را روی JSON تنظیم کنید.
ایجاد را انتخاب کنید.
یک کلید حساب سرویس JSON خصوصی در دستگاه محلی شما دانلود می شود.

در کد به‌روزرسانی‌های سفارش، می‌توانید با استفاده از کتابخانه سرویس گیرنده Google APIs و محدوده «https://www.googleapis.com/auth/actions.order.developer» کلید خدمات خود را با یک توکن حامل تعویض کنید. می‌توانید مراحل و نمونه‌های نصب را در صفحه GitHub کتابخانه سرویس گیرنده API پیدا کنید.

همچنین می‌توانید به order-update.js در نمونه Node.js ما برای تبادل کلید مثال مراجعه کنید.

ارسال به روز رسانی سفارش

هنگامی که کلید حساب سرویس خود را با یک توکن حامل OAuth مبادله کردید، می توانید به روز رسانی های سفارش را به عنوان درخواست های PATCH مجاز به Orders API ارسال کنید.

URL API سفارشات: PATCH https://actions.googleapis.com/v3/orders/${orderId}

سرفصل های زیر را در درخواست خود وارد کنید:

"Authorization: Bearer token" با نماد حامل OAuth که کلید حساب سرویس خود را با آن مبادله کرده اید.
"Content-Type: application/json" .

درخواست PATCH باید بدنه JSON با فرمت زیر داشته باشد:

{ "orderUpdate": OrderUpdate }

شی OrderUpdate از فیلدهای سطح بالای زیر تشکیل شده است:

updateMask - فیلدهای سفارشی که به روز می کنید. برای به روز رسانی وضعیت سفارش، مقدار purchase.status, purchase.userVisibleStatusLabel را تنظیم کنید.
order - محتویات به روز رسانی. اگر محتوای سفارش را به‌روزرسانی می‌کنید، مقدار را روی شی به‌روزرسانی شده Order تنظیم کنید. اگر وضعیت سفارش را به‌روزرسانی می‌کنید (مثلاً از "CONFIRMED" به "SHIPPED" )، شی حاوی فیلدهای زیر است:
- merchantOrderId - همان شناسه ای که در شیء Order خود تنظیم کرده اید.
- lastUpdateTime - مهر زمانی این به روز رسانی.
- purchase - یک شی حاوی موارد زیر:
  - status - وضعیت سفارش به عنوان PurchaseStatus ، مانند " SHIPPED " یا " DELIVERED ".
  - userVisibleStatusLabel - یک برچسب رو به روی کاربر که جزئیات وضعیت سفارش را ارائه می دهد، مانند "سفارش شما ارسال شده است و در راه است".
userNotification (اختیاری) - یک شی userNotification که می تواند هنگام ارسال این به روز رسانی در دستگاه کاربر نمایش داده شود. توجه داشته باشید که گنجاندن این شیء تضمین نمی کند که یک اعلان در دستگاه کاربر ظاهر شود.

کد نمونه زیر نمونه ای از OrderUpdate را نشان می دهد که وضعیت سفارش را به DELIVERED به روز می کند:

// 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}`);
}

وضعیت خرید را تنظیم کنید

status به‌روزرسانی سفارش باید توصیفی از وضعیت فعلی سفارش باشد. در قسمت order.purchase.status به روز رسانی خود، از یکی از مقادیر زیر استفاده کنید:

CREATED - سفارش توسط کاربر پذیرفته می شود و از منظر اقدام شما "ایجاد" می شود، اما نیاز به پردازش دستی در پشتیبان شما دارد.
CONFIRMED - سفارش فعال است و برای انجام در حال پردازش است.
IN_PREPARATION - سفارش برای ارسال/تحویل آماده می شود، مانند غذا در حال پخته شدن یا بسته بندی یک مورد.
READY_FOR_PICKUP - سفارش برای تحویل توسط گیرنده در دسترس است.
DELIVERED - سفارش به گیرنده تحویل داده شد
OUT_OF_STOCK - یک یا چند مورد در سفارش موجود نیست.
CHANGE_REQUESTED - کاربر درخواست تغییر در سفارش را داده است و تغییر در حال پردازش است.
RETURNED - سفارش پس از تحویل توسط کاربر برگردانده شده است.
REJECTED - اگر نتوانستید سفارش را پردازش کنید، شارژ کنید یا در غیر این صورت "فعال" کنید.
CANCELLED - سفارش توسط کاربر لغو شد.

شما باید به‌روزرسانی‌های سفارش را برای هر وضعیتی که به تراکنش شما مرتبط است ارسال کنید. برای مثال، اگر تراکنش شما به پردازش دستی برای ثبت سفارش پس از ثبت نیاز دارد، یک به‌روزرسانی سفارش CREATED را تا زمانی که پردازش اضافی انجام شود، ارسال کنید. هر سفارشی به هر مقدار وضعیت نیاز ندارد.

پروژه خود را تست کنید

هنگام آزمایش پروژه خود، می‌توانید حالت sandbox را در کنسول Actions فعال کنید تا Action خود را بدون پرداخت هزینه از روش پرداخت آزمایش کنید. برای فعال کردن حالت جعبه ایمنی، مراحل زیر را دنبال کنید:

در کنسول Actions، روی Test در ناوبری کلیک کنید.
روی تنظیمات کلیک کنید.
گزینه Development Sandbox را فعال کنید.

برای تراکنش‌های فیزیکی، می‌توانید فیلد isInSandbox را نیز در نمونه خود روی true تنظیم کنید. این عمل معادل فعال کردن تنظیمات حالت sandbox در کنسول Actions است. برای دیدن قطعه کدی که از isInSandbox استفاده می‌کند، به بخش ارسال به‌روزرسانی‌های سفارش مراجعه کنید.

عیب یابی

اگر در طول آزمایش با مشکلی مواجه شدید، باید مراحل عیب‌یابی تراکنش‌ها را بخوانید.