OrderReport
На главную support@orderreport.app
en ru uz

Integration Guide

Подключение отправки Orders и Events по API

На этой странице описан полный процесс интеграции двух endpoint'ов: POST /api/orders/track и POST /api/events/track. Здесь есть подготовка проекта, доменов и ключей, структуры запросов, примеры и диагностика ошибок.

Orders Endpoint

https://devserver.tw1.ru/api/orders/track

Events Endpoint

https://devserver.tw1.ru/api/events/track

Шаг 1. Подготовка в приложении

  1. Создайте проект (или выберите существующий).
  2. Добавьте домен сайта в проект (например: example.com).
  3. Создайте API key и убедитесь, что он active.
  4. Для events создайте событие и скопируйте его key (например: cfsdfsfds).
Скриншот #1
Место для скриншота: где в интерфейсе взять API key
Скриншот #2
Место для скриншота: где добавить домен проекта
Скриншот #3
Место для скриншота: где создать Event и увидеть его key

Шаг 2. Общие правила запросов

Для обоих endpoint'ов отправляйте заголовки ниже.

Content-Type: application/json
X-API-KEY: <your_api_key>

Домен проверяется по заголовку Origin и должен быть заранее добавлен в проект как активный.

Важно: если вы отправляете запрос не из браузера (например, серверным скриптом), передавайте заголовок Origin вручную, иначе API вернет 403 Invalid Origin header.

Шаг 3. Отправка заказа (Orders)

Endpoint: POST https://devserver.tw1.ru/api/orders/track

Поле Тип Обязательно Описание
id string Да Уникальный ID заказа в рамках проекта (дубликаты отклоняются).
total integer Да Сумма заказа целым числом в minor units.
currency string Нет Код валюты ISO 4217. По умолчанию используется RUB.
phone string Нет Телефон клиента.
email email Нет Email клиента (валидный формат).
username string Рекомендуется Имя/логин клиента.
products array Нет Массив товаров заказа.
products[].name string Да (если есть products) Название товара.
products[].price integer Да (если есть products) Цена единицы товара.
products[].count integer Да (если есть products) Количество товара.
products[].image url Да (если есть products) Полная ссылка на изображение товара.
data array Нет Дополнительные данные заказа в формате массива объектов { name, value }.
data[].name string Да (если есть data) Название дополнительного поля, например "Телефон".
data[].value string Да (если есть data) Значение дополнительного поля, например "+998888214888".

Пример fetch (браузер)

await fetch('https://devserver.tw1.ru/api/orders/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    id: 'order-100234',
    total: 99000,
    currency: 'RUB',
    username: 'john_doe',
    email: 'john@example.com',
    phone: '+998901112233',
    data: [
      { name: 'Имя', value: 'John Doe' },
      { name: 'Телефон', value: '+998901112233' }
    ],
    products: [
      {
        name: 'Sneakers X',
        price: 99000,
        count: 1,
        image: 'https://example.com/images/sneakers-x.jpg'
      }
    ]
  })
});

Пример cURL (сервер)

curl -X POST 'https://devserver.tw1.ru/api/orders/track' \\
  -H 'Content-Type: application/json' \\
  -H 'X-API-KEY: YOUR_API_KEY' \\
  -H 'Origin: https://example.com' \\
  -d '{
    "id": "order-100234",
    "total": 99000,
    "currency": "RUB",
    "username": "john_doe",
    "email": "john@example.com",
    "phone": "+998901112233",
    "data": [
      { "name": "Имя", "value": "John Doe" },
      { "name": "Телефон", "value": "+998901112233" }
    ],
    "products": [
      {
        "name": "Sneakers X",
        "price": 99000,
        "count": 1,
        "image": "https://example.com/images/sneakers-x.jpg"
      }
    ]
  }'

Шаг 4. Отправка события (Events)

Endpoint: POST https://devserver.tw1.ru/api/events/track

Событие принимается только если API key валиден, домен разрешен, event key существует в проекте и событие активно.

Поле Тип Обязательно Описание
event string Да Ключ события из раздела Events (например: cfsdfsfds).
data array Да Массив объектов, например [{"name":"Имя","value":"Ruslan Garapov"}].

Пример fetch (браузер)

await fetch('https://devserver.tw1.ru/api/events/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    event: 'cfsdfsfds',
    data: [
      { name: 'Имя', value: 'Ruslan Garapov' },
      { name: 'Телефон', value: '+998888214888' }
    ]
  })
});

Пример cURL (сервер)

curl -X POST 'https://devserver.tw1.ru/api/events/track' \\
  -H 'Content-Type: application/json' \\
  -H 'X-API-KEY: YOUR_API_KEY' \\
  -H 'Origin: https://example.com' \\
  -d '{
    "event": "cfsdfsfds",
    "data": [
      { "name": "Имя", "value": "Ruslan Garapov" },
      { "name": "Телефон", "value": "+998888214888" }
    ]
  }'
Скриншот #4
Место для скриншота: пример успешной отправки события/заказа (Network tab или лог)

Шаг 5. Универсальный JS helper для сайта

Этот helper можно добавить в front-end код сайта для отправки orders/events из одного места.

const OR_API_BASE = 'https://devserver.tw1.ru';
const OR_API_KEY = 'YOUR_API_KEY';

async function sendOrder(payload) {
  return sendToOrderReport('/api/orders/track', payload);
}

async function sendEvent(payload) {
  return sendToOrderReport('/api/events/track', payload);
}

async function sendToOrderReport(path, payload) {
  const res = await fetch(`${OR_API_BASE}${path}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': OR_API_KEY
    },
    body: JSON.stringify(payload)
  });

  const body = await res.json().catch(() => ({}));

  if (!res.ok) {
    throw new Error(`OrderReport API error: ${res.status} ${body.message || 'Unknown error'}`);
  }

  return body;
}

// Example:
// await sendOrder({
//   id: 'order-1',
//   total: 50000,
//   currency: 'RUB',
//   username: 'user_1',
//   email: 'user1@example.com',
//   phone: '+998901112233',
//   data: [
//     { name: 'Имя', value: 'User One' },
//     { name: 'Телефон', value: '+998901112233' }
//   ],
//   products: [
//     {
//       name: 'T-Shirt Basic',
//       price: 20000,
//       count: 1,
//       image: 'https://example.com/images/tshirt-basic.jpg'
//     },
//     {
//       name: 'Cap Black',
//       price: 30000,
//       count: 1,
//       image: 'https://example.com/images/cap-black.jpg'
//     }
//   ]
// });
// await sendEvent({
//   event: 'cfsdfsfds',
//   data: [
//     { name: 'Имя', value: 'Ruslan Garapov' },
//     { name: 'Телефон', value: '+998888214888' }
//   ]
// });

Шаг 6. Ошибки и диагностика

HTTP код message Причина Что делать
401 API key missing / Invalid API key Нет API key или он неверный/неактивный. Проверьте X-API-KEY и статус ключа.
403 Invalid Origin header / Domain not allowed Нет Origin или домен не привязан к проекту. Добавьте домен в проект и включите его.
401 Invalid event key / Event is not active Неверный ключ события или событие выключено. Проверьте поле event и активность события.
422 Validation error / Invalid data payload Неверная структура запроса. Сверьте payload с таблицей полей.
402 Monthly order limit reached for this account. Достигнут лимит заказов текущего тарифа. Обновите тариф или дождитесь нового периода.
Чеклист: активный API key, добавленный домен, созданный event key, корректный JSON и уникальный id заказа.