Интеграция заказов

Чтобы сохранять высокий уровень доверия клиентов, конверсий и удержания, вы должны предлагать понятный и качественный интерфейс оформления заказа и обслуживание после покупки. Надлежащая обработка и синхронизация заказов между системами Meta и системами продавца обеспечивает точность и надежность работы с клиентами, снижая количество проблем как с клиентами, так и с продавцами.

• Такие проблемы клиентов, как отмена заказов или задержка доставки, бьют по репутации продавцов и приводят к росту нагрузки на службу поддержки.
• Проблемы на стороне продавца, например ошибки синхронизации заказов, могут приводить к задержке или невозможности оплаты, потому что заказы в системах Meta не помечаются как выполненные.

Отсутствие поддержки клиентов после покупки, например несвоевременное подтверждение или обработка возвратов, может привести к возврату средств по инициативе службы поддержки за счет продавца.

Наилучший интерфейс управления заказами для продавцов — тот, в котором они могут выполнять в уже используемой ими системе управления заказами следующие задачи:

• обработать и выполнить новый заказ;
• отменить заказ целиком или частично, уведомив клиента о проблеме с выполнением;
• вернуть клиенту средства целиком или частично.

Если товар не помечен как final sale, вы обязаны обеспечить поддержку его возврата. По умолчанию у покупателей есть 30 дней на возврат, однако продавцы могут настраивать политику возврата и на уровне отдельных товаров. Покупатели могут зайти в сведения о заказе и запросить возврат. В результате будет выполнено одно из следующих действий:

• если в настройках возврата магазина задан параметр Returns URL, откроется сайт возврата продавца;
• на контактный адрес службы поддержки продавца, зарегистрированный в настройках магазина, будет отправлено электронное письмо.

Если в посылку вложена этикетка для возврата, покупатели также могут вернуть товар напрямую, не используя приложение Facebook или Instagram. Когда продавец получит возвращенный товар, следует инициировать возврат средств.

Чтобы получить представление о различных статусах заказа, переходах и операциях, связанных с заказом на торговой платформе Meta, ознакомьтесь со статьей Жизненный цикл заказа. В этом обзоре описана интеграция с точки зрения прямого продавца, однако он вполне применим и к партнерским интеграциям, где продавцы связаны с партнерской платформой.

После успешного подключения продавцов и загрузки их ассортимента в Meta их товары готовы будут к покупке. С помощью Order Management API на торговой платформе вы можете перемещать заказы продавцов, которых вы поддерживаете, в свою систему и управлять жизненным циклом заказов.

Требования

Чтобы соответствовать стандартам качества интеграции Магазинов, необходимо выполнить следующие требования.

Требование 1. Получение и подтверждение заказов из Meta

Требование 2. Синхронизация статусов заказов в системе управления с Meta

Прежде чем начать

Ваше приложение должно иметь следующие разрешения:

• commerce_manage_accountsилиcommerce_account_read_settings;
• commerce_account_manage_ordersилиcommerce_account_read_orders.

Требование 1. Получение и подтверждение заказов из Meta

Шаг 1. Получение новых заказов

Для управления заказами через API сначала необходимо связать приложение с настройками торговли продавца, представляющего магазин. Это действие нужно выполнить только один раз для каждого магазина. В результате завершенные заказы на торговой платформе Meta будут иметь состояние CREATED для подтверждения вами.

Пример запроса

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{api-version}/{cms-id}/order_management_apps

Пример ответа

{
    "success": true
}

Заказы, оформленные на Facebook или в Instagram, приостанавливаются на время обработки нашими внутренними системами. Эта задержка также предназначена для того, чтобы у покупателей была возможность отменить заказы, если они передумали. После того как Meta убедится в законности этой транзакции, соответствующий заказ становится доступным для выполнения. Когда продавец выполняет заказ, деньги, связанные с выполнением заказа, фиксируются, и начинается процесс выплаты денег продавцу.

Для поиска новых заказов используйте List Orders API. Это механизм, основанный на извлечении данных, который позволяет постоянно опрашивать API в поисках новых заказов, которые нужно выполнить. Рекомендуемый интервал опроса: 5–15 минут. По умолчанию этот API выводит список всех заказов, связанных с магазином, и возвращает только заказы, которые находятся в состоянии CREATED.

Пример запроса

curl -X GET -G \
  -d 'state=CREATED' \
  -d 'fields=id,buyer_details,channel,merchant_order_id,order_status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{api-version}/{cms-id}/commerce_orders

Пример ответа

