Перейти к основному содержимому

Заказы | Документация для разработчиков

Заказы

Обновлено: 25 марта 2026 г
API платежей представляет два новых типа интерактивных сообщений : order_details и order_status . Они являются точкой входа для приема платежей в WhatsApp.
    order_details отправляются для создания заказа в приложении WhatsApp покупателя. Это сообщение содержит настройки оплаты, используемые для приема платежей, и может дополнительно включать заказа с подробным описанием товаров, комиссий и скидок. Без заказа можно отправить упрощенное сообщение с подробной информацией о заказе, содержащее только общую сумму и настройки оплаты. Настройки оплаты будут различаться в зависимости от типа интеграции ( Pix , платежные ссылки , Boleto , One Click Payments ). order_status отправляются, когда компании обновляют статус заказа либо на основании уведомления об изменении статуса платежа в WhatsApp, либо в соответствии со своими внутренними процессами. Вы также можете отправить упрощенное обновление статуса без заказа .
    Изображение
    При прикреплении к сообщению с подробной информацией о заказе, заказы изначально находятся в «ожидание» . Когда продавец полностью выполнит заказ, и покупателю не следует ожидать дальнейших обновлений, его необходимо пометить как выполненный .

    Отправка сообщений о заказе

    Оба типа сообщений содержат одни и те же 4 основных компонента интерактивного сообщения: заголовок , тело , нижний колонтитул и действие . Параметры в действия будут различаться в зависимости от типа сообщения. Кроме того, order_details и order_status могут дополнительно включать заказа , содержащий список товаров, сборы и другие сведения о заказе.
    После того, как объект интерактивного сообщения будет сформирован, выполните POST-запрос к конечной точке messages . Не забудьте установить тип как interactive .

    Пример сведений о заказе

    Конечная точка
    POST /{PHONE_NUMBER_ID}/messages
    Текст запроса
    { "recipient_type": "individual", "to": "<PHONE_NUMBER> ", "type": "interactive", "interactive": { "type": "order_details", "body": { "text": "Содержание вашего сообщения" }, "action": { "name": "review_and_pay", "parameters": { "reference_id": "unique-reference-id", "type": "digital-goods", "payment_type": "br", "payment_settings": [ { "type": "payment_link", "payment_link": { "uri": "https://my-payment-link-url" } } ], "currency": "BRL", "total_amount": { "value": 50000, "offset": 100 }, "order": { "status": "pending", "tax": { "value": 0, "offset": 100, "description": "optional text" }, "items": [ { "retailer_id": "1234567", "name": "Торт", "количество": { "значение": 50000, "смещение": 100 }, "количество": 1 } ], "итого": { "значение": 50000, "смещение": 100 } } } } } }
    Упрощенное сообщение с подробной информацией о заказе
    Конечная точка
    POST /{PHONE_NUMBER_ID}/messages

    Текст запроса
    { "recipient_type": "individual", "to": "<PHONE_NUMBER> ", "type": "interactive", "interactive": { "type": "order_details", "body": { "text": "Содержание вашего сообщения" }, "action": { "name": "review_and_pay", "parameters": { "reference_id": "unique-reference-id", "type": "digital-goods", "payment_type": "br", "payment_settings": [ { "type": "payment_link", "payment_link": { "uri": "https://my-payment-link-url" } } ], "currency": "BRL", "total_amount": { "value": 50000, "offset": 100 } } } } }
    Пример статуса заказа
    Конечная точка
    POST /{PHONE_NUMBER_ID}/messages

    Текст запроса
    { "recipient_type": "individual", "to": "<PHONE_NUMBER> ", "type": "interactive", "interactive": { "type": "order_status", "body": { "text": "your-mandatory-text-body-content" }, "footer": { "text": "your-optional-text-footer-content" }, "action": { "name": "review_order", "parameters": { "reference_id": "unique-reference-id", "order": { "status": "processing" }, "payment": { "status": "captured", "timestamp": 1722445231 } } } } }
    Упрощенный пример статуса заказа
    Конечная точка
    POST /{PHONE_NUMBER_ID}/messages

    Текст запроса
    { "recipient_type": "individual", "to": "<PHONE_NUMBER> ", "type": "interactive", "interactive": { "type": "order_status", "body": { "text": "your-mandatory-text-body-content" }, "footer": { "text": "your-optional-text-footer-content" }, "action": { "name": "review_order", "parameters": { "reference_id": "unique-reference-id", "payment": { "status": "captured", "timestamp": 1722445231 } } } } }
    Ответ на сообщение
    В любом случае, если ваше сообщение будет отправлено успешно, вы получите следующий ответ:
    { "messaging_product": "whatsapp", "contacts": [ { "input": "[PHONE_NUMBER_ID]", "wa_id": "[PHONE-NUMBER_ID]" } ], "messages": [ { "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA" } ] }
    Со всеми возможными ошибками и рекомендациями по их обработке можно ознакомиться в разделе «Коды ошибок Cloud API» .
    Полная справочная информация по API
    Детали заказа
    Для отправки сообщения order_details предприятиям необходимо собрать интерактивный объект типа order_details, состоящий из следующих компонентов:
    Интерактивный объект
    Название поляНеобязательный?ТипОписание
    тип
    Необходимый
    Нить
    Должно быть order_details .
    заголовок
    Необязательный
    Объект
    Миниатюрное изображение для сообщения с подробной информацией о заказе. Оно содержит следующие поля:
      Тип : Должен быть изображением .изображение : см. Объект изображения .
      Если заголовок отсутствует, API находит первый товар с изображением и использует его в качестве миниатюры.
      тело
      Необходимый
      Объект
      Объект, содержащий тело сообщения. Объект содержит следующее поле:
        Текстовая строка: Содержимое сообщения. Поддерживаются эмодзи и разметка Markdown. Максимальная длина — 1024 символа.
        нижний колонтитул
        Необязательный
        Объект
        Объект, содержащий нижнюю часть сообщения. Объект содержит следующее поле:
          Текстовая строка: Обязательна, если присутствует нижний колонтитул. Содержимое нижнего колонтитула. Поддерживаются эмодзи, разметка Markdown и ссылки. Максимальная длина — 60 символов.
          действие
          Необходимый
          Объект действия
          См. раздел «Объект действия» ниже.
          Изображение Объект
          
