Смена статуса задания

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

POST /api/changeTaskStatus

Задание 1С получает методом check, а затем дважды обращается к этому методу: сначала переводит задание в work, потом — в done или failed.

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

Параметр	Тип	Обязательный	Описание
`SecretKey`	string	Да	Секретный ключ
`Id`	integer	Да	ID задания из метода check
`Status`	string	Да	Новый статус задания
`Data`	object	Условно	Результат выполнения задания

Примечания

Id — целое число. Нечисловое значение отклоняется с кодом 422 и задание не меняется
Data обязательна для заданий создания сущностей и не нужна для заданий выгрузки — см. таблицу «Что возвращать по типам заданий»
Канонический вид Data — объект { "Guid": "..." }. Обёртка-массив из одного элемента [{ "Guid": "..." }] принимается для обратной совместимости, но предпочтительна объектная форма
В Guid передаётся идентификатор созданной в 1С записи в формате GUID: 22db4291-154f-11ec-973e-244bfecb4e0a. Текст, сообщение об ошибке или любое другое значение в это поле присылать нельзя — об отказе сообщает статус failed

Статусы задания

Значение	Когда отправлять	Что делает Цифра
work	Перед началом обработки задания в 1С	Блокирует повторную выдачу задания в `check`
done	Задание выполнено	Привязывает `Guid` из `Data` к сущности в Цифре. Если вместо идентификатора пришёл текст, результат отклоняется и задание уходит в `failed`
failed	Задание выполнить не удалось	Фиксирует причину; для `createApplication` и `createOrder` ставит задание заново

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

Присланный статус и Data сохраняются в задании до того, как Цифра начнёт разбирать результат — попытка видна в истории задания даже при отказе
Дальше по типу задания выполняется привязка: Guid из 1С проставляется созданной сущности (контрагенту, договору, заказу, отгрузке, зоне доставки, объекту строительства)
Пригодным значением Guid считается только идентификатор в формате GUID. Текст вместо идентификатора — например, сообщение об ошибке 1С — Цифра отклоняет: задание переводится в failed, идентификатор сущности в Цифре не меняется, а по заказам и отгрузкам в историю попадает запись «в поле Guid пришёл не идентификатор». Сам присланный ответ Цифра сохраняет в задании целиком — разбирать его текст и показывать пользователю она не берётся
Для справочных заданий пустой или отсутствующий Guid — ошибка: сущность осталась бы без ключа, и следующая синхронизация её не нашла бы. Задание переводится в failed с причиной, привязка не выполняется
failed по createApplication и createOrder запускает автоматическую перегенерацию — Цифра поставит задание заново, отдельный запрос от 1С не нужен. Ответ, отклонённый из-за непригодного Guid, перегенерацию не запускает: повтор того же задания вернул бы тот же ответ. Чтобы Цифра поставила задание заново, сообщайте о неудаче статусом failed
Сущность, удалённую в Цифре после постановки задания, привязка всё равно найдёт: Guid проставится и в удалённую запись

Структура Data

Поле Тип Обязательное Описание

Guid string Да GUID созданной записи в 1С

Applications array Нет GUID отгрузок заказа. Только для createOrder

Элемент массива Applications

Поле	Тип	Обязательное	Описание
`Id`	integer	Да	ID отгрузки в Цифре
`Guid`	string	Да	GUID отгрузки в 1С

Примечания

Регистр Guid любой, фигурные скобки вокруг значения допускаются
Пустая ссылка 1С 00000000-0000-0000-0000-000000000000 идентификатором не считается: Цифра разбирает её так же, как отсутствующий Guid
Элемент Applications с пустым или непригодным Guid пропускается — остальные отгрузки заказа привязываются как обычно

Что возвращать по типам заданий

Тип задания приходит в поле Task метода check.

Тип задания	Data	Что вернуть
`createCompany`, `createContract`, `createDeliveryZone`, `createConstructionObject`	Да	`Guid` созданной записи. Без него задание уходит в `failed`
`createOrder`	Да	`Guid` заказа и, при наличии, массив `Applications`
`createApplication`	Да	`Guid` отгрузки
`createCar`	Да	`Guid` транспортного средства
Задания выгрузки (`getCompanies` и другие `get*`)	Нет	Ничего — достаточно статуса `done`

Примечания

Для createOrder и createApplication пустой или отсутствующий Guid означает «запись в 1С ещё не создана»: задание завершается, привязка просто не выполняется. Для справочных заданий такой ответ — ошибка
Текст вместо идентификатора отклоняется у всех заданий, где Guid — ключ созданной записи: createOrder, createApplication, createCompany, createContract, createDeliveryZone, createConstructionObject. Разбор — в блоке «Логика работы»

