Цифра ↔ 1С

Отчёт по заказам

Цифра отдаёт в 1С завершённые заказы за период — с составом заказа, участниками сделки и вложенным массивом отгрузок. Метод опрашивает 1С, когда нужно закрыть период реализациями.

POST /api/orders/report

1С отправляет период, Цифра возвращает массив заказов Data[]. Тот же эндпоинт описан на странице создания заказов — здесь его структура разобрана полностью.

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

Параметр Тип Обязательный Описание
SecretKeystringДаСекретный ключ
StartDatedatetimeДаНачало периода
EndDatedatetimeДаОкончание периода
Примечания
  • Формат дат — ГГГГ-ММ-ДД ЧЧ:ММ:СС. Запись 1С через точки (2026.04.30 00:00:00) тоже принимается: разделитель нормализуется на стороне сервиса
  • Обе границы включительно, сравнение идёт по дате отгрузки заказа
  • StartDate и EndDate трактуются в московском времени (GMT+3) независимо от часового пояса завода, а даты в ответе приходят уже в поясе завода
  • Обе границы обязательны: без StartDate или без EndDate запрос отклоняется ответом 422 и выборка не выполняется
  • Ключ проверяется первым — при неверном SecretKey приходит 403 ещё до разбора дат
  • Неразбираемая дата (например «вчера») до фильтра не доходит: запрос завершается ответом 422
Логика работы
  • В выборку попадают заказы заводов, привязанных к SecretKey, у которых дата отгрузки лежит в периоде
  • Отдаются только завершённые заказы — Status всегда completed. Заказы в работе, отменённые и черновики в отчёт не попадают
  • Внутри заказа Applications содержит только выполненные (done) и не удалённые отгрузки; заказ без таких отгрузок вернётся с пустым массивом. В задании createOrder этот же массив приходит с отгрузками в любом статусе — см. Статусы отгрузки
  • Guid заказа заполняется после того, как 1С выполнит задание createOrder; до этого приходит null
  • Перед отдачей Цифра сверяет Guid вложенных сущностей с интеграционной единицей ключа: чужой Guid обнуляется, а при наличии связи подставляется 1С-аналог — сразу Id, Name и Guid одним блоком
  • Если заказов за период нет, приходит 200 с пустым Data, а не ошибка
Отчёт по отгрузкам Расход материалов Инструкция по созданию реализации

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

Один элемент массива — один заказ. «Обязательное» означает, что ключ всегда присутствует в ответе; значение при этом может быть null.

Поле Тип Обязательное Описание
IdintegerДаID заказа в Цифре
Guidstring|nullДаGUID заказа в 1С
DocstringДаНомер заказа
ShortNumberstringДаКороткий номер заказа
Namestring|nullДаПолное имя заказа
TotalfloatДаОбъём заказа, м³
TypestringДаТип отгрузки
StatusstringДаСтатус заказа
PaymentMethodstringДаСпособ оплаты
DeliveryTypestringДаТип доставки
DatedatetimeДаДата и время заказа
FirstOrderTimeDeliverystringДаВремя первой отгрузки
Commentstring|nullДаКомментарий диспетчера
Примечания
  • Status заказа в этом отчёте всегда completed, Status отгрузки — всегда done: другие статусы в выборку не попадают. В задании createOrder тот же массив Applications приходит с отгрузками в любом статусе — незавершённые могут измениться или исчезнуть, см. Статусы отгрузки
  • Type и DeliveryType — одно и то же значение (delivery, take-away); DeliveryType оставлен для совместимости
  • Date заказа собирается из даты отгрузки и времени первой отгрузки, FirstOrderTimeDelivery — то же время в формате ЧЧ:ММ:СС; обе величины уже в часовом поясе завода
  • ShortNumber — хвост поля Name начиная с первой заглавной буквы: из «250801Д10» получается «Д10»
  • Служебный IntegrationUnitId во вложенных блоках заказа (Recipe, Client, Seller, Carrier, Products, Services, Contract, Invoice) не приходит — он вырезается перед отдачей. Связь с 1С устанавливается по Guid
  • CharacteristicGuid — вторая часть soft_id номенклатуры, отделённая пробелом; null, если у товара нет характеристики. В Services ключ появляется только тогда, когда GUID удалось разрешить по тарифу или номенклатуре
  • RowNumber проставляется сквозной нумерацией по всей выборке отчёта: сначала нумеруются строки Products всех заказов, затем строки Services. Внутри одного заказа номера возрастают, но не обязательно идут подряд и не обязательно начинаются с единицы
  • Application в строке Products или Services — та же отгрузка, что и в массиве Applications, если строка привязана к конкретной отгрузке; у строк уровня заказа приходит null
  • Ненайденная связь приходит объектом-заглушкой с Id: 0 и null в остальных полях, а не null вместо объекта. Исключение — Zone: если зона доставки не задана, приходит null
  • ConstructionObject приходит пустым массивом [], если CRM-проект к заказу не привязан. Ключ отсутствует целиком, если в настройках интеграционной единицы выключена передача объектов строительства (по умолчанию включена)
  • Materials у отгрузок этот отчёт не наполняет — всегда приходит пустым массивом. Фактический расход материалов отдаёт метод application/materials