Название поля

Необязательный?

Тип

Описание

          связь
          Необходимый
          Нить
          URL изображения.
          поставщик
          Необязательный
          Нить
          Название поставщика URL-адресов.
          Объект действия
          
Название поля

Необязательный?

Тип

Описание

          имя
          Необходимый
          Нить
          Необходимо выбрать review_and_pay .
          параметры
          Необходимый
          Объект параметров
          Объект параметров
          Название поляНеобязательный?ТипОписание
          reference_id
          Необходимый
          Нить
          Уникальный идентификатор заказа или счета-фактуры, предоставленный компанией. Он не может быть пустой строкой и может содержать только английские буквы, цифры, подчеркивания, дефисы или точки, и не должен превышать 60 символов.
          Идентификатор ссылки (reference_id) должен быть уникальным для каждого сообщения order_details, относящегося к одному и тому же заказу. Если партнер хочет отправить несколько сообщений order_details для одного и того же заказа, счета-фактуры и т. д., рекомендуется включить порядковый номер в reference_id для обеспечения его уникальности.
          тип
          Необходимый
          Нить
          Должен быть либо цифровой товар , либо физический товар .
          payment_type
          Необходимый
          Нить
          Должно быть , бр .
          настройки оплаты
          Необязательный
          Список объектов конфигурации, связанных с платежами.
          валюта
          Необходимый
          Нить
          Код валюты по стандарту ISO 4217 для заказа. Должен быть BRL (бразильский реал).
          Общая сумма
          Необходимый
          Сумма Объект
          Значение total_amount.value должно быть равно order.subtotal.value + order.tax.value + order.shipping.value - order.discount.value
          заказ
          Необязательный
          Объект заказа
          Настройки платежей
          
Название поля

Необязательный?

Тип

