OrderReport
Bosh sahifa support@orderreport.app
en ru uz

Integration Guide

Orders va Events yuborishni API orqali ulash

Bu sahifada ikki endpoint uchun to'liq integratsiya jarayoni berilgan: POST /api/orders/track va POST /api/events/track. Bu yerda loyiha sozlamalari, domenlar, kalitlar, so'rov strukturalari, misollar va xatolar diagnostikasi bor.

Orders Endpoint

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

Events Endpoint

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

1-qadam. Ilovada tayyorlash

  1. Loyiha yarating (yoki mavjud loyihani tanlang).
  2. Sayt domenini loyihaga qo'shing (masalan: example.com).
  3. API key yarating va u active ekanini tekshiring.
  4. Events uchun event yarating va uning key qiymatini saqlang (masalan: cfsdfsfds).
Skrinshot #1
Joy: API key qayerdan olinishi
Skrinshot #2
Joy: loyiha domenini qayerga qo'shish
Skrinshot #3
Joy: Event yaratish va uning key qiymatini ko'rish

2-qadam. So'rovlar uchun umumiy qoidalar

Har ikkala endpoint uchun quyidagi header'larni yuboring.

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

Domen tekshiruvi Origin header orqali qilinadi. Domen loyihada qo'shilgan va active bo'lishi kerak.

Muhim: agar so'rov brauzerdan tashqaridan yuborilsa (masalan, server skript), Origin header'ni qo'lda yuboring, aks holda API 403 Invalid Origin header qaytaradi.

3-qadam. Buyurtma yuborish (Orders)

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

Maydon Turi Majburiy Tavsif
id string Ha Loyiha ichidagi noyob buyurtma ID (dublikat qabul qilinmaydi).
total integer Ha Buyurtma summasi minor units ko‘rinishidagi butun son.
currency string Yo'q ISO 4217 valuta kodi. Standart qiymat RUB.
phone string Yo'q Mijoz telefoni.
email email Yo'q Mijoz emaili (to'g'ri format).
username string Tavsiya etiladi Mijoz ismi/logini.
products array Yo'q Buyurtma tovarlari ro'yxati.
products[].name string Ha (products bo'lsa) Tovar nomi.
products[].price integer Ha (products bo'lsa) Bitta tovar narxi.
products[].count integer Ha (products bo'lsa) Tovar soni.
products[].image url Ha (products bo'lsa) Tovar rasmi uchun to'liq URL.
data array Yo'q Buyurtma uchun qo'shimcha ma'lumotlar: { name, value } obyektlari massivi.
data[].name string Ha (data bo'lsa) Qo'shimcha maydon nomi, masalan "Telefon".
data[].value string Ha (data bo'lsa) Qo'shimcha maydon qiymati, masalan "+998888214888".

Fetch misoli (brauzer)

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 misoli (server)

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-qadam. Event yuborish (Events)

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

Event faqat API key to'g'ri bo'lsa, domen ruxsat etilgan bo'lsa, event key loyihada mavjud bo'lsa va event active bo'lsa qabul qilinadi.

Maydon Turi Majburiy Tavsif
event string Ha Events bo'limidagi event key (masalan: cfsdfsfds).
data array Ha Obyektlar massivi, masalan [{"name":"Ism","value":"Ruslan Garapov"}].

Fetch misoli (brauzer)

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 misoli (server)

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" }
    ]
  }'
Skrinshot #4
Joy: event/buyurtma muvaffaqiyatli yuborilganini ko'rsatadigan Network yoki log

5-qadam. Sayt uchun universal JS helper

Ushbu helper'ni frontend kodga qo'shib, orders/events yuborishni bitta joydan boshqaring.

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-qadam. Xatolar va diagnostika

HTTP kod message Sabab Nima qilish kerak
401 API key missing / Invalid API key API key yo'q, noto'g'ri yoki nofaol. X-API-KEY header va kalit holatini tekshiring.
403 Invalid Origin header / Domain not allowed Origin yo'q yoki domen loyiha bilan bog'lanmagan. Domenni loyihaga qo'shing va faollashtiring.
401 Invalid event key / Event is not active Event key noto'g'ri yoki event o'chirilgan. event maydoni va event holatini tekshiring.
422 Validation error / Invalid data payload So'rov strukturasi noto'g'ri. Payloadni jadvaldagi maydonlar bilan tekshiring.
402 Monthly order limit reached for this account. Joriy tarif uchun oy limitiga yetilgan. Tarifni yangilang yoki keyingi davrni kuting.
Cheklist: active API key, qo'shilgan domen, yaratilgan event key, to'g'ri JSON va noyob order id.