Integration Guide

Connect Orders and Events API tracking

This page explains the full integration flow for two endpoints: POST /api/orders/track and POST /api/events/track. It includes project setup, domains and keys, request structures, examples, and error diagnostics.

Orders Endpoint

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

Events Endpoint

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

Step 1. Setup in the app

Create a project (or use an existing one).
Add your website domain to the project (for example: example.com).
Create an API key and make sure it is active.
For events, create an event and copy its key (for example: cfsdfsfds).

Screenshot #1

Placeholder: where to find API key in the interface

Screenshot #2

Placeholder: where to add project domain

Screenshot #3

Placeholder: where to create an event and view its key

Step 2. Common request rules

Send the headers below for both endpoints.

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

Domain validation uses the Origin header. This domain must be added to the project and active.

Important: if the request is sent outside a browser (for example, from server code), set the Origin header manually, otherwise API returns 403 Invalid Origin header.

Step 3. Send order (Orders)

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

Field	Type	Required	Description
`id`	string	Yes	Unique order ID inside a project (duplicates are rejected).
`total`	integer	Yes	Order total as integer in minor units.
`currency`	string	No	ISO 4217 currency code. Defaults to RUB.
`phone`	string	No	Customer phone number.
`email`	email	No	Customer email (valid email format).
`username`	string	Recommended	Customer name/login.
`products`	array	No	Array of order products.
`products[].name`	string	Yes (if products provided)	Product name.
`products[].price`	integer	Yes (if products provided)	Product unit price.
`products[].count`	integer	Yes (if products provided)	Product quantity.
`products[].image`	url	Yes (if products provided)	Full product image URL.
`data`	array	No	Optional additional order data as an array of { name, value } pairs.
`data[].name`	string	Yes (if data provided)	Additional field label, for example "Phone".
`data[].value`	string	Yes (if data provided)	Additional field value, for example "+998888214888".

Fetch example (browser)

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 example (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"
      }
    ]
  }'

Step 4. Send event (Events)

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

Event tracking works only if API key is valid, domain is allowed, event key exists in the project, and event is active.

Field	Type	Required	Description
`event`	string	Yes	Event key from Events section (for example: cfsdfsfds).
`data`	array	Yes	Array of objects, for example [{"name":"Name","value":"Ruslan Garapov"}].

Fetch example (browser)

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 example (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" }
    ]
  }'

Screenshot #4

Placeholder: successful event/order request in Network tab or logs

Step 5. Universal JS helper for your site

Add this helper to your frontend and send orders/events from a single place.

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' }
//   ]
// });

Step 6. Errors and diagnostics

HTTP code	message	Reason	How to fix
401	API key missing / Invalid API key	API key is missing, invalid, or inactive.	Check X-API-KEY header and key status.
403	Invalid Origin header / Domain not allowed	Origin is missing or domain is not linked to project.	Add the domain to project and enable it.
401	Invalid event key / Event is not active	Wrong event key or disabled event.	Check event field and event active status.
422	Validation error / Invalid data payload	Request payload structure is invalid.	Validate payload against field table.
402	Monthly order limit reached for this account.	Current plan monthly order limit exceeded.	Upgrade plan or wait for next billing period.

Checklist: active API key, added domain, created event key, valid JSON, and unique order id.