Описание

          тип
          Необходимый
          Нить
          Один из pix_dynamic_code , payment_link , boleto .
          Один из следующих объектов: pix_dynamic_code , payment_link , boleto .
          Необходимый
          Объект
          Инструкции по оплате, которые будут отображены покупателям в процессе оформления заказа.
          Объект заказа
          Название поляНеобязательный?ТипОписание
          статус
          Необходимый
          Нить
          Статус заказа. Здесь поддерживается только значение " ожидает обработки" .
          catalog_id
          Необязательный
          Нить
          Уникальный идентификатор каталога Facebook, используемого компанией.
          срок действия
          Необязательный
          Объект истечения срока действия
          Срок действия данного заказа истекает. После истечения срока действия кнопка призыва к действию (CTA) будет отключена на стороне пользователя. См. Объект «Срок действия» .
          предметы
          Необходимый
          Список объектов элементов
          Список должен содержать как минимум один элемент. См. Объект «Элемент» .
          промежуточная сумма
          Необходимый
          Сумма Объект
          Значение должно быть равно сумме ( item.amount.value или item.sale_amount.value ) * item.quantity .
          Следующие поля являются частью  «Промежуточный итог» :
          смещение строки
            Обязательно. Для BRL должно быть не менее 100 .
            строковое значение
              Обязательно. Положительное целое число, представляющее значение суммы, умноженное на смещение. Например, S$12.34 имеет значение 1234.
              налог
              Необходимый
              Сумма с описанием объекта
              Информация о налогах для этого заказа. Несмотря на то, что объект является обязательным, сумма может быть равна нулю. При использовании нуля строка с налогом не отображается в клиенте. См. Объект «Сумма с описанием» .
              перевозки
              Необязательный
              Сумма с описанием объекта
              скидка
              Необязательный
              Объект скидки
              Скидка на заказ. См. объект «Скидка» .
              Объект истечения срока действия
              Название поляНеобязательный?ТипОписание
              метка времени
              Необходимый
              Нить
              Время UTC в секундах. Минимальный порог — 300 секунд.
              описание
              Необходимый
              Нить
              Текстовое пояснение, указывающее на срок действия заказа. Максимальное количество символов — 120.
              Объект элемента
              Название поляНеобязательный?ТипОписание
              retailer_id
              Необходимый
              Нить
              Идентификатор содержимого для товара в заказе из вашего каталога.
              имя
              Необходимый
              Нить
              Название товара, которое будет отображаться пользователю. Не может превышать 60 символов.
              количество
              Необходимый
              Сумма Объект
              Цена за единицу товара. См. Объект «Сумма» .
              количество
              Необходимый
              Целое число
              Количество товаров в этом заказе.
              сумма продажи
              Необязательный
              Сумма Объект
              Цена со скидкой за единицу товара. Она должна быть меньше первоначальной суммы. Если это поле включено, оно используется для расчета промежуточной суммы. См. Объект «Сумма» .
              Объект скидки
              Название поляНеобязательный?ТипОписание
              ценить
              Необходимый
              Целое число
              Положительное целое число, представляющее собой сумму, умноженную на смещение. Например, 12,34 BRL имеют значение 1234.
              компенсировать
              Необходимый
              Целое число
              Для BRL сумма должна составлять 100 .
              описание
              Необязательный
              Нить
              Максимальное количество символов — 60.
              discount_program_name
              Необязательный
              Нить
              Текст, используемый для обозначения заказов с предоставлением скидок. Если заказ является заказом с предоставлением скидок, продавец должен указать эту информацию. Максимальное количество символов — 60.
              Сумма Объект
              Название поляНеобязательный?ТипОписание
              ценить
              Необходимый
              Целое число
              Положительное целое число, представляющее собой сумму, умноженную на смещение. Например, 12,34 BRL имеют значение 1234.
              компенсировать
              Необходимый
              Целое число
              Для BRL сумма должна составлять 100 .
              Объект «Сумма» (с описанием)
              Название поляНеобязательный?ТипОписание
              ценить
              Необходимый
              Целое число
              Положительное целое число, представляющее собой сумму, умноженную на смещение. Например, 12,34 BRL имеют значение 1234.
              компенсировать
              Необходимый
              Целое число
              Для BRL сумма должна составлять 100 .
              описание
              Необязательный
              Нить
              Максимальное количество символов — 60.
              Статус заказа
              Для отправки сообщения order_status предприятиям необходимо собрать интерактивный объект типа order_status, состоящий из следующих компонентов:
              Интерактивный объект
              Название поляНеобязательный?ТипОписание
              тип
              Необходимый
              Нить
              Должно быть order_status .
              заголовок
              Необязательный
              Объект
              Необязательный объект для заголовка сообщения.
              тело
              Необходимый
              Объект
              Объект, содержащий тело сообщения. Объект содержит следующее поле:
                Текстовая строка: Содержимое сообщения. Поддерживаются эмодзи и разметка Markdown. Максимальная длина — 1024 символа.
                нижний колонтитул
                Необязательный
                Объект
                Объект, содержащий нижнюю часть сообщения. Объект содержит следующее поле:
                  Текстовая строка: Обязательна, если присутствует нижний колонтитул. Содержимое нижнего колонтитула. Поддерживаются эмодзи, разметка Markdown и ссылки. Максимальная длина — 60 символов.
                  действие
                  Необходимый
                  Объект действия
                  См. раздел «Объект действия» ниже.
                  Объект действия
                  
