Цифра

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

1С регулярно опрашивает Цифру и забирает очередь заданий (task): что выгрузить из справочников и какие сущности создать. Запрос инициирует 1С, данные едут обратным потоком — в ответе. Рекомендуемая частота опроса — раз в минуту.

POST /api/check

Запрос отправляет 1С, задания приходят в ответе. Полученное задание 1С затем проводит через changeTaskStatus: сначала work, потом done или failed.

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

Параметр Тип Обязательный Описание
SecretKeystringДаСекретный ключ из настроек Цифры
Примечания
  • Других параметров метод не читает: очередь определяется ключом
  • Ключ должен принадлежать активной интеграции. Отключённая интеграция отвечает так же, как неизвестный ключ, — 403
  • Каждый успешный запрос обновляет отметку активности интеграции в Цифре — по ней видно, что 1С на связи

Задания в ответе

Ответ всегда содержит ключ Tasks. Если очередь пуста, приходит пустой массив.

Поле Тип Обязательное Описание
Примечания
  • Ключи ответа при успехе — с заглавной буквы: Tasks, Id, Task, Status, Params
  • Status в выдаче всегда new: метод отдаёт только невзятые задания. Значения work, done, failed проставляет 1С через changeTaskStatus
  • Params зависит от типа задания. У заданий выгрузки (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, очередь создания не двигается
  • Опрашивать метод чаще раза в минуту без необходимости — лишние вызовы только сжигают попытки уже выданных заданий
Запрос 1С → Цифра
{
  "SecretKey": "2akgzOCYsAxLwpNl"
}
Пример curl 1С → Цифра
curl -X POST https://1c.cifra.ai/api/check \
  -H "Content-Type: application/json" \
  -d '{"SecretKey":"2akgzOCYsAxLwpNl"}'
Ответ с заданиями Цифра → 1С
{
  "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 есть ещё поставщик, перевозчик, машина, водитель, услуги и материалы. Полный состав — на странице создания реализации.

Ответ без заданий Цифра → 1С
{
  "Tasks": []
}

Обычный ответ при пустой очереди. Ошибкой не является — 1С просто ждёт следующего опроса.

Коды ответов

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

Кода 422 у этого метода нет: входных данных, кроме ключа, метод не проверяет. Тело запроса с испорченным JSON тоже даёт 403 — ключ из него просто не прочитается.

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

ПолеТипОписание
TasksarrayОчередь заданий. Только при успехе
messagestringПричина отказа. Только при ошибке
successbooleanВсегда 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": "Произошла внутренняя ошибка"
}

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

См. также