Расход материалов

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

POST /api/application/materials

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

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

Параметр	Тип	Обязательный	Описание
`SecretKey`	string	Да	Секретный ключ
`StartDate`	datetime	Да	Начало периода
`EndDate`	datetime	Да	Окончание периода

Примечания

Формат даты — ГГГГ-ММ-ДД ЧЧ:ММ:СС. Точки в дате нормализуются: 2024.12.01 00:00:00 равнозначно 2024-12-01 00:00:00
Границы периода включаются в выборку
Время трактуется в часовом поясе завода и переводится в UTC на стороне Цифры — пересчитывать его в 1С не нужно
Пустое или неразбираемое значение даты приводит к ответу 500: частичного результата не будет
SecretKey задаёт список заводов — в отчёт попадают только их замесы

Логика работы

В расчёт идут замесы, созданные в границах периода на заводах секретного ключа
Расход суммируется по материалу: строки замесов и рецептов схлопываются в одну строку на материал
Если для сырья настроена связь с номенклатурой 1С, в ответ уходят Id, Name и Guid именно этой номенклатуры — так строки отчёта сходятся с учётом в 1С
Если связи нет, строка приходит с данными сырья Цифры, а в Guid — собственный идентификатор сырья
Материал без товара в справочнике Цифры в отчёт не попадает
TotalFormula и TotalFact округляются до двух знаков после запятой
Период без замесов — не ошибка: Цифра возвращает пустой Data

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

Массив материалов в ответе. Вложенных объектов нет — все поля плоские.

Поле	Тип	Обязательное	Описание
`Id`	integer	Да	ID материала
`Guid`	string\|null	Нет	Идентификатор сырья
`Name`	string	Да	Наименование материала
`TotalFormula`	float	Да	Расход по рецепту
`TotalFact`	float	Да	Фактический расход

Примечания

Id — идентификатор связанной номенклатуры 1С, если для сырья настроена связь; иначе идентификатор сырья в Цифре
Guid — GUID связанной номенклатуры 1С, если для сырья настроена связь и у номенклатуры заполнен идентификатор; тогда Id и Name строки тоже приходят от неё. Если связи нет, приходит собственный идентификатор сырья, а Id и Name остаются от сырья Цифры
Собственный идентификатор сырья приходит в том виде, в каком его ведёт завод, — это может быть короткая строка вида ag11, а не GUID. Сопоставлять такое значение нужно по точному совпадению, формат не гарантирован. null в Guid означает, что идентификатор не заполнен ни у связанной номенклатуры, ни у самого сырья
Идентификатор приходит одной строкой целиком, как он записан в Цифре: этот метод не отделяет GUID характеристики от GUID номенклатуры, и ключа CharacteristicGuid в ответе нет. В Отгрузках те же данные разнесены по двум полям — обработчики этих двух методов не взаимозаменяемы
Name — наименование сырья (Цемент, Вода, Песок и т. п.); при наличии связанной номенклатуры 1С подставляется её наименование
TotalFormula — плановое количество по рецептуре, TotalFact — фактически отвешенное. Расхождение между ними — норма, а не признак ошибки
Единица измерения в ответе не передаётся — отдельного поля под неё в Data нет

Частые ошибки

Считать успехом только код 200 — успешный ответ приходит с кодом 207, и такой обработчик примет его за отказ
Разбирать ответ по ключам в нижнем регистре — у этого метода конверт Success/Message/Data
Разбирать Guid как GUID — у сырья без связанной номенклатуры 1С приходит его собственный идентификатор (например, ag11), и проверка формата отбросит корректную строку расхода
Отправить пустые StartDate/EndDate — вместо пустого списка вернётся 500

Запрос за период Цифра → 1С

{
  "SecretKey": "2akgzOCYsAxLwpNl",
  "StartDate": "2024-12-01 00:00:00",
  "EndDate": "2024-12-12 23:59:59"
}

Ответ с расходом материалов Цифра → 1С

{
  "Message": null,
  "Success": true,
  "Data": [
    {
      "Id": 1,
      "Guid": "22db4291-154f-11ec-973e-244bfecb4e0a",
      "Name": "Цемент ПЦ500",
      "TotalFormula": 450,
      "TotalFact": 452.5
    },
    {
      "Id": 2,
      "Guid": "33ab5192-265g-22fc-a84f-355cgfdc5f1b",
      "Name": "Вода",
      "TotalFormula": 180,
      "TotalFact": 181.2
    },
    {
      "Id": 3,
      "Guid": "ag11",
      "Name": "Песок",
      "TotalFormula": 650,
      "TotalFact": 648.8
    }
  ]
}

HTTP-код успешного ответа — 207. У третьего материала связанной номенклатуры 1С нет, поэтому в Guid пришёл собственный идентификатор сырья — короткая строка, а не GUID.

Пример curl Цифра → 1С

curl -X POST https://1c.cifra.ai/api/application/materials \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "2akgzOCYsAxLwpNl",
    "StartDate": "2024-12-01 00:00:00",
    "EndDate": "2024-12-12 23:59:59"
  }'

Коды ответов

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

Успех приходит с кодом 207, а не 200: проверяйте поле Success, а не только HTTP-код.

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

Поле	Тип	Описание
`Success`	boolean	Признак успешной обработки
`Message`	string	Текст ошибки; при успехе `null`
`Data`	array	Массив материалов; при ошибке `null` или отсутствует

Ключи ответа — с заглавной буквы: Success, Message, Data, а не success/message, как у методов приёма данных. Состав полей элемента Data — в табе Из Цифры в 1С.

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

{
  "Message": null,
  "Success": true,
  "Data": [
    {
      "Id": 1,
      "Guid": "22db4291-154f-11ec-973e-244bfecb4e0a",
      "Name": "Цемент ПЦ500",
      "TotalFormula": 450,
      "TotalFact": 452.5
    }
  ]
}

Единственный успешный исход метода. Кода 200 он не возвращает.

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

Пустой Data — не ошибка: за период на заводах ключа не было замесов либо у их материалов не заполнено сырьё.

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

Ключ не найден или отключён. Поля Data в этом ответе нет — его добавляют только ответы общего обработчика ошибок.

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

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

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

Этим же кодом отвечают пустые и неразбираемые StartDate/EndDate. Подробности наружу не уходят — причина фиксируется на стороне Цифры.

См. также

Отгрузки

application/report — отгрузки за период

Заказы

orders/report — заказы за период

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

factories/list — заводы секретного ключа