DataSales Integration API для 1С

Документация для интеграторов и клиентов DataSales по подключению учётной системы 1С к платформе мобильных торговых агентов DataSales.

Версия: 1.7 · Базовый URL: https://datasales.kg/api/integration/1c · Формат: JSON · Auth: X-Company-Token

Оглавление

1. О сервисе
2. Что даёт интеграция с 1С
3. Архитектура обмена
4. Подключение клиента (онбординг)
5. Авторизация
6. Конвенции API
7. Формат ответов и ошибок
8. Проверка подключения
9. Импорт справочников из 1С
10. Выгрузка документов в 1С
11. Подтверждение обработки документов
12. Журнал синхронизации
13. Рекомендуемый сценарий обмена
14. Best practices интеграции
15. Лимиты и тайминги
16. Диагностика типовых проблем
17. Полный список методов
18. Поддержка

1. О сервисе

DataSales — облачный SaaS-сервис для управления мобильными торговыми агентами. Полевые сотрудники работают в мобильном приложении: оформляют заказы, принимают оплаты и возвраты, делают визиты к торговым точкам.

Integration 1C API — официальный HTTP-интерфейс DataSales для двусторонней синхронизации с учётной системой клиента (1С или аналогичной).

API спроектирован так, чтобы вашей учётной системе нужно было реализовать только один компонент — обмен с DataSales по HTTPS. Никакого прямого взаимодействия учётной системы с мобильными устройствами агентов не требуется.

2. Что даёт интеграция с 1С

После настройки обмена вы получаете:

В DataSales из 1С:

• актуальный каталог категорий и товаров;
• справочник типов цен;
• цены товаров по типам цен;
• справочник складов;
• остатки товаров в разрезе складов;
• справочник организаций / подразделений компании;
• структуру торговых точек (папки / районы);
• список торговых точек со статусами активности и привязанным типом цены;
• долги торговых точек в разрезе организаций.

Из DataSales в 1С:

• заказы, созданные агентами в полях;
• принятые оплаты (наличные и безналичные);
• возвраты товара;
• факты визитов агентов к торговым точкам с геолокацией.

Бонусом:

• журнал всех обменов с временными метками и payload'ами для аудита и поддержки;
• изоляция данных вашей компании от других клиентов DataSales на уровне API;
• идемпотентность всех операций — повторная отправка одних и тех же данных безопасна.

3. Архитектура обмена

┌──────────────────┐                ┌──────────────────┐                ┌──────────┐
│ Мобильное прило- │   Mobile API   │     DataSales    │ Integration    │          │
│ жение агентов    │ ◄──────────►   │     Backend      │   1C API       │   1С     │
│ (заказы, оплаты, │                │  (БД, журнал,    │ ◄────────────► │          │
│ возвраты, визиты)│                │   изоляция)      │                │          │
└──────────────────┘                └──────────────────┘                └──────────┘

Ключевые принципы:

• 1С не общается напрямую с мобильными устройствами агентов.
• Мобильные устройства не общаются напрямую с 1С.
• DataSales — единственный посредник и источник истины для обеих сторон.
• 1С — активная сторона: сама отправляет справочники и сама забирает документы по расписанию.

Такая схема снимает с интегратора всю сложность работы с мобильным трафиком, оффлайном агентов, конфликтами при одновременном редактировании и т.д.

Новая модель цен и остатков:

products                 — карточка номенклатуры
price_types              — справочник типов цен
product_prices           — цены номенклатуры по типам цен
warehouses               — склады компании
product_stocks           — остатки номенклатуры по складам
organizations            — подразделения компании
products.organization_external_1c_id -> organizations.external_1c_id
trade_outlets            — торговые точки с привязанным типом цены
trade_outlets.price_type_external_1c_id -> price_types.external_1c_id

Доступы агентов к районам и складам настраиваются не через 1С, а через web-админку компании. Мобильное приложение использует эти настройки для фильтрации торговых точек и расчёта суммарных остатков.

4. Подключение клиента (онбординг)

Шаг 1. Регистрация компании

Менеджер DataSales создаёт для вас компанию в системе и присылает вам:

• X-Company-Token — секретный токен компании для всех запросов API;
• company_external_1c_id — UUID вашей компании в DataSales;
• срок действия доступа (если ограничен).

⚠ Токен — это секрет. Не публикуйте его в репозиториях, логах и не передавайте третьим лицам. При компрометации обратитесь в поддержку для ротации.

Шаг 2. Проверка соединения

Выполните пинг (раздел 8). Если API отвечает success: true — соединение и токен валидны.

Шаг 3. Первичная загрузка справочников

Отправьте в DataSales справочники в строго следующем порядке (из-за внешних связей):

1. Категории товаров → /product-categories/batch-upsert
2. Организации / подразделения компании → /organizations/batch-upsert
3. Товары → /products/batch-upsert
4. Типы цен → /price-types/batch-upsert
5. Цены товаров → /product-prices/batch-upsert
6. Склады → /warehouses/batch-upsert
7. Остатки товаров по складам → /product-stocks/batch-upsert
8. Папки / районы торговых точек → /outlet-folders/batch-upsert
9. Торговые точки → /trade-outlets/batch-upsert
10. Долги торговых точек по организациям → /trade-outlet-debts/batch-upsert

Если товары ссылаются на организацию, организации должны быть загружены до товаров. Если торговые точки ссылаются на тип цены, типы цен должны быть загружены до торговых точек. Если цены товаров ссылаются на тип цены и товар, сначала должны быть загружены товары и типы цен. Если остатки ссылаются на склад и товар, сначала должны быть загружены товары и склады. Если долги ссылаются на торговую точку и организацию, сначала должны быть загружены торговые точки и организации.