Порядок работы с заданием

Получить задание через check
Отправить Status: "work"
Выполнить действия в 1С
Отправить Status: "done" с результатом в Data — либо Status: "failed", если выполнить не удалось

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

Пропустить статус work — задание останется в очереди и будет выдано повторно, сущность создастся в 1С дважды
Отправить done с пустым Guid — Цифра ответит 200, но задание уйдёт в failed: связь между записями не установится
Положить в Guid текст ошибки вместо идентификатора — задание уйдёт в failed, а заново Цифра его не поставит: отказ по бизнес-правилу сообщается статусом failed, и только он запускает перегенерацию
Считать done успехом по одному HTTP-коду — часть отказов приходит с кодом 200 и полем success: false

Взять задание в работу 1С → Цифра

{
  "SecretKey": "2akgzOCYsAxLwpNl",
  "Id": 15,
  "Status": "work"
}

Завершить создание сущности 1С → Цифра

{
  "SecretKey": "2akgzOCYsAxLwpNl",
  "Id": 15,
  "Status": "done",
  "Data": {
    "Guid": "22db4291-154f-11ec-973e-244bfecb4e0a"
  }
}

Завершить задание выгрузки 1С → Цифра

{
  "SecretKey": "2akgzOCYsAxLwpNl",
  "Id": 16,
  "Status": "done"
}

Для заданий getCompanies и других get* поле Data не передаётся.

Завершить createOrder с отгрузками 1С → Цифра

{
  "SecretKey": "2akgzOCYsAxLwpNl",
  "Id": 15,
  "Status": "done",
  "Data": {
    "Guid": "22db4291-154f-11ec-973e-244bfecb4e0a",
    "Applications": [
      { "Id": 101, "Guid": "9b0c8e2a-1111-11ec-973e-244bfecb4e0a" }
    ]
  }
}

Id — идентификатор отгрузки из Цифры, Guid — идентификатор из 1С.

Сообщить об ошибке 1С → Цифра

{
  "SecretKey": "2akgzOCYsAxLwpNl",
  "Id": 15,
  "Status": "failed"
}

Для createApplication и createOrder Цифра поставит задание заново автоматически.

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

curl -X POST https://1c.cifra.ai/api/changeTaskStatus \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "2akgzOCYsAxLwpNl",
    "Id": 15,
    "Status": "done",
    "Data": {"Guid": "22db4291-154f-11ec-973e-244bfecb4e0a"}
  }'

Коды ответов

Код	Описание
200	Запрос обработан. Проверьте поле `success`, если оно есть
403	Секретный ключ не найден, задание не найдено или отгрузка не найдена
422	Некорректный формат `Id`
500	Внутренняя ошибка сервиса

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

Поле	Тип	Описание
`message`	string	Результат обработки
`success`	boolean	Приходит только при отказе — со значением `false`

Ключи ответа — в нижнем регистре: message, а не Message.

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

{
  "message": "Статус обновлен"
}

{
  "message": "Задача завершена: ответ без Guid"
}

Приходит, когда для справочного задания в Data не было Guid. Запрос принят, задание переведено в failed, привязка сущности не выполнена. Похожий ответ «Задача завершена: пустые параметры» означает, что у задания в Цифре нет параметров и обработать его результат невозможно.

{
  "message": "Задача завершена: в поле Guid не идентификатор"
}

Приходит, когда вместо идентификатора в Guid пришёл текст. Запрос принят, задание переведено в failed, идентификатор сущности в Цифре не изменён, перегенерация не запускается. Присланный текст сохраняется в задании и по заказам и отгрузкам попадает в историю в Цифре.

{
  "success": false,
  "message": "Не удалось создать компанию \"Ромашка\" (имя в стоп-листе: \"ручной\", \"(не выбран)\")"
}

Часть отказов при createCompany приходит с кодом 200 и полем success: false — исторический контракт. Проверяйте это поле, а не только HTTP-код.

{
  "message": "Задача не найдена"
}

Другие тексты с этим кодом: «Секретный ключ не найден» — ключ не подошёл; «Отгрузки не существует» — при createApplication отгрузка из параметров задания уже удалена в Цифре.

{
  "message": "Некорректный формат ID"
}

Поле Id должно быть целым числом. Задание при этом не изменяется.

{
  "success": false,
  "message": "Произошла внутренняя ошибка"
}

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

См. также

Проверка заданий

check — откуда берётся Id

Двусторонний обмен данных

Как устроена система заданий

Инструкции по заданиям

Что делать в 1С по каждому типу

Заказы

order/create — приёмка заказов