Цифра ↔ 1С

Заказы

Двусторонний обмен заказами между 1С и Цифрой. Заказы могут создаваться и обновляться из 1С в Цифру через API /api/order/create, а также выгружаться из Цифры в 1С в виде отчёта через /api/orders/report.

POST /api/order/create

Приёмка заказов из 1С в Цифру. Создаёт новый заказ или обновляет существующий по GUID.

Параметры запроса

Параметр Тип Обязательный Описание
SecretKey string Да Секретный ключ
Data object Да Данные заказа
Логика работы
  • Если заказа с указанным Guid нет — создаётся новый заказ со статусом «Неподтверждённый»
  • Если заказ есть и не начат (неподтверждён, подтверждён, пауза) — обновляются все данные
  • Если заказ есть и начат — можно обновить только объём (не менее уже отгруженного/в работе)
  • Отмена возможна только для не начатых заказов (передать Status: "cancel")
  • Если сущность (контрагент, номенклатура и т.д.) не найдена по GUID — она будет создана автоматически

Структура Data

Поле Тип Обязательное Описание
GuidstringДаGUID заказа в 1С. По нему определяется, создавать или обновлять
DispatchIdintegerДаID диспетчерской в Цифре. См. список диспетчерских
TotalfloatДаОбщий объём заказа (м³)
StatusstringНетПередавать только cancel для отмены. Остальные статусы не обрабатываются
PaymentMethodstringНетbankWithVAT, bankWithoutVAT, cash, transfer
DeliveryTypestringНетdelivery, take-away. По умолчанию: delivery
DatedatetimeДаДата заказа (YYYY-MM-DD)
FirstOrderTimeDeliverystringДаВремя первой доставки (HH:MM:SS)
CommentstringНетКомментарий к заказу (для диспетчера)
CommentDriverstringНетКомментарий для водителя
Factories array<int> Нет Массив MixId заводов для привязки к заказу. См. список заводов. Если не указан — привязываются все заводы диспетчерской
Примечания
  • Если контрагент, номенклатура или другая сущность не найдена по GUID — она будет создана автоматически
  • Адрес может быть без координат
  • Объём начатого заказа не может быть меньше, чем уже отгружено + в работе + подтверждённые рейсы
  • Если передан параметр Factories — к заказу привязываются только заводы из этого списка (из числа связанных с диспетчерской). Заводы, не связанные с диспетчерской, игнорируются
  • Все операции из 1С записываются в историю заказа
POST /api/orders/report

Получение заказов из Цифры в 1С за указанный период с полной информацией о входящих в них отгрузках.

Параметры запроса

Параметр Тип Обязательный Описание
SecretKeystringДаСекретный ключ
StartDatedatetimeДаНачало периода
EndDatedatetimeДаОкончание периода
Логика работы
  • Возвращает массив Data[] с заказами за период StartDate…EndDate
  • Каждый заказ содержит вложенный массив Applications — отгрузки в рамках заказа
  • Даты конвертируются в часовой пояс завода/отгрузки
  • Поле Guid заполняется после выполнения задания createOrder на стороне 1С
Отчёт по отгрузкам (application-report) Инструкция по созданию реализации

Структура Data[]

Поле Тип Описание
IdintegerID заказа в Цифре
GuidstringID в 1С (если связь установлена)
DocstringНомер заказа
ShortNumberstringКороткий номер заказа (например: «Д10»)
TotalfloatОбщий объём заказа (м³)
Typestringdelivery, take-away
Statusstringnew, confirmed, work, done, completed, canceled
PaymentMethodstringСпособ оплаты
DeliveryTypestringТип доставки (дублирует Type)
DatedatetimeДата и время заказа с учётом часового пояса
FirstOrderTimeDeliverystringВремя первой отгрузки (HH:MM:SS)
CommentstringКомментарий диспетчера
Примечания
  • Заказ может содержать несколько отгрузок в массиве Applications
  • Поле DeliveryType дублирует значение Type для совместимости
  • Все Guid и IntegrationUnitId используются для связи с данными в 1С
  • Поле Guid заказа заполняется после выполнения задания createOrder
  • RowNumber — сквозной номер строки в табличной части: сначала Products, затем Services
  • Поле Zone может быть null, если зона доставки не определена
  • Поле ConstructionObject может отсутствовать — передачу можно отключить в настройках интеграции 1С
  • Дата и время автоматически конвертируются в часовой пояс завода/отгрузки