Шаг 4. Настройка регулярного обмена

В своей 1С настройте регламентные задания:

• Периодически (например, каждые 30 минут) — обновление справочников теми же batch-методами. Повторные отправки безопасны.
• Периодически (например, каждые 5 минут) — забор pending-документов из DataSales (заказы, оплаты, возвраты, визиты).
• После обработки документа в 1С — отправка callback'а статуса в DataSales.

Готово — обмен настроен.

5. Авторизация

API использует токен компании, передаваемый в HTTP-заголовке.

Обязательные заголовки для каждого запроса:

X-Company-Token: <ваш токен>
Accept: application/json
Content-Type: application/json

Пример:

X-Company-Token: cmp_alpha_2026_demo_token_001

Что делает API при получении запроса:

1. Извлекает токен из заголовка X-Company-Token.
2. Находит вашу компанию.
3. Проверяет, что компания активна и срок доступа не истёк.
4. Все дальнейшие операции выполняются строго в рамках вашей компании.

Изоляция данных: даже если вы укажете в запросе UUID, принадлежащий другой компании, API не позволит ни прочитать, ни изменить чужие данные.

6. Конвенции API

• Транспорт: HTTPS, метод GET для чтения, POST для создания/обновления.
• Формат данных: JSON в теле запроса и ответа.
• Кодировка: UTF-8.
• Даты: строка в формате YYYY-MM-DD HH:MM:SS (московское/локальное серверное время) или YYYY-MM-DD для полей-дат.
• Идентификаторы: UUID v4/v5 (поля с суффиксом _external_1c_id).
• Денежные суммы и количество: строки с точкой как разделителем ("125.50", "2.000") — чтобы не терять точность.
• Пагинация: current_page, per_page, total, last_page. По умолчанию 100, максимум 200 записей на страницу.

7. Формат ответов и ошибок

Успешный ответ

{
  "success": true,
  "data": {
    /* полезная нагрузка */
  }
}

Ошибка

{
  "success": false,
  "code": "ERROR_CODE",
  "message": "Понятное человекочитаемое сообщение."
}

Ошибка валидации

{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "Ошибка валидации входных данных.",
  "errors": {
    "items.0.external_1c_id": [
      "Поле external_1c_id обязательно."
    ]
  }
}

Общие коды ошибок

8. Проверка подключения

8.1. Ping

Минимальный запрос для проверки, что API доступен и токен валиден.

GET /api/integration/1c/ping

curl -X GET "https://datasales.kg/api/integration/1c/ping" \
  -H "Accept: application/json" \
  -H "X-Company-Token: cmp_alpha_2026_demo_token_001"

Ответ:

{
  "success": true,
  "data": {
    "service": "DataSales Integration 1C API",
    "prefix": "/api/integration/1c",
    "status": "ok",
    "authenticated": true,
    "company_external_1c_id": "6290a6fd-f204-5a62-965d-ca231f94f3fa",
    "server_time": "2026-05-15 21:00:00"
  }
}

8.2. Информация о компании

Возвращает данные о вашей компании, как они видны в DataSales.

GET /api/integration/1c/company

curl -X GET "https://datasales.kg/api/integration/1c/company" \
  -H "Accept: application/json" \
  -H "X-Company-Token: cmp_alpha_2026_demo_token_001"

Ответ:

{
  "success": true,
  "data": {
    "company": {
      "external_1c_id": "6290a6fd-f204-5a62-965d-ca231f94f3fa",
      "name": "ООО Альфа",
      "contacts": {},
      "status": "active",
      "agent_limit": 10,
      "access_expires_at": "2027-01-01 00:00:00",
      "created_at": "2026-01-15 10:00:00",
      "updated_at": "2026-05-10 12:00:00"
    }
  }
}

9. Импорт справочников из 1С

Все методы импорта работают как batch-upsert по единому шаблону: вы отправляете массив элементов, DataSales создаёт новые и обновляет существующие.

Важно: после изменения архитектуры цены и остатки вынесены из карточки товара в отдельные сущности. Поэтому /products/batch-upsert передаёт только номенклатуру, /product-prices/batch-upsert — цены по типам цен, /product-stocks/batch-upsert — остатки по складам.

9.0. Общие правила batch-upsert

Шаблон URL:

POST /api/integration/1c/{entity}/batch-upsert

Формат запроса:

{
  "items": [ /* до 1000 элементов */ ]
}

Гарантии API:

1. Максимум 1000 элементов в одном запросе.
2. Каждый элемент обрабатывается независимо.
3. Ошибка в одном элементе не отменяет остальные — валидные элементы будут сохранены.
4. Идемпотентность. Повторная отправка тех же данных не создаёт дубликаты:
   • запись найдена → update;
   • не найдена → create;
   • данные не изменились → skipped.
5. Для большинства справочников поиск ведётся по external_1c_id в рамках вашей компании.
6. Для типов цен поиск ведётся по price_types.external_1c_id.
7. Для цен товаров поиск ведётся по связке product_external_1c_id + price_type_external_1c_id.
8. Для остатков товаров поиск ведётся по связке product_external_1c_id + warehouse_external_1c_id.

Формат ответа:

{
  "success": true,
  "data": {
    "summary": {
      "total": 2,
      "created": 1,
      "updated": 1,
      "skipped": 0,
      "errors": 0
    },
    "items": [
      {
        "index": 0,
        "external_1c_id": "11111111-1111-4111-8111-111111111111",
        "status": "created",
        "id": 6
      },
      {
        "index": 1,
        "external_1c_id": "22222222-2222-4222-8222-222222222222",
        "status": "updated",
        "id": 7
      }
    ]
  }
}