Частые ошибки
  • Искать IntegrationUnitId внутри Recipe, Client, Products или Services — ключа в ответе нет, сопоставление идёт по Guid
  • Считать период в часовом поясе завода — границы StartDate и EndDate разбираются в московском времени, поэтому у заводов в других поясах края периода смещаются
  • Не передать StartDate или EndDate — запрос отклоняется ответом 422, отчёт не строится
  • Ждать в отчёте заказ, который ещё не закрыт, — до перехода в completed заказ не выгружается, даже если отгрузки по нему уже выполнены
Запрос отчёта за период Цифра → 1С 
{
  "SecretKey": "2akgzOCYsAxLwpNl",
  "StartDate": "2024-12-01 00:00:00",
  "EndDate": "2024-12-12 23:59:59"
}
Пример curl Цифра → 1С 
curl -X POST https://1c.cifra.ai/api/orders/report \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "2akgzOCYsAxLwpNl",
    "StartDate": "2024-12-01 00:00:00",
    "EndDate": "2024-12-12 23:59:59"
  }'

1С принимает и запись даты через точки: 2024.12.01 00:00:00.

Полный ответ с одним заказом Цифра → 1С 
{
  "Message": null,
  "Success": true,
  "Data": [
    {
      "Id": 567,
      "Guid": "22db4291-154f-11ec-973e-244bfecb4e0a",
      "Doc": "Z-123",
      "ShortNumber": "Д10",
      "Name": "250801Д10",
      "Total": 24.0,
      "Type": "delivery",
      "Status": "completed",
      "PaymentMethod": "bankWithVAT",
      "DeliveryType": "delivery",
      "Date": "2024-12-09 08:00:00",
      "FirstOrderTimeDelivery": "08:00:00",
      "Comment": "Подъезд со стороны главного входа",
      "Recipe": {
        "Id": 45,
        "Guid": "33ab5192-265a-11ec-a84f-355cbfdc5f1b",
        "CharacteristicGuid": "44bc6203-376b-11ec-b95c-466dbcde6d2d",
        "Name": "БСТ В25П4F200",
        "Price": 4500.0
      },
      "Client": {
        "Id": 123,
        "Guid": "44cd6203-376b-11ec-b95c-466dbcde6c2c",
        "Name": "ООО Заказчик",
        "Inn": "7604377806"
      },
      "Products": [
        {
          "Id": 78,
          "ServiceId": 501,
          "RowNumber": 1,
          "Guid": "55de7314-487c-11ec-c06d-577ebcef7e3e",
          "CharacteristicGuid": null,
          "Name": "Пластификатор",
          "Price": 150.0,
          "Sum": 300.0,
          "Quantity": 2.0,
          "VatRate": "20%",
          "VatInPrice": true,
          "Application": null
        }
      ],
      "Services": [
        {
          "Id": 502,
          "RowNumber": 2,
          "Guid": "66ef8425-598d-11ec-d17e-688fbcfa8f4f",
          "CharacteristicGuid": null,
          "Name": "Доставка бетона",
          "Price": 2500.0,
          "Sum": 2500.0,
          "Quantity": 1.0,
          "VatRate": "20%",
          "VatInPrice": true,
          "Application": null
        }
      ],
      "Zone": {
        "Id": 10,
        "Guid": "77fa9536-609e-11ec-e28f-799abcda9a5a",
        "Name": "Зона 1 (до 10 км)"
      },
      "Delivery": {
        "Address": "Тула, Менделеевская улица, 12В",
        "Price": 2500.0
      },
      "Seller": {
        "Id": 5,
        "Guid": "88ab0647-710f-11ec-f39a-800bcdea0b6b",
        "Name": "ООО Бетонный Завод",
        "Inn": "7604123456"
      },
      "Carrier": {
        "Id": 12,
        "Guid": "99bc1758-821a-11ec-a40b-911cdefb1c7c",
        "Name": "ООО Транспортная Компания",
        "Inn": "7604654321"
      },
      "Manager": {
        "Id": 25,
        "Name": "Иванов Иван Иванович",
        "Phone": "+7 (900) 123-45-67"
      },
      "Dispatcher": {
        "Id": 31,
        "Name": "Сидоров Сергей Сергеевич",
        "Phone": "+7 (900) 765-43-21"
      },
      "Spec": {
        "Id": 34,
        "Guid": "00cd2869-932b-11ec-b51c-022defac2d8d",
        "CharacteristicGuid": null,
        "Name": "Автобетононасос 42м",
        "IntegrationUnitId": 1
      },
      "Contract": {
        "Id": 18,
        "Guid": "11de3970-043c-11ec-c62d-133efabd3e9e",
        "Name": "Договор №123 от 01.01.2024"
      },
      "Invoice": {
        "Id": 42,
        "Guid": "22ef4081-154d-11ec-d73e-244fabce4f0f",
        "Name": "Счет №456"
      },
      "Applications": [
        {
          "Id": 12345,
          "Doc": "Z-123-1",
          "Guid": "33fa5192-265e-11ec-e84f-355abcdf5a1a",
          "IntegrationUnitId": 1,
          "MixId": 1001,
          "ShortNumber": "Д10-1",
          "Name": "250801Д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:45:00",
          "ReturnAt": "2024-12-09 10:05:00",
          "Recipe": {
            "Id": 45,
            "Guid": "33ab5192-265a-11ec-a84f-355cbfdc5f1b",
            "CharacteristicGuid": "44bc6203-376b-11ec-b95c-466dbcde6d2d",
            "Name": "БСТ В25П4F200",
            "Price": 4500.0
          },
          "Client": {
            "Id": 123,
            "Guid": "44cd6203-376b-11ec-b95c-466dbcde6c2c",
            "Name": "ООО Заказчик",
            "Inn": "7604377806"
          },
          "Products": [],
          "Services": [],
          "Zone": {
            "Id": 10,
            "Guid": "77fa9536-609e-11ec-e28f-799abcda9a5a",
            "Name": "Зона 1 (до 10 км)"
          },
          "Delivery": {
            "Address": "Тула, Менделеевская улица, 12В",
            "Distance": 8.5,
            "DistanceToObjectPlan": 8.2,
            "OnObjectTime": 30.0,
            "Price": 1250.0
          },
          "Seller": {
            "Id": 5,
            "Guid": "88ab0647-710f-11ec-f39a-800bcdea0b6b",
            "Name": "ООО Бетонный Завод",
            "Inn": "7604123456"
          },
          "Carrier": {
            "Id": 12,
            "Guid": "99bc1758-821a-11ec-a40b-911cdefb1c7c",
            "Name": "ООО Транспортная Компания",
            "Inn": "7604654321"
          },
          "Car": {
            "Id": 8,
            "Guid": "44ab6203-376f-11ec-f95a-466bcdea6b2b",
            "CarNumber": "А123БВ177",
            "Volume": 12.0,
            "Rent": false
          },
          "Driver": {
            "Id": 15,
            "Guid": null,
            "Name": "Петров Петр Петрович"
          },
          "Manager": {
            "Id": 25,
            "Name": "Иванов Иван Иванович",
            "Phone": "+7 (900) 123-45-67"
          },
          "Dispatcher": {
            "Id": 31,
            "Name": "Сидоров Сергей Сергеевич",
            "Phone": "+7 (900) 765-43-21"
          },
          "Spec": {
            "Id": 34,
            "Guid": "00cd2869-932b-11ec-b51c-022defac2d8d",
            "CharacteristicGuid": null,
            "Name": "Автобетононасос 42м"
          },
          "Contract": {
            "Id": 18,
            "Guid": "11de3970-043c-11ec-c62d-133efabd3e9e",
            "Name": "Договор №123 от 01.01.2024"
          },
          "Invoice": {
            "Id": 42,
            "Guid": "22ef4081-154d-11ec-d73e-244fabce4f0f",
            "Name": "Счет №456"
          },
          "Materials": []
        }
      ],
      "Pumps": [],
      "ConstructionObject": {
        "Id": 101,
        "Name": "ЖК Солнечный, корпус 3",
        "Guid": "aabbccdd-1122-3344-5566-77889900aabb"
      }
    }
  ]
}

