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

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

URL: https://kontrol-zakazov.ru/docs/api/podklyuchenie-otpravki
Обновлено: 2026-08-29

## Подключение отправки 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. Подготовка и приложение

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

![Список проектов и ключей API](/images/docs/article-step1-a.png)

![Тестовая отправка заявки](/images/docs/article-step1-b.png)

### Шаг 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"
    }
  }'
```

![События в интерфейсе Контроль заказов](/images/docs/article-step5.png)

### Шаг 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.