Возможные значения status элемента: created, updated, skipped, error.

9.1. Категории товаров

POST /api/integration/1c/product-categories/batch-upsert

Пример:

{
  "items": [
    {
      "external_1c_id": "11111111-1111-4111-8111-111111111111",
      "name": "Напитки",
      "sort_order": 10
    }
  ]
}

9.2. Товары и номенклатура

POST /api/integration/1c/products/batch-upsert

Товары теперь являются только карточками номенклатуры. Цена и остаток больше не обновляются этим методом.

Поля, которые больше не передаются в этом методе:

Особенности обновления:

• Если поле не передано при update — текущее значение сохраняется.
• Если category_external_1c_id = null явно — связь с категорией очищается.
• Если category_external_1c_id передан и не равен null, категория должна существовать в вашей компании.
• Если organization_external_1c_id = null явно — связь с организацией очищается.
• Если organization_external_1c_id передан и не равен null, организация должна существовать в вашей компании.
• Для артикула основное поле — sku. Если интеграция отправляет article, artikul или vendor_code, система сохранит первое непустое значение в products.sku.
• Для минимального остатка основное поле — minimum_stock_quantity. Если интеграция отправляет minimum_stock или min_stock, система сохранит первое переданное значение как индивидуальный порог товара.
• Если minimum_stock_quantity не передан, индивидуальный порог товара не изменяется. Это позволяет вручную заполнять порог в админке и не перетирать его пакетами интеграции без этого поля.
• Если minimum_stock_quantity = null явно, индивидуальный порог товара очищается и товар использует порог по умолчанию из раздела «Кастомизация» → «Настройки».
• Для кратности заказа основное поле — order_multiple_quantity. Также можно отправлять алиасы order_multiple, order_step_quantity, order_step, quantity_step или multiplicity. Если поле не передано, текущая кратность не изменяется.
• Числовые поля minimum_stock_quantity и order_multiple_quantity можно передавать числом или строкой. Допускается дробный разделитель . или ,, пробелы-разделители разрядов будут удалены перед валидацией.
• Если 1С продолжит передавать price или stock_quantity в этом методе, эти значения не должны использоваться как источник цен и остатков.

Пример:

{
  "items": [
    {
      "external_1c_id": "33333333-3333-4333-8333-333333333333",
      "sku": "TEST-1C-001",
      "name": "Тестовый товар",
      "description": "Краткое описание товара для карточки в каталоге дилера.",
      "category_external_1c_id": "11111111-1111-4111-8111-111111111111",
      "organization_external_1c_id": "66666666-6666-4666-8666-666666666666",
      "unit": "шт",
      "image_url": "/assets/img/test-product.jpg",
      "barcode": "4600000000001",
      "minimum_stock_quantity": 5,
      "order_multiple_quantity": 1,
      "status": "active"
    }
  ]
}

Дополнительные коды ошибок элемента:

9.3. Типы цен

POST /api/integration/1c/price-types/batch-upsert

Типы цен нужны для хранения нескольких цен одной и той же номенклатуры: розничной, оптовой, акционной и т.д.

Таблица price_types не хранит company_external_1c_id. Связь с компанией определяется через цены товаров:

price_types -> product_prices -> products -> company_external_1c_id

Пример:

{
  "items": [
    {
      "external_1c_id": "00000000-0000-4000-8000-000000000001",
      "name": "Розничная цена",
      "is_default": true,
      "status": "active"
    },
    {
      "external_1c_id": "00000000-0000-4000-8000-000000000002",
      "name": "Оптовая цена",
      "is_default": false,
      "status": "active"
    }
  ]
}

Особенности:

• Ключ идемпотентности: external_1c_id.
• Если is_default = true, backend может снять признак is_default с остальных типов цен.
• Типы цен нужно загрузить до цен товаров и до торговых точек, если торговые точки ссылаются на тип цены.

Дополнительные коды ошибок элемента:

9.4. Цены номенклатуры по типам цен

POST /api/integration/1c/product-prices/batch-upsert

Метод импортирует цены товаров по типам цен. Одна номенклатура может иметь несколько цен.

Пример:

{
  "items": [
    {
      "product_external_1c_id": "33333333-3333-4333-8333-333333333333",
      "price_type_external_1c_id": "00000000-0000-4000-8000-000000000001",
      "price": 125.50,
      "status": "active"
    },
    {
      "product_external_1c_id": "33333333-3333-4333-8333-333333333333",
      "price_type_external_1c_id": "00000000-0000-4000-8000-000000000002",
      "price": 110.00,
      "status": "active"
    }
  ]
}

Особенности:

• Ключ идемпотентности: product_external_1c_id + price_type_external_1c_id.
• Товар должен существовать в вашей компании.
• Тип цены должен быть заранее загружен через /price-types/batch-upsert.
• В таблице product_prices не хранится company_external_1c_id.
• Принадлежность к компании проверяется через products.company_external_1c_id.

Дополнительные коды ошибок элемента:

9.5. Склады

POST /api/integration/1c/warehouses/batch-upsert

Метод импортирует склады компании.

Пример:

{
  "items": [
    {
      "external_1c_id": "10000000-0000-4000-8000-000000000001",
      "name": "Основной склад",
      "address": "Бишкек, ул. Логистическая 10",
      "sort_order": 10,
      "status": "active"
    }
  ]
}

Особенности:

• Ключ идемпотентности: company_external_1c_id + external_1c_id.
• company_external_1c_id backend подставляет сам из X-Company-Token.
• Если склад больше не используется, 1С может передать его со статусом inactive.

Дополнительные коды ошибок элемента:

9.6. Остатки номенклатуры по складам

POST /api/integration/1c/product-stocks/batch-upsert

