Одобрить пачку предложений

Цикл по одиночным одобрениям: право, политика и журнал — на каждое предложение; один отказ пачку не валит. Либо ids, либо batch_id (задание пачки). Больше 2000 — 413, ничего не одобрено. Задание ещё идёт — 409. Больше 50 предложений (или async: true) — 202 и задание вида approve_batch. Ошибки — единым видом с полем error.code (ApproveError): 400 onec_rejected (1С отклонила документ), 403 missing_permission / onec_read_only / policy_blocked / key_write_limit, 404 proposal_not_found, 409 wrong_status / payload_changed / job_running / onec_conflict (объект в 1С занят или такой документ уже есть) / onec_not_found, 422 has_blockers (error.blockers), 503 onec_unavailable / onec_failed (документ не записан, повторите позже) / write_unknown (1С не ответила на запись: неизвестно, создан ли документ; error.marker — метка для поиска в 1С, повтор безопасен — сначала найдёт документ по метке; повтор раньше чем через 2 минуты после обрыва в 1С не пишет и отвечает тем же кодом с error.retry_after и Retry-After — сколько секунд ждать). В ошибке записи есть error.status и error.document: «записан черновиком, но не проведён» видно без карточки, повтор «Записать» проведёт тот же документ.

Idempotency-Key: повтор с тем же ключом и тем же телом отдаёт прежний ответ (статус и тело) с заголовком Idempotent-Replayed: true и ничего не делает второй раз; тот же ключ с другим адресом или телом — 422 (error.code = idempotency_key_reused); первый запрос с этим ключом ещё идёт — 409 (error.code = idempotency_in_progress). Запоминается только удачный ответ (2xx): после отказа повтор с тем же ключом выполнится заново. Ключ живёт сутки (настройка idempotency.keys), область — организация и тот, кто прислал (ключ API или человек).

Доступ: proposals.approve.

Доступно по ключу API.

POST /v1/companies/{co}/proposals/approve-batch

Одобрить пачку предложений

cURL

curl --request POST \
  --url https://api.tungo.kz/v1/companies/{co}/proposals/approve-batch \
  --header 'Content-Type: application/json' \
  --cookie tungo.session_token= \
  --data '
{
  "ids": [
    "<string>"
  ],
  "batch_id": "<string>",
  "exclude": [
    "<string>"
  ],
  "post": true,
  "note": "<string>",
  "idempotency_key": "<string>",
  "async": true
}
'

200

{
  "ok": true,
  "message": "Одобрено 12 из 14, исключено 1, с блокерами 1.",
  "requested": 123,
  "approved": 123,
  "excluded": 123,
  "failed": 123,
  "limit": 123,
  "counts": {
    "approved": 12,
    "excluded": 1,
    "blocked": 1
  },
  "results": [
    {
      "id": "P-000123",
      "outcome": "approved",
      "title": "Одобрено и записано",
      "message": "<string>",
      "error": "<string>",
      "retry_after": 123,
      "document_number": "<string>",
      "mismatches": [
        "<string>"
      ]
    }
  ],
  "batch_id": "<string>",
  "unknown_excluded": [
    "<string>"
  ],
  "stopped": {
    "reason": "<string>",
    "remaining": 123
  }
}

Авторизации

sessionapiKeybearerKey

tungo.session_token · string · cookie · обязательно

Сессия кабинета: cookie ставит вход через /v1/auth/* (Better Auth), браузер шлёт её сам — фронтенду кабинета ничего добавлять не нужно (fetch с credentials: 'include'). За HTTPS имя cookie — __Secure-tungo.session_token. Сессия кончилась — 401 authentication_error: отправить на вход.

Заголовки

Idempotency-Key · string

Ключ повтора (например, UUID): повтор с тем же ключом и тем же телом не выполняет действие второй раз, а отдаёт прежний ответ

Maximum string length: 255

Параметры пути

co · string · обязательно

id компании, co_… — из GET /v1/companies

Тело

application/json

Что одобрить: либо ids, либо batch_id — ровно одно из двух. Неизвестные поля — 400.

ids · string[]

Явный список предложений. Взаимоисключающе с batch_id.

Minimum array length: 1

Required string length: 1 - 64

batch_id · string

Задание пачки (bat_… — id из ответа на загрузку выписки или ЭСФ): все предложения этого задания

exclude · string[]

Что снято галочками — эти предложения не одобряются (не больше 2000)

Maximum array length: 2000

Maximum string length: 64

post · boolean

Проводить документы после записи (по умолчанию true)

note · string

Комментарий к решению: попадёт в журнал по каждому предложению

Maximum string length: 1000

idempotency_key · string

То же, что заголовок Idempotency-Key

Maximum string length: 200

async · boolean

Одобрить заданием в фоне: ответ 202 с номером задания сразу, прогресс — …/batch/:id/events, итог — …/batch/:id (report.approval). Пачка больше 50 предложений идёт заданием всегда.

Ответ

200

application/json

Итог по каждому предложению — пачка до 50 предложений без async

Итог одобрения пачкой — по каждому предложению

ok · boolean · обязательно

true — всё, что не снято галочкой, одобрено (или уже было записано); false — есть отказы, смотрите results

message · string · обязательно

Итог одной фразой для человека

Пример:

"Одобрено 12 из 14, исключено 1, с блокерами 1."

requested · number · обязательно

Сколько предложений в пачке (со снятыми галочкой)

approved · number · обязательно

Одобрено, включая уже записанные раньше

excluded · number · обязательно

Снято галочкой

failed · number · обязательно

Не одобрено по любой причине

limit · number · обязательно

Предел пачки (2000)

counts · object · обязательно

Сколько предложений с каждым исходом (ключ — outcome из results)

Show child attributes

Пример:

{
  "approved": 12,
  "excluded": 1,
  "blocked": 1
}

results · object[] · обязательно

Исход по каждому предложению, в порядке пачки

Show child attributes

batch_id · string

Номер задания, если одобряли по batch_id

unknown_excluded · string[]

Номера из exclude, которых нет в пачке

stopped · object

Пачка остановлена раньше конца (1С трижды не ответила, база только для чтения, отозвали право, нажали «Остановить»)

Show child attributes