Пример запроса /order/create 1С → Цифра 
{
  "SecretKey": "2akgzOCYsAxLwpNl",
  "Data": {
    "Guid": "22db4291-154f-11ec-973e-244bfecb4e0a",
    "DispatchId": 1,
    "Total": 24.0,
    "DeliveryType": "delivery",
    "PaymentMethod": "bankWithVAT",
    "Date": "2024-12-09",
    "FirstOrderTimeDelivery": "08:00:00",
    "Comment": "Подъезд со стороны главного входа",
    "Factories": [42, 43],
    "Good": {
      "Guid": "33ab5192-265g-22fc-a84f-355cgfdc5f1b",
      "CharacteristicGuid": "44bc6203-376h-33gd-b95g-466dghde6g2d",
      "Name": "БСТ В25П4F200",
      "Price": 4500.0
    },
    "Client": {
      "Guid": "44cd6203-376h-33gd-b95g-466dghde6g2c",
      "Name": "ООО Заказчик",
      "Inn": "7604377806"
    },
    "Delivery": {
      "Address": "Тула, Менделеевская улица, 12В",
      "Price": 2500.0
    },
    "Seller": {
      "Guid": "88gh0647-710l-77kh-f39k-800hklhi0k6h",
      "Name": "ООО Бетонный Завод",
      "Inn": "7604123456"
    },
    "Zone": {
      "Guid": "77fg9536-609k-66jg-e28j-799gjkgh9j5g",
      "Name": "Зона 1 (до 10 км)"
    },
    "Contract": {
      "Guid": "11jk3970-043o-00nk-i62n-133knokl3n9k",
      "Name": "Договор №123 от 01.01.2024"
    }
  }
}
Пример запроса /orders/report Цифра → 1С 
{
  "SecretKey": "2akgzOCYsAxLwpNl",
  "StartDate": "2024-12-01 00:00:00",
  "EndDate": "2024-12-12 23:59:59"
}
Пример отмены заказа 1С → Цифра 
{
  "SecretKey": "2akgzOCYsAxLwpNl",
  "Data": {
    "Guid": "22db4291-154f-11ec-973e-244bfecb4e0a",
    "DispatchId": 1,
    "Status": "cancel"
  }
}
Пример ответа /orders/report Цифра → 1С 
{
  "Success": true,
  "Message": null,
  "Data": [
    {
      "Id": 567,
      "Guid": "22db4291-154f-11ec-973e-244bfecb4e0a",
      "Doc": "Z-123",
      "ShortNumber": "Д10",
      "Total": 24.0,
      "Type": "delivery",
      "Status": "done",
      "PaymentMethod": "bankWithVAT",
      "DeliveryType": "delivery",
      "Date": "2024-12-09 08:00:00",
      "FirstOrderTimeDelivery": "08:00:00",
      "Comment": "Подъезд со стороны главного входа",
      "Recipe": {
        "Id": 45,
        "Guid": "33ab5192-265g-22fc-a84f-355cgfdc5f1b",
        "CharacteristicGuid": "44bc6203-376h-33gd-b95g-466dghde6g2d",
        "Name": "БСТ В25П4F200",
        "Price": 4500.0,
        "IntegrationUnitId": 1
      },
      "Client": {
        "Id": 123,
        "Guid": "44cd6203-376h-33gd-b95g-466dghde6g2c",
        "Name": "ООО Заказчик",
        "Inn": "7604377806",
        "IntegrationUnitId": 1
      },
      "Products": [
        {
          "Id": 78, "ServiceId": 501, "RowNumber": 1,
          "Guid": "55de7314-487i-44he-c06h-577ehief7h3e",
          "CharacteristicGuid": null,
          "Name": "Пластификатор",
          "Price": 150.0, "Sum": 300.0, "Quantity": 2.0,
          "VatRate": "20%", "VatInPrice": true, "IntegrationUnitId": 1
        }
      ],
      "Services": [
        {
          "Id": 502, "GoodId": 89, "RowNumber": 2,
          "Guid": "66ef8425-598j-55if-d17i-688fijfg8i4f",
          "Name": "Доставка бетона",
          "Price": 2500.0, "Sum": 2500.0, "Quantity": 1.0,
          "VatRate": "20%", "VatInPrice": true,
          "IntegrationUnitId": 1, "TariffId": 15
        }
      ],
      "Zone": { "Id": 10, "Guid": "77fg9536-...", "Name": "Зона 1 (до 10 км)" },
      "Delivery": { "Address": "Тула, Менделеевская 12В", "Distance": 8.5, "Price": 2500.0 },
      "Seller":  { "Id": 5,  "Guid": "88gh0647-...", "Name": "ООО Бетонный Завод", "Inn": "7604123456", "IntegrationUnitId": 1 },
      "Carrier": { "Id": 12, "Guid": "99hi1758-...", "Name": "ООО Транспортная Компания", "Inn": "7604654321", "IntegrationUnitId": 1 },
      "Manager": { "Id": 25, "Name": "Иванов Иван Иванович", "Phone": "+7 (900) 123-45-67" },
      "Spec":    { "Id": 34, "Guid": "00ij2869-...", "Name": "Автобетононасос 42м", "IntegrationUnitId": 1 },
      "Contract":{ "Id": 18, "Guid": "11jk3970-...", "Name": "Договор №123", "IntegrationUnitId": 1 },
      "Invoice": { "Id": 42, "Guid": "22kl4081-...", "Name": "Счет №456", "IntegrationUnitId": 1 },
      "Applications": [
        {
          "Id": 12345, "Doc": "Z-123-1",
          "Guid": "33lm5192-265q-22pm-k84p-355mpqmn5p1m",
          "IntegrationUnitId": 1, "MixId": 1001, "ShortNumber": "Д10-1",
          "Total": 12.0, "TotalClient": 12.0,
          "Type": "delivery", "Status": "done",
          "PaymentMethod": "bankWithVAT",
          "Date": "2024-12-09 08:30:00", "StartAt": "2024-12-09 08:00:00",
          "Recipe": { "Id": 45, "Name": "БСТ В25П4F200", "Price": 4500.0 },
          "Car":    { "Id": 8, "CarNumber": "А123БВ177", "Volume": 12.0, "Rent": false },
          "Driver": { "Id": 15, "Name": "Петров Петр Петрович" },
          "Materials": []
        }
      ],
      "Pumps": [
        {
          "Id": 20, "Guid": "77pq9536-...", "Number": "Н001",
          "Rent": false, "Name": "Автобетононасос 42м Putzmeister",
          "Driver": { "Id": 30, "Name": "Александров Александр", "Phone": "+7 (900) 765-43-21" }
        }
      ],
      "ConstructionObject": {
        "Id": 101, "Name": "ЖК Солнечный, корпус 3",
        "Guid": "aabbccdd-1122-3344-5566-77889900aabb"
      }
    }
  ]
}