Метод импортирует остатки товаров в разрезе складов.

Пример:

{
  "items": [
    {
      "product_external_1c_id": "33333333-3333-4333-8333-333333333333",
      "warehouse_external_1c_id": "10000000-0000-4000-8000-000000000001",
      "stock_quantity": 120.000,
      "status": "active"
    },
    {
      "product_external_1c_id": "33333333-3333-4333-8333-333333333333",
      "warehouse_external_1c_id": "10000000-0000-4000-8000-000000000002",
      "stock_quantity": 30.000,
      "status": "active"
    }
  ]
}

Особенности:

• Ключ идемпотентности: product_external_1c_id + warehouse_external_1c_id.
• Товар должен существовать в вашей компании.
• Склад должен существовать в вашей компании.
• В таблице product_stocks не хранится company_external_1c_id.
• Принадлежность к компании проверяется через products и warehouses.
• В мобильном приложении общий остаток товара считается не по всем складам компании, а только по складам, доступным конкретному агенту через agent_warehouses.

Дополнительные коды ошибок элемента:

9.7. Организации / подразделения компании

POST /api/integration/1c/organizations/batch-upsert

Метод импортирует организации компании. В текущей архитектуре организация — это подразделение компании, к которому может быть привязана номенклатура.

Пример:

{
  "items": [
    {
      "external_1c_id": "66666666-6666-4666-8666-666666666666",
      "name": "ОсОО «Ромашка Бишкек»",
      "status": "active"
    }
  ]
}

Особенности:

• Ключ идемпотентности: company_external_1c_id + external_1c_id.
• company_external_1c_id backend подставляет сам из X-Company-Token.
• Если организация больше не используется, 1С может передать её со статусом inactive.
• Товары могут ссылаться на организацию через organization_external_1c_id.

Дополнительные коды ошибок элемента:

9.8. Папки / районы торговых точек

POST /api/integration/1c/outlet-folders/batch-upsert

Пример:

{
  "items": [
    {
      "external_1c_id": "55555555-5555-4555-8555-555555555555",
      "name": "Северный район",
      "sort_order": 10
    }
  ]
}

9.9. Торговые точки

POST /api/integration/1c/trade-outlets/batch-upsert

Особенности:

• Сумма долга торговой точки не обновляется этим методом. Используйте отдельный метод /trade-outlet-debts/batch-upsert.
• Лимит долга остаётся атрибутом торговой точки и обновляется этим методом.
• Статус торговых точек обновляется этим же методом.
• Если folder_external_1c_id передан, район должен существовать в вашей компании.
• Если price_type_external_1c_id передан, тип цены должен существовать в price_types.
• Если price_type_external_1c_id = null или пустая строка — привязка типа цены очищается.
• Если price_type_external_1c_id не передан при update — текущее значение сохраняется.
• discount_percent необязателен. Если поле не передано при создании торговой точки, сохраняется 0.
• Если discount_percent не передан при update — текущее значение сохраняется.

Пример:

{
  "items": [
    {
      "external_1c_id": "77777777-7777-4777-8777-777777777777",
      "folder_external_1c_id": "55555555-5555-4555-8555-555555555555",
      "price_type_external_1c_id": "00000000-0000-4000-8000-000000000001",
      "name": "Магазин «Ромашка»",
      "address": "Бишкек, ул. Тестовая, 1",
      "contact_person": "Иванов И.И.",
      "phone": "+996 555 777777",
      "geo_coordinates": "42.8750000,74.6000000",
      "debt_limit": 5000,
      "discount_percent": 7.5,
      "status": "active",
      "last_visit_at": "2026-05-15 10:30:00"
    }
  ]
}

Дополнительные коды ошибок элемента:

9.10. Долги торговых точек по организациям

POST /api/integration/1c/trade-outlet-debts/batch-upsert

Метод импортирует задолженность торговых точек в разрезе организаций. Одна торговая точка может иметь отдельную сумму долга по каждой организации.

Пример:

{
  "items": [
    {
      "trade_outlet_external_1c_id": "77777777-7777-4777-8777-777777777777",
      "organization_external_1c_id": "66666666-6666-4666-8666-666666666666",
      "debt_amount": 1500.50,
      "status": "active"
    }
  ]
}

Особенности:

• Ключ идемпотентности: company_external_1c_id + trade_outlet_external_1c_id + organization_external_1c_id.
• Торговая точка должна быть предварительно загружена через /trade-outlets/batch-upsert.
• Организация должна быть предварительно загружена через /organizations/batch-upsert.
• Кредитный лимит передаётся в методе торговых точек /trade-outlets/batch-upsert, а не в этом методе.

Дополнительные коды ошибок элемента:

9.11. Что не импортируется через Integration 1C API

Доступы агентов к районам и складам через интеграционный API не передаются.

Не реализуются методы:

POST /api/integration/1c/agent-outlet-folders/batch-upsert
POST /api/integration/1c/agent-warehouses/batch-upsert

Этими настройками управляет web-админка компании.

Мобильное приложение при этом учитывает эти доступы:

• торговые точки фильтруются по районам, привязанным к агенту;
• суммарный остаток товара считается только по складам, привязанным к агенту.

10. Выгрузка документов в 1С

Документы создаются мобильным приложением агентов и сохраняются в DataSales с признаком sync_status = pending. Ваша 1С забирает их HTTP-запросами.

10.0. Общая схема

Для каждой документной сущности (orders, payments, returns) реализованы три метода:

GET  /api/integration/1c/{entity}                          # список
GET  /api/integration/1c/{entity}/{external_1c_id}         # карточка
POST /api/integration/1c/{entity}/{external_1c_id}/status  # подтверждение