{
  "data": [
    {
      "id": "3565497390177110",
      "buyer_details": {
        "name": "John Doe",
        "email": "7dvra5wfy2@commerce.facebook.com",
        "email_remarketing_option": false
      },
      "channel": "facebook",
      "order_status": {
        "state": "CREATED"
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "--SANITIZED--",
      "after": "--SANITIZED--"
    }
  }
}

Ответ содержит переменную ORDER_ID в поле data[].id, которое позволяет определить операцию с этим конкретным заказом в последующих запросах. В ответе могут присутствовать и другие новые заказы. Чтобы обработать все новые заказы, используйте курсоры разбивки на страницы. Подробнее см. в разделе, посвященном Order API.

Шаг 2. Подтверждение заказов

Когда обработка заказа (проверка на предмет мошенничества и т. д.) на торговой платформе Meta завершается, он автоматически переходит в состояние CREATED. Подробнее о состояниях заказа см. в этом разделе.

Подтверждение заказа означает, что вы перенесли заказ в свою систему управления заказами и готовы к тому, чтобы продавец его выполнил. У продавца должны быть достаточные запасы товара, и в момент подтверждения заказа он должен отложить нужные товары. После подтверждения заказ переходит в статус IN_PROGRESS.

Во время подтверждения можно передать параметр merchant_order_reference. Это уникальный идентификатор заказа, известный в вашей внутренней системе управления заказами. Этот идентификатор отображается на чеке, и пользователи могут указывать его при обращении в вашу службу поддержки.

В зависимости от количества заказов вы можете использовать обычную обработку или Batch API. Этот API позволяет подтверждать до 100 заказов за один запрос. Если вы ожидаете большого объема заказов, рекомендуем подтверждать их в пакетном режиме. Если подтверждать их по одному, есть вероятность превысить ограничение числа обращений для Страницы. В этом случае вызовы API будут регулироваться. Чтобы обрабатывать заказы в пакетном режиме, используйте наш метод массового подтверждения. Чтобы подтвердить созданный заказ, вызовите Acknowledgement API с указанием ORDER_ID.

Пример запроса

curl -X POST \
  -F '{
    "idempotency_key": "<UUID>"
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{api-version}/{order-id]/acknowledge_order

Пример запроса (непакетный)

{
  "id": "3565497390177110",
  "state": "IN_PROGRESS"
}

Пример запроса (пакетный)

{
  "idempotency_key": "cb090e84-e75a-9a34-45d3-5163bec88b65",
  "orders": [
    {
      "id": "64000841790004"
    },
    {
      "id": "10100677592885259"
    }
  ]
}

Если какие-то заказы находились в состоянии FB_PROCESSING, к ним невозможно применить ACK. Вы получите закодированное исключение. Повторное выполнение этих запросов с тем же ключом идемпотентности возвращает тот же результат. Если вы получаете закодированное исключение, рекомендуем использовать новый ключ идемпотентности и повторить попытку.

Пример ответа (пакетный)

{
  "orders": [
    {
      "id": "64000841790004",
      "state": "IN_PROGRESS"
    },
    {
      "id": "10100677592885259",
      "error": {
        "error_code": 2361003,
        "error_message": "Invalid Order ID"
      }
    }
  ]
}

Подробнее об Acknowledgement API см. в этой статье.

Требование 2. Синхронизация статусов заказов в системе управления с Meta

Шаг 1. Синхронизация отмены заказа

Продавцы могут целиком или частично отменять заказы, которые находятся в состоянии IN_PROGRESS. Например, это может потребоваться, чтобы уведомить покупателя о проблемах, если заказ не был отправлен вовремя. Когда продавец инициирует отмену заказа в вашей системе управления, синхронизируйте состояние отмены заказа с Meta, вызвав Cancel Order API с указанием ORDER_ID.

Пример запроса

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{api-version}/{order-id}/cancellations

Пример запроса (заказ целиком)

  "cancel_reason": {
    "reason_code": "CUSTOMER_REQUESTED",
    "reason_description": "Buyer did not need it anymore"
  },
  "restock_items": true,
  "idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}

Пример запроса (часть заказа)

{
  "cancel_reason": {
    "reason_code": "OUT_OF_STOCK",
    "reason_description": "Ran out of item"
  },
  "restock_items": false,
  "items": [
    {
      "retailer_id": "FB_product_1234",
      "quantity": 1
    }
  ],
  "idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}

Пример ответа

{
  "success": true
}

Подробнее о Cancellation API см. в этом разделе.

Шаг 2. Синхронизация выполнения заказа

Когда продавец начинает выполнять заказ, синхронизируйте состояние выполнения заказа из вашей системы управления с Meta, вызвав API отправлений с указанием ORDER_ID, что свяжет код перевозчика и номер для отслеживания.

Пример запроса

curl -X POST \
  -F '{
    "external_shipment_id": "shipment_1",
    "items": [
      {
        "retailer_id": "FB_T_Shirt_001",
        "quantity": 1
      }
    ],
    "tracking_info": {
      "tracking_number": "1Z204E380338943508",
      "carrier": "UPS",
    },
    "idempotency_key": "<UUID>"
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{api-version]/{order-id}/shipments

Пример ответа

{
  "success": true
}

Подробнее об Fulfillment API см. в этой статье.

Шаг 3. Синхронизация возврата заказа

Продавцы могут инициировать частичный или полный возврат (по количеству или цене). Обычно это происходит, если покупатель обнаружил какую-либо проблему с товаром. Если продавец инициирует действие возврата, синхронизируйте состояние возвращаемого заказа в вашей системе управления с Meta, вызвав Refund Order API и указав ORDER_ID и код причины. Список возможных причин возврата см. в разделе refund_reason_code enum. Будет запущена обратная платежная операция Meta в пользу покупателя, а баланс продавца будет уменьшен на соответствующую сумму.

Пример запроса

curl -X POST \
  -F '{
   "reason_code": "WRONG_ITEM",
   "idempotency_key": "<UUID>"
}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{api-version}/{order-id}/refunds

Пример запроса (заказ целиком)

{
    "reason_code": "WRONG_ITEM",
    "idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}

Пример запроса (часть заказа)

{
  "items": [
    {
      "item_id": "1234",
      "item_refund_quantity": 1
    },
    {
      "item_id": "38383838",
      "item_refund_amount": {
        "amount": "2.5",
        "currency": "USD"
      }
    }
  ],
  "shipping": {
    "shipping_refund": {
      "amount": "2.4",
      "currency": "USD"
    }
  },
  "deductions": [
    {
      "deduction_type": "RETURN_SHIPPING",
      "deduction_amount": {
        "amount": "5.5",
        "currency": "USD"
      }
    }
  ],
  "reason_code": "WRONG_ITEM",
  "idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}

Пример ответа

{
  "success": true
}

Подробнее о Refund API см. в этом разделе.

Дополнительная информация

• Order Management API
• List Orders API
• Состояние заказа
• Cancel Order API