Название поля

Необязательный?

Тип

Описание

                  имя
                  Необходимый
                  Нить
                  Должно быть review_order .
                  параметры
                  Необходимый
                  Объект параметров
                  Объект параметров
                  
Название поля

Необязательный?

Тип

Описание

                  reference_id
                  Необходимый
                  Нить
                  Уникальный идентификатор, указанный в  order_details .
                  заказ
                  Необязательный
                  Объект заказа
                  оплата
                  Необязательный
                  Объект платежа
                  Объект заказа
                  
Название поля

Необязательный?

Тип

Описание

                  статус
                  Необходимый
                  Нить
                  описание
                  Необязательный
                  Нить
                  Дополнительный текст для отображения информации о статусе заказа на странице сведений о заказе. Может быть полезен при отправке уведомления об отмене. Длина текста не должна превышать 120 символов.
                  Объект платежа
                  
Название поля

Необязательный?

Тип

Описание

                  статус
                  Необходимый
                  Нить
                  метка времени
                  Необязательный
                  Целое число
                  Необязательная метка времени в секундах (с возможностью установки даты начала отсчета)
                  Статус поддерживаемого заказа
                  В настоящее время мы поддерживаем следующие значения статуса заказа:
                  
Ценить

Описание

                  в ожидании
                  Заказ находится в обработке / еще не обработан.
                  обработка
                  Продавец/партнер выполняет заказ, оказывает услугу и т. д.
                  частично отгружено
                  Часть заказанных товаров уже отправлена ​​продавцом.
                  отправленный
                  Все заказанные товары были отправлены продавцом.
                  завершенный
                  Заказ выполнен, и от пользователя или партнера/продавца не требуется никаких дальнейших действий.
                  отменено
                  Партнер/продавец хочет отменить сообщение order_details для заказа/счета. Обновление статуса не удастся, если по этому сообщению order_details уже есть успешный или ожидающий платеж.
                  Статус поддерживаемого платежа
                  В настоящее время мы поддерживаем следующие значения статуса платежа:
                  
Ценить

Описание

                  в ожидании
                  Оплата ожидается.
                  захвачен
                  Оплата успешно списана. После получения этого статуса платежа в окне заказа появится отметка «оплачено» (с зеленой галочкой).
                  неуспешный
                  Платеж не удался.
                  Ошибки и статусы
                  Вот соответствующие ошибки для API платежей WhatsApp:
                  
Код ошибки

Описание

                  2040 - Сообщение не поддерживается
                  Сообщение, которое вы пытаетесь отправить, не может быть получено этим пользователем
                  2046 - Недействительный переход статуса заказа
                  Статус заказа нельзя изменить с существующего значения на новое
                  2047 - Неудачная отмена заказа
                  Заказ не мог быть отменен
                  Полный список с подробным описанием кодов ошибок и кодов состояния HTTP см. в нашем  «Коды ошибок» .
                  
    
                          
                  
    
                  

            
                  
        
                  
    
                  

    
                  

    
    
                  
        
                  
             Вернуться наверх