Цифра ↔ 1С

Отчёт по отгрузкам

Цифра отдаёт в 1С завершённые отгрузки (реализации) за период: состав товаров и услуг, контрагентов, транспорт, доставку и расход сырья. На основании отчёта 1С строит документы реализации.

POST /api/application/report

Запрос отправляет 1С, данные едут обратно: в ответе приходит массив Data[], по одному элементу на отгрузку. Секретный ключ определяет, отгрузки каких заводов попадут в отчёт.

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

Параметр Тип Обязательный Описание
SecretKeystringДаСекретный ключ
StartDatedatetimeДаНачало периода
EndDatedatetimeДаОкончание периода
Примечания
  • Формат даты — ГГГГ-ММ-ДД ЧЧ:ММ:СС. Точки в дате 1С (2026.04.30 00:00:00) нормализуются автоматически
  • Даты трактуются в часовом поясе завода, границы периода включительные
  • Период фильтрует отгрузки по дате создания записи в Цифре, а не по дате загрузки миксера
  • Обе границы обязательны: без StartDate или без EndDate запрос отклоняется ответом 422 и выборка не выполняется
  • Неразбираемая дата тоже завершается ответом 422; при неверном SecretKey раньше приходит 403 — ключ проверяется первым
  • Секретный ключ задаёт список заводов (MixId) и подразделение интеграции, по которому подбираются 1С-аналоги номенклатур, контрагентов и техники
Логика работы
  • Успешный ответ приходит с кодом 207, а не 200 — проверять нужно и код, и поле Success
  • В отчёт попадают только завершённые (done) и не удалённые отгрузки заводов, привязанных к ключу
  • Отгрузок за период может не быть — тогда Data приходит пустым массивом, а Success остаётся true
  • Даты в ответе конвертируются из UTC в часовой пояс завода
  • Перед отдачей Цифра подставляет 1С-аналоги номенклатур, контрагентов и техники по связям подразделения интеграции: если аналог найден, в блоке приходят его Id, Name и Guid
  • Guid в любом блоке — идентификатор уже синхронизированной с 1С сущности; пока синхронизации не было, приходит null

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

Элемент массива Data из конверта ответа — одна отгрузка. Строки со стрелкой раскрывают вложенный объект.

Поле Тип Обязательное Описание
IdintegerДаID отгрузки в Цифре
Docstring|nullНетНомер документа в программе бетонного завода
Guidstring|nullНетGUID реализации в 1С
IntegrationUnitIdinteger|nullНетID подразделения интеграции
MixIdintegerДаID бетонного завода
ShortNumberstringНетКороткий номер отгрузки
Namestring|nullНетПолный номер отгрузки
TotalfloatДаФактический объём отгрузки
TotalClientfloatДаОбъём в документах для клиента
TypestringДаТип отгрузки
StatusstringДаСтатус отгрузки
PaymentMethodstring|nullНетСпособ оплаты
DatedatetimeДаОкончание загрузки миксера
StartAtdatetime|nullНетНачало загрузки миксера
ReturnAtdatetime|nullНетВозврат машины на завод
Примечания
  • Type — delivery (доставка), take-away (самовывоз), production (производство)
  • Status — в отчёт попадают только завершённые отгрузки, поэтому фактически всегда приходит done. Полный перечень значений и то, чем опасны незавершённые отгрузки, — в разделе Статусы отгрузки
  • PaymentMethod — bankWithVAT, bankWithoutVAT, cashbox, cash, transfer; null, если способ оплаты у отгрузки не задан
  • Total и TotalClient — в кубометрах. TotalClient равен Total, если объём для документов клиента отдельно не задавали
  • Date, StartAt, ReturnAt — формат ГГГГ-ММ-ДД ЧЧ:ММ:СС. Часовой пояс определяется по первому заводу из настроек ключа и применяется ко всем строкам отчёта
  • ShortNumber — часть полного номера начиная с первой заглавной буквы: из 250801Д10-5 получается Д10-5
  • Guid отгрузки заполняется после того, как 1С отчиталась по заданию createApplication; IntegrationUnitId — только при настроенной связи с конкретным подразделением 1С
  • IntegrationUnitId есть только на верхнем уровне отгрузки: во вложенных объектах он служебный и в ответ не попадает
  • RowNumber сквозной по обеим табличным частям: сначала нумеруются строки Products, затем Services
  • VatRate — строка с процентом («20%», «0%»). При VatInPrice: true НДС уже включён в Price и Sum
  • В Products попадают строки товаров, в Services — строки услуг: перевозка, простой и работа насоса
  • Materials[].Guid — GUID связанной номенклатуры 1С, если для сырья настроена связь и у номенклатуры заполнен идентификатор; тогда Id и Name строки тоже приходят от неё. Если связи нет, приходит собственный идентификатор сырья, а Id и Name остаются от сырья Цифры
  • Собственный идентификатор сырья приходит в том виде, в каком его ведёт завод, — это может быть короткая строка вида ag11, а не GUID. Сопоставлять такое значение нужно по точному совпадению, формат не гарантирован. null в Materials[].Guid означает, что идентификатор не заполнен ни у связанной номенклатуры, ни у самого сырья
  • Materials[].CharacteristicGuid — GUID характеристики: вторая часть идентификатора, отделённая пробелом; null, если характеристики нет. Ключ приходит и у сырья со связанной номенклатурой, и у сырья без неё
  • Pumps передаётся, только если в настройках интеграции включён флаг «Передавать насосы в отгрузках» (режим отправки «по каждой отгрузке, без заказа», по умолчанию выключен). При выключенном флаге ключа Pumps в ответе нет вообще; при включённом, но без насосов у заказа, приходит пустой массив