Для визитов (outlet-visits) подтверждение не требуется (см. 10.4).

Также поддерживается обратная загрузка документов из 1С в DataSales:

POST /api/integration/1c/orders/batch-upsert
POST /api/integration/1c/payments/batch-upsert
POST /api/integration/1c/returns/batch-upsert

Формат пакетного ответа совпадает со справочниками: summary и items. Если торговая точка, организация, агент или дилер не найдены в текущей компании, конкретная строка получает status = skipped, а весь пакет продолжает обрабатываться. Ошибки валидации остаются status = error.

Стандартные фильтры списка

Черновики (draft) и отменённые документы (cancelled) по умолчанию не выдаются — это не документы для обработки в 1С.

10.1. Заказы

Список заказов

GET /api/integration/1c/orders

curl -X GET "https://datasales.kg/api/integration/1c/orders?sync_status=pending" \
  -H "Accept: application/json" \
  -H "X-Company-Token: cmp_alpha_2026_demo_token_001"

Карточка заказа

GET /api/integration/1c/orders/{external_1c_id}

Ответ (включает позиции заказа):

{
  "success": true,
  "data": {
    "order": {
      "external_1c_id": "7342e706-cd5a-5370-bcb9-c309f84be2c8",
      "order_number": "8832-TX",
      "company_external_1c_id": "6290a6fd-f204-5a62-965d-ca231f94f3fa",
      "outlet_external_1c_id": "aef6e08e-3eee-5730-8519-58422999988e",
      "agent_external_1c_id": "c77267d1-f4ec-5125-9849-e8986ad6ae6a",
      "organization_external_1c_id": "66666666-6666-4666-8666-666666666666",
      "source": "mobile",
      "dealer_external_1c_id": null,
      "status": "created",
      "sync_status": "pending",
      "total_amount": "575.40",
      "delivery_date": "2026-05-15T00:00:00",
      "delivery_method": "delivery",
      "delivery_address": "Bishkek, warehouse 7",
      "payment_method": "account",
      "comment": "Комментарий",
      "created_at": "2026-05-10T12:20:00",
      "updated_at": "2026-05-10T12:24:00",
      "items": [
        {
          "id": 1,
          "product_external_1c_id": "89ac79cd-8600-5e2a-9052-be6367510ec2",
          "product_name": "Velocity Pro-X Industrial",
          "quantity": "2.000",
          "price": "124.50",
          "total_amount": "249.00"
        }
      ]
    }
  }
}

Новые поля источника заказа:

Загрузка заказов из 1С

POST /api/integration/1c/orders/batch-upsert

Метод используется для обратной интеграции документов из 1С в DataSales. Запись создаётся или обновляется по паре company_external_1c_id + external_1c_id. При обновлении позиции заказа заменяются переданным набором.

{
  "items": [
    {
      "external_1c_id": "7342e706-cd5a-5370-bcb9-c309f84be2c8",
      "order_number": "DLR-0000206",
      "outlet_external_1c_id": "aef6e08e-3eee-5730-8519-58422999988e",
      "agent_external_1c_id": null,
      "dealer_external_1c_id": "d77267d1-f4ec-5125-9849-e8986ad6ae6a",
      "organization_external_1c_id": "66666666-6666-4666-8666-666666666666",
      "source": "dealer",
      "status": "accepted_by_1c",
      "sync_status": "success",
      "total_amount": 575.40,
      "delivery_date": "2026-06-30T00:00:00",
      "delivery_method": "delivery",
      "delivery_address": "Bishkek, warehouse 7",
      "payment_method": "account",
      "document_date": "2026-06-30T18:00:00",
      "comment": "Комментарий",
      "items": [
        {
          "product_external_1c_id": "89ac79cd-8600-5e2a-9052-be6367510ec2",
          "product_name": "Пиво ARASAN мягкое свежее бан. 0,45 л",
          "quantity": 2,
          "price": 287.70,
          "total_amount": 575.40
        }
      ]
    }
  ]
}

При обратной загрузке заказов DataSales ведёт историю изменений заказа для дилерского портала. В историю попадают только реальные изменения:

• создание заказа;
• смена status;
• изменение состава items.

Если 1С повторно отправила тот же заказ без изменения статуса и состава, новая запись истории не создаётся.

10.2. Оплаты

Список оплат

GET /api/integration/1c/payments

Дополнительный фильтр: payment_type ∈ {cash, cashless, all}.

Загрузка принятой оплаты из 1С

POST /api/integration/1c/payments

Метод используется для дилерского портала: оплата уже принята в 1С и передаётся в DataSales для отображения во взаиморасчётах дилера. Запись создаётся или обновляется по паре company_external_1c_id + external_1c_id и сохраняется с sync_status = success.

Тело запроса:

{
  "external_1c_id": "2410662b-66b4-565c-ac87-a1e6d95edfc1",
  "outlet_external_1c_id": "46115f6d-34d7-56bf-a56b-732efb6d6f59",
  "agent_external_1c_id": null,
  "organization_external_1c_id": "66666666-6666-4666-8666-666666666666",
  "amount": 5000,
  "payment_type": "cashless",
  "reference_number": "ПП №4471",
  "comment": "Оплата по счёту",
  "payment_date": "2026-06-13 10:30:00"
}

Ответ:

{
  "success": true,
  "data": {
    "action": "created",
    "payment": {
      "external_1c_id": "2410662b-66b4-565c-ac87-a1e6d95edfc1",
      "organization_external_1c_id": "66666666-6666-4666-8666-666666666666",
      "amount": "5000.00",
      "payment_type": "cashless",
      "reference_number": "ПП №4471",
      "sync_status": "success"
    }
  }
}

