Заказы | Документация для разработчиков
Заказы
Обновлено: 25 марта 2026 г
API платежей представляет два новых типа интерактивных сообщений :
order_details и order_status . Они являются точкой входа для приема платежей в WhatsApp.order_details отправляются для создания заказа в приложении WhatsApp покупателя. Это сообщение содержит настройки оплаты, используемые для приема платежей, и может дополнительно включать заказа с подробным описанием товаров, комиссий и скидок. Без заказа можно отправить упрощенное сообщение с подробной информацией о заказе, содержащее только общую сумму и настройки оплаты. Настройки оплаты будут различаться в зависимости от типа интеграции ( Pix , платежные ссылки , Boleto , One Click Payments ). order_status отправляются, когда компании обновляют статус заказа либо на основании уведомления об изменении статуса платежа в WhatsApp, либо в соответствии со своими внутренними процессами. Вы также можете отправить упрощенное обновление статуса без заказа .
При прикреплении к сообщению с подробной информацией о заказе, заказы изначально находятся в
«ожидание» . Когда продавец полностью выполнит заказ, и покупателю не следует ожидать дальнейших обновлений, его необходимо пометить как выполненный .Отправка
сообщения о заказе
подробности заказастатус заказазаказинтерактивныйПример сведений о заказе
Конечная точка
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" } ] }
Полная справочная информация по 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 .
строковое
значениеналог
Необходимый
Сумма с описанием объекта
Информация о налогах для этого заказа. Несмотря на то, что объект является обязательным, сумма может быть равна нулю. При использовании нуля строка с налогом не отображается в клиенте. См. Объект «Сумма с описанием» .
перевозки
Необязательный
Сумма с описанием объекта
См. Объект «Сумма» .
скидка
Необязательный
Объект скидки
Скидка на заказ. См. объект «Скидка» .
Объект истечения срока действия
метка времени
Необходимый
Нить
Время 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 см. в нашем «Коды ошибок» .