Статусы отгрузки

Значения поля Status. Общий справочник — используется и в этом отчёте, и в массиве Applications отчёта по заказам, и в заданиях createApplication и createOrder.

Значение Название в Цифре Описание
newНоваяПлановая отгрузка, загрузка ещё не начиналась
loadingЗагрузкаИдёт загрузка миксера
deliveryДоставкаМашина в пути на объект
objectНа объектеМашина прибыла на объект
pouringЗаливкаИдёт выгрузка бетона
returnВозвращаетсяМашина возвращается на завод
doneЗавершенаОтгрузка выполнена
Реализацию в 1С создавайте только по отгрузкам в статусе done
  • done — единственный конечный статус. Только он означает, что отгрузка состоялась и её данные больше не изменятся
  • Отгрузку в статусе new проводить как реализацию не рекомендуется — она ещё не выполнена
  • Такая отгрузка может исчезнуть: при отмене, завершении или постановке заказа на паузу все отгрузки этого заказа в статусе new удаляются в Цифре. Отдельного статуса «отменена» или признака отмены в API нет — отгрузка просто перестаёт приходить в следующих заданиях и отчётах
  • Пока отгрузка не перешла в done, её данные могут измениться: объём, машина, водитель, время, состав товаров и услуг

В самих отчётах незавершённые отгрузки не встречаются — действует фильтр Status = done. В промежуточных статусах отгрузки приходят только в заданиях createApplication и createOrder, если в настройках интеграции выбран триггер «При любых изменениях».

Частые ошибки
  • Считать успехом только код 200 — отчёт отдаётся с кодом 207, и такой обработчик отбросит весь ответ
  • Разбирать ответ по ключам success и message — у отчётов конверт с заглавной буквы: Success, Message, Data
  • Считать ключ Pumps обязательным — при выключенной настройке его в ответе нет
  • Искать IntegrationUnitId внутри Recipe, Client или Products — он приходит только на верхнем уровне отгрузки
  • Ждать от периода фильтрацию по дате отгрузки — фильтр работает по дате создания записи в Цифре
  • Разбирать Materials[].Guid как GUID — у сырья без связанной номенклатуры 1С приходит его собственный идентификатор (например, ag11), и проверка формата отбросит корректную строку расхода
Запрос за период 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/application/report \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "2akgzOCYsAxLwpNl",
    "StartDate": "2024-12-01 00:00:00",
    "EndDate": "2024-12-12 23:59:59"
  }'

Ответ приходит с HTTP-кодом 207.