Карточка оплаты

GET /api/integration/1c/payments/{external_1c_id}

Ответ:

{
  "success": true,
  "data": {
    "payment": {
      "external_1c_id": "2410662b-66b4-565c-ac87-a1e6d95edfc1",
      "company_external_1c_id": "6290a6fd-f204-5a62-965d-ca231f94f3fa",
      "outlet_external_1c_id": "46115f6d-34d7-56bf-a56b-732efb6d6f59",
      "agent_external_1c_id": "c77267d1-f4ec-5125-9849-e8986ad6ae6a",
      "organization_external_1c_id": "66666666-6666-4666-8666-666666666666",
      "amount": "500.00",
      "payment_type": "cash",
      "reference_number": "P-001",
      "comment": "Наличные",
      "sync_status": "pending",
      "created_at": "2026-05-13T07:28:00",
      "updated_at": "2026-05-13T07:28:00"
    }
  }
}

Пакетная загрузка оплат из 1С

POST /api/integration/1c/payments/batch-upsert

Используется, когда 1С передаёт в DataSales уже принятые оплаты. Платёж создаётся или обновляется по паре company_external_1c_id + external_1c_id.

{
  "items": [
    {
      "external_1c_id": "2410662b-66b4-565c-ac87-a1e6d95edfc1",
      "outlet_external_1c_id": "46115f6d-34d7-56bf-a56b-732efb6d6f59",
      "agent_external_1c_id": null,
      "organization_external_1c_id": "66666666-6666-4666-8666-666666666666",
      "amount": 5000,
      "payment_type": "cashless",
      "reference_number": "ПП №4471",
      "comment": "Оплата по счёту",
      "payment_date": "2026-06-30T18:00:00"
    }
  ]
}

organization_external_1c_id нужно передавать, если оплата закрывает долг торговой точки в разрезе организации.

10.3. Возвраты

Список возвратов

GET /api/integration/1c/returns

Карточка возврата

GET /api/integration/1c/returns/{external_1c_id}

Ответ (включает позиции возврата с причинами):

{
  "success": true,
  "data": {
    "return": {
      "external_1c_id": "79c27b9b-2491-5eda-ab11-bf0f279c9de7",
      "company_external_1c_id": "6290a6fd-f204-5a62-965d-ca231f94f3fa",
      "outlet_external_1c_id": "aef6e08e-3eee-5730-8519-58422999988e",
      "agent_external_1c_id": "c77267d1-f4ec-5125-9849-e8986ad6ae6a",
      "organization_external_1c_id": "66666666-6666-4666-8666-666666666666",
      "status": "created",
      "sync_status": "pending",
      "total_amount": "2140.00",
      "comment": "Комментарий",
      "created_at": "2026-05-13T07:15:00",
      "updated_at": "2026-05-13T07:15:00",
      "items": [
        {
          "id": 1,
          "product_external_1c_id": "e79677df-4121-5228-800b-143b930eee6a",
          "product_name": "Молоко цельное 1L",
          "quantity": "2.000",
          "price": "560.00",
          "total_amount": "1120.00",
          "reason": "damaged_package"
        }
      ]
    }
  }
}

Загрузка возвратов из 1С

POST /api/integration/1c/returns/batch-upsert

Метод создаёт или обновляет возвраты по паре company_external_1c_id + external_1c_id. При обновлении позиции возврата заменяются переданным набором.

{
  "items": [
    {
      "external_1c_id": "79c27b9b-2491-5eda-ab11-bf0f279c9de7",
      "outlet_external_1c_id": "aef6e08e-3eee-5730-8519-58422999988e",
      "agent_external_1c_id": "c77267d1-f4ec-5125-9849-e8986ad6ae6a",
      "organization_external_1c_id": "66666666-6666-4666-8666-666666666666",
      "status": "accepted_by_1c",
      "sync_status": "success",
      "total_amount": 1120,
      "return_date": "2026-06-30T18:00:00",
      "comment": "Возврат из 1С",
      "items": [
        {
          "product_external_1c_id": "e79677df-4121-5228-800b-143b930eee6a",
          "product_name": "Молоко цельное 1L",
          "quantity": 2,
          "price": 560,
          "total_amount": 1120,
          "reason": "damaged_package"
        }
      ]
    }
  ]
}

organization_external_1c_id необязателен. Если поле передано, но организация не найдена в текущей компании, строка будет пропущена со статусом skipped.

agent_external_1c_id для обратного импорта из 1С можно не передавать. При обновлении существующего возврата пустое/отсутствующее значение не перетирает сохранённую привязку.

10.4. Визиты торговых агентов

Список визитов

GET /api/integration/1c/outlet-visits

⚠ Подтверждение статуса для визитов не реализовано. Чтобы избежать повторной обработки, 1С должна забирать визиты по периоду или хранить у себя дату последнего обработанного визита.

Фильтры:

Пример:

curl -X GET "https://datasales.kg/api/integration/1c/outlet-visits?date_from=2026-05-10%2000:00:00&date_to=2026-05-13%2023:59:59" \
  -H "Accept: application/json" \
  -H "X-Company-Token: cmp_alpha_2026_demo_token_001"

Карточка визита

GET /api/integration/1c/outlet-visits/{external_1c_id}

Ответ:

{
  "success": true,
  "data": {
    "outlet_visit": {
      "external_1c_id": "f15fbc0f-5360-5165-b435-e97aad4a4c79",
      "company_external_1c_id": "6290a6fd-f204-5a62-965d-ca231f94f3fa",
      "outlet_external_1c_id": "c21ab827-b8f6-57f2-a5c3-0ad92ace5649",
      "agent_external_1c_id": "c77267d1-f4ec-5125-9849-e8986ad6ae6a",
      "check_in_at": "2026-05-13 07:40:00",
      "check_in_geo_coordinates": "42.8765000,74.6012000",
      "comment": "Комментарий",
      "created_at": "2026-05-13 07:40:00"
    }
  }
}