Ответы при создании/обновлении из 1С в Цифру

Коды ответов

КодОписание
201Заказ успешно создан
200Заказ успешно обновлён или отменён
401Ошибка ключа. Секретный ключ не найден
422Ошибка валидации или бизнес-логики
500Внутренняя ошибка сервера

Структура ответа

ПолеТипОписание
successbooleanУспешность операции
messagestringСообщение о результате
data_idintegerID записи в логах интеграции
errorsarrayМассив ошибок (при наличии)

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

{
  "success": true,
  "message": "Заказ создан (ID: 567)",
  "data_id": 12345
}
{
  "success": true,
  "message": "Заказ обновлён",
  "data_id": 12345
}
{
  "success": false,
  "message": "Секретный ключ не найден",
  "data_id": null
}
{
  "success": false,
  "message": "Отсутствуют обязательные поля: Guid, Client.Guid",
  "data_id": 12345,
  "errors": ["Guid", "Client.Guid"]
}
{
  "success": false,
  "message": "Объём (10 м³) не может быть меньше, чем уже в работе/выполнено (15 м³)",
  "data_id": 12345,
  "errors": ["Объём (10 м³) не может быть меньше, чем уже в работе/выполнено (15 м³)"]
}
{
  "success": false,
  "message": "Ошибка создания заказа: Не удалось создать компанию-покупателя "тест" (имя в стоп-листе: "ручной", "тест", "(не выбран)\", "физ.лицо")",
  "data_id": 12345
}

Также возможна общая ошибка: "Произошла ошибка: подробное описание ошибки". Компания-покупатель / продавец / перевозчик должны иметь название вне стоп-листа (ручной, тест, (не выбран), физ.лицо) — иначе заказ не будет создан.

Ответы при получении отчёта из Цифры в 1С

Коды ответов

КодОписание
200Успешно. Данные получены
401Ошибка ключа. Секретный ключ не найден
422Ошибка валидации. Неверный формат данных
500Ошибка сервера. Внутренняя ошибка обработки

Структура ответа /orders/report

ПолеТипОписание
SuccessbooleanУспешность операции
MessagestringСообщение (null при успехе)
DataarrayМассив заказов за период. Структура — в табе «Из Цифры в 1С»

Полный пример ответа /orders/report — в табе Примеры.

См. также

Список диспетчерских
Для получения DispatchId
Список заводов
Для получения MixId (Factories)
Создание контрагентов
company/create
Создание продукции
product/create
Отчёт по отгрузкам
application-report
Отчёт по заказам
orders-report (отдельная страница)