Проверка наличия заданий
1С регулярно опрашивает Цифру и забирает очередь заданий (task): что выгрузить из справочников и какие сущности создать. Запрос инициирует 1С, данные едут обратным потоком — в ответе. Рекомендуемая частота опроса — раз в минуту.
Запрос отправляет 1С, задания приходят в ответе. Полученное задание 1С затем проводит через changeTaskStatus: сначала work, потом done или failed.
Параметры запроса
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
SecretKey | string | Да | Секретный ключ из настроек Цифры |
- Других параметров метод не читает: очередь определяется ключом
- Ключ должен принадлежать активной интеграции. Отключённая интеграция отвечает так же, как неизвестный ключ, —
403 - Каждый успешный запрос обновляет отметку активности интеграции в Цифре — по ней видно, что 1С на связи
Задания в ответе
Ответ всегда содержит ключ Tasks. Если очередь пуста, приходит пустой массив.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
Tasks |
Да | Задания к выполнению |
- Ключи ответа при успехе — с заглавной буквы:
Tasks,Id,Task,Status,Params Statusв выдаче всегдаnew: метод отдаёт только невзятые задания. Значенияwork,done,failedпроставляет 1С через changeTaskStatusParamsзависит от типа задания. У заданий выгрузки (get*) поле приходит со значениемnull- Даты в
Params— в форматеГГГГ-ММ-ДД ЧЧ:ММ:СС, в часовом поясе площадки
- Первым пакетом Цифра отдаёт все задания выгрузки — всё, кроме шести типов создания (
createCompany,createContract,createCar,createConstructionObject,createApplication,createOrder). Порядок — по возрастаниюId, количество не ограничено - Задания создания выдаются только тогда, когда заданий выгрузки не осталось ни в очереди, ни в работе, — и строго по одному за вызов, в порядке
Id - Отсюда порядок зависимостей: контрагент и договор, поставленные раньше реализации, уходят в 1С до неё
- Каждая выдача увеличивает счётчик попыток задания. На пятой попытке задание, оставшееся в очереди, Цифра переводит в
failedсама createApplicationиcreateOrderпосле такого отказа перегенерируются заново, с актуальными данными из Цифры. Всего поколений три: оригинал и два повтора
Типы заданий
Значение поля Task. Направление показывает, куда едут данные после того, как 1С возьмёт задание в работу.
| Тип задания | Направление | Что делает 1С |
|---|---|---|
getCompanies |
1С → Цифра | Выгружает справочник контрагентов |
getProducts |
1С → Цифра | Выгружает справочник продукции |
getCars |
1С → Цифра | Выгружает справочник транспортных средств |
getDrivers |
1С → Цифра | Выгружает справочник водителей |
getContracts |
1С → Цифра | Выгружает справочник договоров |
getInvoices |
1С → Цифра | Выгружает счета покупателям |
getConstructionObjects |
1С → Цифра | Выгружает объекты строительства |
createCompany |
Цифра → 1С | Создаёт контрагента |
createContract |
Цифра → 1С | Создаёт договор |
createCar |
Цифра → 1С | Создаёт транспортное средство |
createConstructionObject |
Цифра → 1С | Создаёт объект строительства |
createDeliveryZone |
Цифра → 1С | Создаёт зону доставки |
createApplication |
Цифра → 1С | Создаёт реализацию по отгрузке |
createOrder |
Цифра → 1С | Создаёт реализацию по заказу |
- Набор заданий зависит от настроек интеграции: часть типов у конкретной площадки не появляется
- Задания
get*параметров не имеют — 1С отправляет весь справочник методами приёмки данных - Задания создания завершаются передачей
Guidсозданной записи через changeTaskStatus createDeliveryZoneидёт в одном пакете с заданиями выгрузки, а не по одному, как остальные задания создания
- Обрабатывать задание, не переведя его в
work, — оно останется в очереди и придёт в следующем же опросе, а работа выполнится дважды - Считать, что
checkотдаёт задание один раз, — при каждой выдаче растёт счётчик попыток, и на пятой Цифра закрывает задание какfailed - Ждать заданий создания, оставив задания выгрузки незакрытыми, — пока хоть одно из них в
newилиwork, очередь создания не двигается - Опрашивать метод чаще раза в минуту без необходимости — лишние вызовы только сжигают попытки уже выданных заданий
{
"SecretKey": "2akgzOCYsAxLwpNl"
}
curl -X POST https://1c.cifra.ai/api/check \
-H "Content-Type: application/json" \
-d '{"SecretKey":"2akgzOCYsAxLwpNl"}'
{
"Tasks": [
{
"Id": 15,
"Task": "getCars",
"Status": "new",
"Params": null
},
{
"Id": 16,
"Task": "createApplication",
"Status": "new",
"Params": {
"Date": "2024-12-12 14:30:00",
"Client": {
"Id": 123,
"Guid": "22db4291-154f-11ec-973e-244bfecb4e0a",
"Name": "ООО Заказчик",
"Inn": "7604377806"
},
"Recipe": {
"Id": 45,
"Guid": "33ab5192-265g-22fc-a84f-355cgfdc5f1b",
"Name": "БСТ В25П4F200",
"Price": 4500
},
"Total": 12
}
}
]
}
Params задания createApplication показан сокращённо: в реальном payload есть ещё поставщик, перевозчик, машина, водитель, услуги и материалы. Полный состав — на странице создания реализации.
{
"Tasks": []
}
Обычный ответ при пустой очереди. Ошибкой не является — 1С просто ждёт следующего опроса.
Коды ответов
| Код | Описание |
|---|---|
| 200 | Очередь получена. Список может быть пустым |
| 403 | Секретный ключ не найден или интеграция отключена |
| 405 | Запрос отправлен методом, отличным от POST |
| 500 | Внутренняя ошибка сервиса |
Кода 422 у этого метода нет: входных данных, кроме ключа, метод не проверяет. Тело запроса с испорченным JSON тоже даёт 403 — ключ из него просто не прочитается.
Структура ответа
| Поле | Тип | Описание |
|---|---|---|
Tasks | array | Очередь заданий. Только при успехе |
message | string | Причина отказа. Только при ошибке |
success | boolean | Всегда false. Приходит не при каждой ошибке |
- Регистр ключей у успеха и у отказа разный: успех —
Tasksс заглавной, отказ —messageиsuccessсо строчной. Разбор в 1С должен учитывать оба варианта - Ответ
403состоит из одного поляmessage, безsuccess. Ориентироваться надёжнее на HTTP-код, а не на наличие поля - Успешный ответ всегда содержит
Tasks— отдельного признака успеха у метода нет
Примеры ответов
{
"Tasks": [
{
"Id": 15,
"Task": "getCars",
"Status": "new",
"Params": null
}
]
}
Развёрнутый ответ с параметрами задания разобран в табе «Примеры».
{
"Tasks": []
}
Штатный ответ. Пустой массив приходит и когда заданий нет, и когда задания создания ждут закрытия заданий выгрузки.
{
"message": "Секретный ключ не найден"
}
Один и тот же ответ на три случая: ключ передан неверно, ключ вообще не передан, интеграция в Цифре отключена.
Поля success в этом ответе нет.
{
"success": false,
"message": "Метод запроса не поддерживается"
}
Эндпоинт принимает только POST. Открытие адреса в браузере даёт именно этот ответ.
{
"success": false,
"message": "Произошла внутренняя ошибка"
}
Подробности наружу не уходят: причина фиксируется на стороне Цифры. Опрос можно продолжать — выданные ранее задания не теряются. Если ошибка повторяется, обратитесь в поддержку.