11. Подтверждение обработки документов

После того как ваша 1С обработала документ (создала на его основе свой документ или, наоборот, не смогла обработать), вы должны вернуть результат в DataSales. Это нужно, чтобы документ перестал отдаваться в выборке sync_status = pending.

Единый формат callback'а

POST /api/integration/1c/orders/{external_1c_id}/status
POST /api/integration/1c/payments/{external_1c_id}/status
POST /api/integration/1c/returns/{external_1c_id}/status

Успешная обработка

{
  "status": "accepted_by_1c",
  "one_c_document_number": "ЗК-000001",
  "processed_at": "2026-05-15T12:30:00"
}

Ошибка обработки на стороне 1С

{
  "status": "sync_error",
  "error_message": "Не найден договор клиента",
  "processed_at": "2026-05-15T12:35:00"
}

Что произойдёт в DataSales

Поля one_c_document_number и error_message сохраняются в журнале синхронизации для аудита.

Идемпотентность и защиты

• Повторный callback с тем же финальным состоянием безопасен и возвращает action = skipped.
• Нельзя перевести уже принятый документ (accepted_by_1c) обратно в sync_error — это финальное состояние. Если действительно нужно «откатить» — обратитесь в поддержку.
• Подтверждение черновиков и отменённых документов запрещено.

Возможные ошибки callback'а

12. Журнал синхронизации

DataSales ведёт детальный журнал всех обменов с вашей компанией. Журнал доступен по API и в админ-панели DataSales.

12.1. Список записей

GET /api/integration/1c/sync/logs

Фильтры:

12.2. Одна запись

GET /api/integration/1c/sync/logs/{id}

12.3. Формат записи журнала

{
  "id": 1,
  "company_external_1c_id": "uuid",
  "entity_type": "order",
  "entity_external_1c_id": "uuid",
  "direction": "to_1c",
  "status": "success",
  "request_payload": { /* тело запроса */ },
  "response_payload": { /* тело ответа или summary */ },
  "error_message": null,
  "created_at": "2026-05-10T12:24:00"
}

12.4. Когда журнал особенно полезен

• При расследовании, почему документ «застрял» в pending.
• Для аудита: что и когда было передано в обе стороны.
• Для службы поддержки клиента — все payload'ы сохраняются в исходном виде.

13. Рекомендуемый сценарий обмена

13.1. Первичная загрузка (один раз при старте)

Порядок важен — последующие справочники ссылаются на предыдущие:

1. POST /product-categories/batch-upsert
2. POST /organizations/batch-upsert
3. POST /products/batch-upsert
4. POST /price-types/batch-upsert
5. POST /product-prices/batch-upsert
6. POST /warehouses/batch-upsert
7. POST /product-stocks/batch-upsert
8. POST /outlet-folders/batch-upsert
9. POST /trade-outlets/batch-upsert
10. POST /trade-outlet-debts/batch-upsert

Почему именно так:

• товары могут ссылаться на категории;
• цены товаров ссылаются на товары и типы цен;
• остатки товаров ссылаются на товары и склады;
• товары могут ссылаться на организации;
• торговые точки могут ссылаться на районы и типы цен.
• долги торговых точек ссылаются на торговые точки и организации.

13.2. Регулярная синхронизация справочников

Настройте в 1С регламентное задание, которое периодически (например, раз в 30–60 минут) повторно отправляет те же batch-запросы. Идемпотентность гарантирует, что неизменившиеся записи будут пропущены, изменённые — обновлены, новые — созданы.

Рекомендуемый состав регулярной синхронизации:

POST /api/integration/1c/product-categories/batch-upsert
POST /api/integration/1c/organizations/batch-upsert
POST /api/integration/1c/products/batch-upsert
POST /api/integration/1c/price-types/batch-upsert
POST /api/integration/1c/product-prices/batch-upsert
POST /api/integration/1c/warehouses/batch-upsert
POST /api/integration/1c/product-stocks/batch-upsert
POST /api/integration/1c/outlet-folders/batch-upsert
POST /api/integration/1c/trade-outlets/batch-upsert
POST /api/integration/1c/trade-outlet-debts/batch-upsert

13.3. Регулярный забор документов

Отдельное регламентное задание (например, каждые 5 минут):

GET /api/integration/1c/orders?sync_status=pending
GET /api/integration/1c/payments?sync_status=pending
GET /api/integration/1c/returns?sync_status=pending

Для визитов — забор по периоду со сдвигом по обработанной дате:

GET /api/integration/1c/outlet-visits?date_from=...&date_to=...

13.4. Подтверждение обработки

После того как 1С обработала каждый забранный документ:

POST /api/integration/1c/orders/{id}/status
POST /api/integration/1c/payments/{id}/status
POST /api/integration/1c/returns/{id}/status

13.5. Полная схема

 1. Проверка подключения (GET /ping)
 2. 1С отправляет справочники: категории, организации, товары, типы цен, цены, склады, остатки, районы, торговые точки, долги торговых точек
 3. DataSales сохраняет справочники и фиксирует операции в журнале
 4. Администратор компании настраивает доступы агентов к районам и складам в web-админке
 5. Мобильные агенты получают актуальные справочники
 6. Для торговой точки мобильное приложение знает price_type_external_1c_id
 7. Для товара мобильное приложение выбирает цену по типу цены торговой точки
 8. Остаток товара в мобильном приложении считается по складам, доступным агенту
 9. Агент в полях создаёт заказ / оплату / возврат / визит