Ответ: одна отгрузка со всеми блоками Цифра → 1С 
{
  "Message": null,
  "Success": true,
  "Data": [
    {
      "Id": 12345,
      "Doc": "3432",
      "Guid": "22db4291-154f-11ec-973e-244bfecb4e0a",
      "IntegrationUnitId": 5,
      "MixId": 3,
      "ShortNumber": "Д10-5",
      "Name": "250801Д10-5",
      "Total": 12.0,
      "TotalClient": 11.8,
      "Type": "delivery",
      "Status": "done",
      "PaymentMethod": "bankWithVAT",
      "Date": "2024-12-09 13:00:52",
      "StartAt": "2024-12-09 12:41:40",
      "ReturnAt": "2024-12-09 13:45:10",
      "Recipe": {
        "Id": 45,
        "Guid": "33ab5192-265b-42fc-a84f-355c9fdc5f1b",
        "CharacteristicGuid": "44bc6203-376c-43dd-b95a-466d9ede6e2c",
        "Name": "БСТ В12,5П3 F50W2",
        "Price": 4500.0
      },
      "Client": {
        "Id": 123,
        "Guid": "55cd7314-487d-44ee-c06b-577e1efe7f3d",
        "Name": "ООО Заказчик Бетона",
        "Inn": "7604377806"
      },
      "Products": [
        {
          "Id": 45,
          "ServiceId": 892,
          "RowNumber": 1,
          "Guid": "66de8425-598e-45ff-d17c-688f2fef8a4e",
          "CharacteristicGuid": "77ef9536-6a9f-46aa-e28d-799a3afa9b5f",
          "Name": "БСТ В12,5П3 F50W2",
          "Price": 4500.0,
          "Sum": 54000.0,
          "Quantity": 12.0,
          "VatRate": "20%",
          "VatInPrice": true
        }
      ],
      "Services": [
        {
          "Id": 893,
          "RowNumber": 2,
          "Guid": "88fa0647-7b0a-47bb-f39e-800b4bab0c6a",
          "Name": "Доставка бетона",
          "Price": 4000.0,
          "Sum": 4000.0,
          "Quantity": 1.0,
          "VatRate": "20%",
          "VatInPrice": true
        }
      ],
      "Zone": {
        "Id": 8,
        "Guid": "99ab1758-8c1b-48cc-a40f-911c5cbc1d7b",
        "Name": "Зона 1 (до 30 км)"
      },
      "Delivery": {
        "Address": "Тула, Менделеевская улица, 12В",
        "Distance": 34.5,
        "DistanceToObjectPlan": 32.0,
        "OnObjectTime": 40.0,
        "Price": 4000.0
      },
      "Seller": {
        "Id": 10,
        "Guid": "aabc2869-9d2c-49dd-b510-a22d6dcd2e8c",
        "Name": "ООО Бетонный Завод №3",
        "Inn": "7123456789"
      },
      "Carrier": {
        "Id": 15,
        "Guid": "bbcd397a-ae3d-4aee-c621-b33e7ded3f9d",
        "Name": "ИП Перевозчиков",
        "Inn": "7198765432"
      },
      "Car": {
        "Id": 89,
        "Guid": "ccde4a8b-bf4e-4bff-d732-c44f8efe4a0e",
        "CarNumber": "В700ТК797",
        "Volume": 8.0,
        "Rent": false
      },
      "Driver": {
        "Id": 78,
        "Guid": null,
        "Name": "Иванов Петр Андреевич"
      },
      "Manager": {
        "Id": 25,
        "Name": "Петрова Анна Сергеевна",
        "Phone": "+79001234567"
      },
      "Dispatcher": {
        "Id": 31,
        "Name": "Сидоров Сергей Сергеевич",
        "Phone": "+79007654321"
      },
      "Spec": {
        "Id": 150,
        "Guid": "ddef5b9c-c05f-4c00-e843-d5509f0f5b1f",
        "CharacteristicGuid": "eeab6cad-d16a-4d11-f954-e6610a1a6c2a",
        "Name": "Добавка пластификатор"
      },
      "Contract": {
        "Id": 456,
        "Guid": "ffab7dbe-e27b-4e22-a065-f772b12b7d3b",
        "Name": "Договор №123/2024 от 01.01.2024"
      },
      "Invoice": {
        "Id": 789,
        "Guid": "aabc8ecf-f38c-4f33-b176-a883c23c8e4c",
        "Name": "Счет №456 от 05.12.2024"
      },
      "Materials": [
        {
          "Id": 16490,
          "Guid": "ag11",
          "CharacteristicGuid": null,
          "Name": "Вода",
          "TotalFormula": 1458.0,
          "TotalFact": 1451.88
        },
        {
          "Id": 16502,
          "Guid": "ccde0a1b-1c2d-4e3f-a405-b6c7d8e9f0a1",
          "CharacteristicGuid": null,
          "Name": "Цемент ЦЕМ I 42,5Н",
          "TotalFormula": 3120.0,
          "TotalFact": 3118.4
        }
      ],
      "Pumps": [
        {
          "Id": 142,
          "Guid": "bbcd9fda-a49d-4a44-c287-b994d34d9f5d",
          "Number": "В123ТК797",
          "Rent": false,
          "Name": "Насос Putzmeister 36",
          "Driver": {
            "Id": 314,
            "Guid": null,
            "Name": "Сидоров Иван Алексеевич",
            "Phone": "+79007654321"
          }
        }
      ]
    }
  ]
}

Ключ Pumps показан для случая, когда в настройках интеграции включена передача насосов. Без этой настройки ключа в ответе нет. В Materials показаны оба случая: у первой строки связанной номенклатуры 1С нет, поэтому пришёл собственный идентификатор сырья, у второй — GUID связанной номенклатуры.

Коды ответов

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

Успех приходит с кодом 207, а не 200: обработчик, который сверяет ответ строго с 200, отбросит корректный отчёт.

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

ПолеТипОписание
Messagestring|nullТекст ошибки; при успехе — null
SuccessbooleanПризнак успешной обработки
Dataarray|nullМассив отгрузок
Примечания
  • Ключи конверта — с заглавной буквы: Success, Message, Data. У приёмных методов api/*, наоборот, success и message
  • В отказе по ключу (403) поля Data нет вовсе; в ошибках, нормализованных общим обработчиком (405, 422, 500), приходит "Data": null
  • Подробности внутренних ошибок наружу не уходят — Message в этом случае содержит обезличенный текст

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

{
  "Message": null,
  "Success": true,
  "Data": [
    { "Id": 12345, "Doc": "3432", "MixId": 3, "Status": "done" }
  ]
}

Элемент массива показан сокращённо — полный состав отгрузки во вкладке Примеры.

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

Это не ошибка: за период просто нет завершённых отгрузок по заводам ключа.

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

Тот же ответ приходит, если ключ существует, но отключён. Поля 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
}

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

См. также

Расход материалов
application/materials — сырьё за период
Отчёт по заказам
orders/report — заказы с отгрузками
Заказы
order/create — приёмка заказов