Выгрузка накладных в 1С

Система предоставляет отдельный REST API для внешних интеграций (в первую очередь — синхронизации с 1С), не связанный с обычной пользовательской сессией. Доступ к нему выдаётся через ключ API, а не через логин/пароль.

Получение ключа API

1. Зайдите под пользователем с ролью владелец или разработчик (developer).
2. Откройте раздел Аккаунт → Ключи API (/account/apikeys).
3. Нажмите «Создать ключ», укажите название и выберите права доступа (scope):
   • naks:read — чтение накладных и их позиций;
   • naks:write — возможность отметить накладную как выгруженную (записать cid).
4. Секретное значение ключа показывается только один раз, сразу после создания. Сохраните его в безопасном месте — восстановить позже нельзя, можно только создать новый ключ.
5. Ключ можно отключить или удалить в любой момент на той же странице — это сразу остановит доступ по нему.

Аутентификация запросов

Каждый запрос к API интеграции должен содержать заголовок:

X-Api-Key: <ваш ключ>

Ключ привязан к конкретному аккаунту (компании) — все данные в ответе автоматически ограничены этим аккаунтом. Передавать account_id отдельно не нужно.

Если ключ не передан, недействителен, отключён, либо не имеет нужного scope — сервер отвечает 401 Unauthorized.

GET /api/1c/naks

Возвращает список накладных (naks) вместе с их позициями (nak_items) для последующей загрузки в 1С.

Требуемый scope: naks:read.

Query-параметры

Параметр	Тип	По умолчанию	Описание
limit	number	100	Размер страницы
offset	number	0	Смещение для пагинации
from	string	—	Начало периода по created_at, формат YYYY-MM-DD
to	string	—	Конец периода по created_at, формат YYYY-MM-DD
posted	number	—	Фильтр по статусу проведения (0 / 1)
type	number	—	Тип накладной: 1 — приход, 2 — расход, 3 — возврат, 4 — перемещение

Удалённые накладные (deleted_at is not null) в выгрузку не попадают.

Пример запроса

curl -H "X-Api-Key: <ваш ключ>" \
  "https://bevtrade.kz/api/1c/naks?from=2026-07-01&to=2026-07-17&limit=100&offset=0"

Пример ответа

{
  "items": [
    {
      "id": 4821,
      "storage_id": 3,
      "type": 2,
      "posted": 1,
      "cid": null,
      "sum": 154200,
      "quantity": 320,
      "client_id": 118,
      "client_name": "ТОО Ромашка",
      "client_address": "г. Алматы, ул. Абая 10",
      "storage": "Основной склад",
      "comment": "",
      "created_at": "2026-07-15T09:12:00.000Z",
      "delivered_at": "2026-07-15T14:00:00.000Z",
      "items": [
        {
          "id": 91011,
          "nak_id": 4821,
          "product_id": 55,
          "product_name": "Вода питьевая 0.5л",
          "product_shortname": "Вода 0.5",
          "product_cid": "00-0000123",
          "amount": 120,
          "price": 320,
          "group": "items"
        }
      ]
    }
  ],
  "total": 1
}

Поле cid у накладной и product_cid у позиции — это идентификатор соответствующего документа/номенклатуры в 1С. Пока накладная не выгружена, cid равен null.

PATCH /api/1c/naks/:id/cid

Отмечает накладную как выгруженную — сохраняет присвоенный ей в 1С идентификатор документа. Используется после успешного импорта накладной на стороне 1С, чтобы при следующих запросах GET /api/1c/naks можно было по полю cid отличить уже выгруженные документы от новых.

Требуемый scope: naks:write.

Тело запроса

{
  "cid": "БТ-000123"
}

Пример запроса

curl -X PATCH -H "X-Api-Key: <ваш ключ>" -H "Content-Type: application/json" \
  -d '{"cid": "БТ-000123"}' \
  "https://bevtrade.kz/api/1c/naks/4821/cid"

Пример ответа

{
  "message": "Отметка о выгрузке в 1С сохранена"
}