Заказ может содержать несколько отгрузок — здесь показана одна. Строки Products и Services уровня заказа приходят с "Application": null; у строки, привязанной к отгрузке, в этом поле лежит тот же объект, что и в массиве Applications.

Коды ответов

КодОписание
200Отчёт сформирован. Data может быть пустым массивом
403Секретный ключ не найден
405Запрос отправлен методом, отличным от POST
422Период выборки не указан или дата в неверном формате
500Внутренняя ошибка сервиса

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

ПолеТипОписание
SuccessbooleanПризнак успешной обработки
Messagestring|nullТекст ошибки; при успехе null
Dataarray|nullМассив заказов
Примечания
  • Ключи конверта — с заглавной буквы: Success, Message, Data. Методы приёмки данных (api/*/create, changeTaskStatus) отвечают в нижнем регистре — разбор у них разный
  • В ответе 403 ключа Data нет вообще: приходят только Message и Success. В остальных ошибках Data присутствует со значением null
  • Отказ всегда сопровождается HTTP-кодом ошибки — ответов 200 с Success: false у этого метода нет

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

{
  "Message": null,
  "Success": true,
  "Data": []
}

Пустой Data означает, что за период нет завершённых заказов — это не ошибка. Ответ с заполненным заказом целиком показан в табе «Примеры».

{
  "Message": "Секретный ключ не найден",
  "Success": false
}

Тот же ответ приходит, когда SecretKey вообще не передан. Ключа Data в этом ответе нет.

{
  "Success": false,
  "Message": "Метод запроса не поддерживается",
  "Data": null
}

Эндпоинт принимает только POST с телом в JSON.

{
  "Success": false,
  "Message": "Не указан период выборки: обязательны StartDate и EndDate",
  "Data": null
}

Приходит, когда в запросе нет StartDate или EndDate. Достаточно одной пропущенной границы — выборка не выполняется, отчёт не строится.

{
  "Success": false,
  "Message": "Некорректный формат даты: StartDate и EndDate ожидаются в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС",
  "Data": null
}

Дата передана, но сервис не смог её разобрать — например «вчера». Запись 1С через точки (2024.12.01 00:00:00) к этой ошибке не приводит: разделитель нормализуется.

{
  "Success": false,
  "Message": "Произошла внутренняя ошибка",
  "Data": null
}

Подробности наружу не уходят — причина фиксируется на стороне Цифры. Если ошибка повторяется, обратитесь в поддержку и укажите запрошенный период.

См. также

Создание заказов
order/create — приёмка заказов из 1С
Отчёт по отгрузкам
application/report — структура отгрузки
Список диспетчерских
dispatches/list — откуда берётся часовой пояс