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

По этой странице можно быстро собрать интеграцию отправки заказов, получения заказа и статуса, а также отправки событий. Здесь есть подготовка проекта, примеры JSON, структура запросов, таблицы полей и диагностика ошибок.

Order Endpoint

https://kontrol-zakazov.ru/api/orders

Order Update Endpoint

https://kontrol-zakazov.ru/api/orders/{id}

Order Status Endpoint

https://kontrol-zakazov.ru/api/orders/{id}/status

Events Endpoint

https://kontrol-zakazov.ru/api/events

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

Создайте проект в панели «Контроль заказов».
Скопируйте API-ключ в настройках проекта.
Добавьте API-ключ в backend или CMS-модуль.
Проверьте отправку событий на тестовом заказе.

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

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Важно: Не публикуйте API-ключ в frontend-коде. Отправляйте запросы с backend сервера или из защищенного CMS-модуля.

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

Endpoint:POST https://kontrol-zakazov.ru/api/orders

Поле	Тип	Обязательное	Описание
order_id	string	Да	Уникальный ID заказа во внешней системе.
source	string	Да	Источник заявки: site, wordpress, woocommerce или custom.
status	string	Нет	Начальный статус заявки.
customer	object	Нет	Имя, телефон, email и дополнительные контакты клиента.
products	array	Нет	Список товаров или услуг в заказе.
amount	number	Нет	Сумма заказа.
currency	string	Нет	Валюта заказа, например RUB или USD.
comment	string	Нет	Комментарий клиента или менеджера.
metadata	object	Нет	Произвольные технические данные интеграции.
created_at	string	Нет	Дата создания заказа во внешней системе.

Пример fetch (frontend)

fetch('https://kontrol-zakazov.ru/api/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    order_id: 'SHOP-1001',
    source: 'site',
    customer: {
      name: 'Иван Петров',
      phone: '+7 980 600-00-00',
      email: 'client@example.com'
    },
    amount: 12990,
    currency: 'RUB',
    comment: 'Нужна доставка завтра'
  })
});

Пример cURL (server)

curl -X POST https://kontrol-zakazov.ru/api/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "SHOP-1001",
    "source": "site",
    "customer": {
      "name": "Иван Петров",
      "phone": "+7 980 600-00-00"
    },
    "amount": 12990,
    "currency": "RUB"
  }'

Шаг 4. Получение заказа и статуса

Получить:GET https://kontrol-zakazov.ru/api/orders/{id}

Статус:GET https://kontrol-zakazov.ru/api/orders/{id}/status

GET-запросы возвращают текущие данные заявки, статус обработки и timestamps последних изменений. Используйте их для синхронизации внешних систем.

Поле	Тип	Обязательное	Описание
order_id	number	Да	Внутренний ID заявки в Контроль заказов.
status	string	Да	Текущий статус заявки: new, processing, done или canceled.
customer	object	Нет	Контактные данные клиента.
updated_at	string	Да	Дата последнего обновления в ISO 8601.

Статус заказа

{
  "order_id": 123,
  "status": "processing",
  "updated_at": "2026-06-26T10:20:00Z"
}

Один заказ по external_id

{
  "order_id": 123,
  "external_id": "SHOP-1001",
  "status": "new",
  "customer": {
    "name": "Иван Петров",
    "phone": "+7 980 600-00-00"
  }
}

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

Endpoint:POST https://kontrol-zakazov.ru/api/events

События подходят для форм обратной связи, кликов, лид-магнитов, callback-заявок и других действий пользователя на сайте.

Поле	Тип	Обязательное	Описание
event	string	Да	Ключ события: form_submit, callback_request, button_click.
source	string	Да	Источник события: site, wordpress, bitrix, landing.
payload	object	Нет	Дополнительные данные события.

Пример fetch (frontend)

fetch('https://kontrol-zakazov.ru/api/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event: 'form_submit',
    source: 'landing',
    payload: {
      form: 'callback',
      page: location.href
    }
  })
});

Пример cURL (server)

curl -X POST https://kontrol-zakazov.ru/api/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "form_submit",
    "source": "landing",
    "payload": {
      "form": "callback",
      "page": "https://example.com"
    }
  }'

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

const KONTROL_ZAKAZOV_ENDPOINTS = {
  orders: 'https://kontrol-zakazov.ru/api/orders',
  events: 'https://kontrol-zakazov.ru/api/events',
};

async function sendToKontrolZakazov(type, payload) {
  const response = await fetch(KONTROL_ZAKAZOV_ENDPOINTS[type], {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'Accept': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(error.message || 'KontrolZakazov request failed');
  }

  return response.json();
}

document.querySelector('[data-order-form]')?.addEventListener('submit', async (event) => {
  event.preventDefault();

  const form = event.currentTarget;
  const data = new FormData(form);

  await sendToKontrolZakazov('orders', {
    order_id: crypto.randomUUID(),
    source: 'site',
    customer: {
      name: data.get('name'),
      phone: data.get('phone'),
      email: data.get('email'),
    },
    comment: data.get('comment'),
  });
});

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

HTTP код	Причина	Что проверить	Комментарий
401	API key missing / invalid API key	Указан ли ключ и не просрочен ли токен.	Проверьте Authorization header.
403	Domain forbidden	Домен отправителя добавлен в проект.	Сервер может отклонить незнакомые домены.
422	Validation error	Поля payload и обязательные значения.	Ответ содержит список ошибок.
429	Rate limit	Частоту запросов с сайта.	Добавьте очередь или retry.
500	Server error	Логи и мониторинг.	Если ошибка повторяется, напишите в поддержку.

Чеклист: сохраните API-ключ, добавьте домен, проверьте JSON, убедитесь что Content-Type установлен в application/json.