10. Документ попадает в DataSales со sync_status = pending
11. 1С забирает pending-документы
12. 1С обрабатывает их у себя (создаёт документы 1С)
13. 1С отправляет callback статуса
14. DataSales обновляет sync_status / status
15. Документ больше не выдаётся в pending-выборке

14. Best practices интеграции

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

2. Не отправляйте цены и остатки в метод товаров. /products/batch-upsert отвечает только за карточку номенклатуры. Цены отправляйте через /product-prices/batch-upsert, остатки — через /product-stocks/batch-upsert.

3. Используйте идемпотентность как преимущество. Не пытайтесь определять «изменилось/не изменилось» на своей стороне — просто отправляйте всё. DataSales сам разберётся: повторная отправка одинаковых данных даст skipped и не нагрузит систему.

4. Один batch — до 1000 элементов. Если ваш каталог больше — режьте на части. Слишком маленькие batch'и (по 1–5 элементов) тоже неэффективны — лучше группировать по 100–500.

5. Обрабатывайте ответ batch'а по элементам. Даже если success: true, в summary.errors может быть ненулевое число. Смотрите статус каждого элемента в data.items.

6. Следите за зависимостями. Товар с организацией не импортируется, если организация не загружена. Цена товара не импортируется, если не загружены товар и тип цены. Остаток не импортируется, если не загружены товар и склад. Торговая точка с типом цены не импортируется, если тип цены не загружен. Долг торговой точки не импортируется, если не загружены торговая точка и организация.

7. Callback'и подтверждения — обязательны. Без них документ останется в pending и будет повторно отдаваться при каждом запросе списка. Это не сломает интеграцию, но засорит трафик и журнал.

8. Не подтверждайте документы вслепую. Если 1С реально не смогла обработать документ — присылайте sync_error с понятным error_message. Это поможет администратору компании увидеть проблему в журнале.

9. Используйте sync_status=error для дашборда мониторинга. Регулярно (например, раз в час) запрашивайте журнал с фильтром status=error и оповещайте ответственного.

10. Храните на своей стороне UUID документа. При callback'е и при повторном запросе карточки документа используйте именно external_1c_id, а не внутренний ID DataSales.

11. Не передавайте company_external_1c_id в теле запросов. Компания всегда определяется по X-Company-Token — это сделано для безопасности.

12. Берегите токен. При утечке немедленно обратитесь в поддержку для ротации.

15. Лимиты и тайминги

Если ваш каталог не помещается в один batch — отправляйте несколько batch'ей последовательно. Идемпотентность гарантирует целостность.

Рекомендованная частота регламентных заданий: справочники — раз в 30–60 минут, документы — раз в 5–10 минут.

16. Диагностика типовых проблем

При обращении в поддержку всегда указывайте: время запроса (с часовым поясом), URL, X-Company-Token в маскированном виде (например, cmp_alpha_***_001), полный текст ответа.

17. Полный список методов

# Проверка подключения
GET  /api/integration/1c/ping
GET  /api/integration/1c/company

# Импорт справочников из 1С
POST /api/integration/1c/product-categories/batch-upsert
POST /api/integration/1c/organizations/batch-upsert
POST /api/integration/1c/products/batch-upsert
POST /api/integration/1c/price-types/batch-upsert
POST /api/integration/1c/product-prices/batch-upsert
POST /api/integration/1c/warehouses/batch-upsert
POST /api/integration/1c/product-stocks/batch-upsert
POST /api/integration/1c/outlet-folders/batch-upsert
POST /api/integration/1c/trade-outlets/batch-upsert
POST /api/integration/1c/trade-outlet-debts/batch-upsert

# Заказы
POST /api/integration/1c/orders/batch-upsert
GET  /api/integration/1c/orders
GET  /api/integration/1c/orders/{external_1c_id}
POST /api/integration/1c/orders/{external_1c_id}/status

# Оплаты
POST /api/integration/1c/payments
POST /api/integration/1c/payments/batch-upsert
GET  /api/integration/1c/payments
GET  /api/integration/1c/payments/{external_1c_id}
POST /api/integration/1c/payments/{external_1c_id}/status

# Возвраты
POST /api/integration/1c/returns/batch-upsert
GET  /api/integration/1c/returns
GET  /api/integration/1c/returns/{external_1c_id}
POST /api/integration/1c/returns/{external_1c_id}/status

# Визиты агентов
GET  /api/integration/1c/outlet-visits
GET  /api/integration/1c/outlet-visits/{external_1c_id}

# Журнал синхронизации
GET  /api/integration/1c/sync/logs
GET  /api/integration/1c/sync/logs/{id}

Всего: 29 методов.

Не входят в Integration 1C API и настраиваются через web-админку компании:

POST /api/integration/1c/agent-outlet-folders/batch-upsert
POST /api/integration/1c/agent-warehouses/batch-upsert

18. Поддержка

• Email поддержки: указать адрес
• Часы работы поддержки: указать
• SLA на ответ: указать
• Личный кабинет / админ-панель: ссылка на админку DataSales для вашей компании
• Связь с менеджером: контакты

При обращении в поддержку, пожалуйста, прикладывайте:

1. Время запроса с указанием часового пояса.
2. URL и метод (GET/POST).
3. Полный текст ответа от API (включая code и message).
4. ID записи в журнале синхронизации, если применимо.
5. Маскированный токен компании (cmp_alpha_***_001) — не отправляйте полный токен.

Документ описывает публичный коммерческий API DataSales для интеграции с 1С. Изменения версии API анонсируются заранее. Обратная совместимость в рамках мажорной версии гарантируется.