Карточка предложения

Шапка, строки, проводки, блокеры, доступные действия.

Доступ: company.read.

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

GET /v1/companies/{co}/proposals/{id}

Карточка предложения

cURL

curl --request GET \
  --url https://api.tungo.kz/v1/companies/{co}/proposals/{id} \
  --cookie tungo.session_token=

200

{
  "id": "P-000123",
  "kind": "sale",
  "kind_title": "Реализация товаров и услуг",
  "status": "previewed",
  "status_title": "Ждёт решения",
  "created_at": "2026-07-10T09:15:00.000Z",
  "level": "L0",
  "level_title": "Предложение, одобряет человек",
  "title": "Реализация товаров и услуг от 2026-07-10 · ТОО «Пример»",
  "total": {
    "amount": 1234.5,
    "amount_tiyn": 123450,
    "formatted": "1 234,50 ₸"
  },
  "vat": {
    "amount": 1234.5,
    "amount_tiyn": 123450,
    "formatted": "1 234,50 ₸"
  },
  "line_count": 123,
  "warning_count": 123,
  "blocker_count": 123,
  "approval": {
    "allowed": true,
    "requires_right": "proposals.approve",
    "blocked_by_blockers": true,
    "reason": "<string>"
  },
  "approval_request": {
    "can_request": true,
    "requested": {
      "by": "<string>",
      "by_name": "Айгерим Сапарова",
      "at": "2023-11-07T05:31:56Z",
      "note": "<string>"
    },
    "href": "<string>"
  },
  "dialog_id": "<string>",
  "origin": {
    "source": "chat",
    "dialog_id": "<string>",
    "batch_id": "<string>",
    "run_id": "<string>"
  },
  "href": "/v1/companies/co_01jx0000000000000000000000/proposals/P-000123",
  "source": {
    "channel": "mcp",
    "note": "<string>"
  },
  "intent": {},
  "header": {
    "document_title": "Реализация товаров и услуг",
    "entity_set": "Document_РеализацияТоваровУслуг",
    "date": "2026-07-10",
    "total": {
      "amount": 1234.5,
      "amount_tiyn": 123450,
      "formatted": "1 234,50 ₸"
    },
    "vat": {
      "amount": 1234.5,
      "amount_tiyn": 123450,
      "formatted": "1 234,50 ₸"
    },
    "net": {
      "amount": 1234.5,
      "amount_tiyn": 123450,
      "formatted": "1 234,50 ₸"
    },
    "accounts": [
      {
        "field": "СчетУчетаБУ",
        "title": "Счёт учёта (БУ)",
        "code": "1330",
        "ref": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "organization": {
      "ref": "00000000-0000-0000-0000-000000000000",
      "name": "ТОО «Пример»",
      "bin": "000000000000"
    },
    "counterparty": {
      "ref": "00000000-0000-0000-0000-000000000000",
      "name": "ТОО «Пример»",
      "bin": "000000000000"
    },
    "contract": {
      "ref": "00000000-0000-0000-0000-000000000000",
      "name": "<string>",
      "number": "<string>",
      "date": "<string>",
      "kind": "<string>"
    },
    "prices_include_vat": true,
    "comment": "<string>",
    "payment_purpose": "<string>"
  },
  "lines": [
    {
      "no": 123,
      "section": "goods",
      "item": {
        "ref": "<string>",
        "name": "<string>"
      },
      "quantity": 2,
      "price": {
        "amount": 1234.5,
        "amount_tiyn": 123450,
        "formatted": "1 234,50 ₸"
      },
      "sum": {
        "amount": 1234.5,
        "amount_tiyn": 123450,
        "formatted": "1 234,50 ₸"
      },
      "vat_rate_title": "<string>",
      "vat": {
        "amount": 1234.5,
        "amount_tiyn": 123450,
        "formatted": "1 234,50 ₸"
      },
      "total": {
        "amount": 1234.5,
        "amount_tiyn": 123450,
        "formatted": "1 234,50 ₸"
      },
      "accounts": [
        {
          "field": "СчетУчетаБУ",
          "title": "Счёт учёта (БУ)",
          "code": "1330",
          "ref": "00000000-0000-0000-0000-000000000000"
        }
      ],
      "description": "<string>",
      "vat_rate": 12
    }
  ],
  "postings": [
    {
      "debit": "1210",
      "credit": "6010",
      "amount": {
        "amount": 1234.5,
        "amount_tiyn": 123450,
        "formatted": "1 234,50 ₸"
      },
      "label": "<string>",
      "computed_by_1c": true
    }
  ],
  "warnings": [
    "<string>"
  ],
  "blockers": [
    "<string>"
  ],
  "actions": [
    {
      "action": "approve",
      "label": "<string>",
      "method": "POST",
      "href": "<string>",
      "enabled": true,
      "effect": "<string>",
      "body": {
        "post": true,
        "idempotency_key": "<uuid от клиента>"
      },
      "disabled_reason": "<string>"
    }
  ],
  "history": [
    {
      "at": "2023-11-07T05:31:56Z",
      "status": "previewed",
      "status_title": "<string>",
      "actor": "<string>",
      "note": "<string>",
      "code": "<string>"
    }
  ],
  "summary": "<string>",
  "counterparty": {
    "ref": "00000000-0000-0000-0000-000000000000",
    "name": "ТОО «Пример»",
    "bin": "000000000000"
  },
  "document_number": "0000-000123",
  "advance_offset": {
    "amount": {
      "amount": 1234.5,
      "amount_tiyn": 123450,
      "formatted": "1 234,50 ₸"
    },
    "to_pay": {
      "amount": 1234.5,
      "amount_tiyn": 123450,
      "formatted": "1 234,50 ₸"
    },
    "debit": "<string>",
    "credit": "<string>",
    "note": "<string>"
  },
  "result": {
    "number": "<string>",
    "ref": "00000000-0000-0000-0000-000000000000",
    "postings": [
      {
        "debit": "1210",
        "credit": "6010",
        "amount": {
          "amount": 1234.5,
          "amount_tiyn": 123450,
          "formatted": "1 234,50 ₸"
        },
        "label": "<string>",
        "computed_by_1c": true
      }
    ],
    "mismatches": [
      "<string>"
    ]
  }
}

Авторизации

sessionapiKeybearerKey

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

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

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

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

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

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

Номер предложения внутри компании: P- и шесть цифр (P-000123). У двух компаний номера могут совпадать

Пример:

"P-000123"

Ответ

200

application/json

Карточка

Полная карточка предложения: шапка, строки, проводки, блокеры, кнопки и история

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

Номер предложения внутри компании (P-000123): по нему открывают карточку GET …/proposals/{id} и одобряют POST …/proposals/{id}/approve

Пример:

"P-000123"

kind · enum<string> · обязательно

Что ИИ предлагает записать в 1С (подпись по-русски — в kind_title):

• sale — реализация товаров и услуг (продажа покупателю);
• purchase — поступление товаров и услуг (покупка у поставщика);
• bank_receipt — входящее платёжное поручение (деньги пришли на счёт);
• bank_payment — исходящее платёжное поручение (оплата со счёта);
• counterparty — новый контрагент (карточка справочника, не документ);
• contract — новый договор с контрагентом (карточка справочника);
• revert — отмена ранее записанного документа (распровести и пометить на удаление);
• inventory_writeoff — списание товаров;
• cash_order_in — приходный кассовый ордер (наличные в кассу);
• cash_order_out — расходный кассовый ордер (наличные из кассы);
• advance_report — авансовый отчёт подотчётного лица.

Доступные опции: sale, purchase, bank_receipt, bank_payment, counterparty, contract, revert, inventory_writeoff, cash_order_in, cash_order_out, advance_report

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

Вид документа по-русски для показа

Пример:

"Реализация товаров и услуг"

status · enum<string> · обязательно

Где предложение в жизненном цикле (подпись по-русски — в status_title рядом):

• previewed — ждёт решения бухгалтера: показать кнопки «Записать» и «Отклонить»;
• approved — одобрено, но запись в 1С не закончена (1С не ответила): «Записать» ещё раз безопасно — второй документ не создастся;
• rejected — отклонено, в 1С ничего не записано; конечное;
• committed — записано в 1С черновиком, без проведения (проводок нет);
• posted — записано и проведено, проводки ещё не сверены;
• verified — проведено, фактические проводки 1С совпали с ожидаемыми; конечное, всё хорошо;
• mismatch — проведено, но проводки расходятся с ожидаемыми: показать предупреждение, причины — в result.mismatches;
• failed — записать не удалось: причина — в последней записи history.

Доступные опции: previewed, approved, rejected, committed, posted, verified, mismatch, failed

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

Статус по-русски для показа (бейдж)

Пример:

"Ждёт решения"

created_at · string<date-time> · обязательно

Когда ИИ подготовил предложение, ISO 8601 UTC

Пример:

"2026-07-10T09:15:00.000Z"

level · enum<string> · обязательно

Уровень самостоятельности ИИ для этого вида операции по политике компании (подпись — в level_title):

• L0 — только чтение; L1 — ИИ предлагает, одобряет человек (обычный случай);
• L2 — ИИ сам записывает черновик; L3 — ИИ проводит сам, с возможностью отмены; L4 — ИИ проводит сам;
• HUMAN_ONLY — только человек и только по одному: пачкой не одобряется (исход policy_blocked);
• FORBIDDEN — запрещено политикой: одобрить нельзя (403, error.code = policy_blocked).

Доступные опции: L0, L1, L2, L3, L4, HUMAN_ONLY, FORBIDDEN

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

Уровень самостоятельности по-русски для показа

Пример:

"Предложение, одобряет человек"

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

Заголовок строки очереди: вид документа, дата и контрагент

Пример:

"Реализация товаров и услуг от 2026-07-10 · ТОО «Пример»"

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

Сумма документа (как в 1С: с НДС или без — см. header.prices_include_vat в карточке)

Show child attributes

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

НДС по строкам документа (налог на добавленную стоимость); 0 — без НДС

Show child attributes

line_count · integer · обязательно

Сколько строк товаров и услуг в документе; 0 у платёжек и справочников

warning_count · integer · обязательно

Сколько предупреждений: показать жёлтый значок, одобрению не мешают

blocker_count · integer · обязательно

Сколько блокеров: больше 0 — одобрить нельзя, нужен ответ человека в чате

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

Можно ли текущему пользователю одобрить предложение — то же правило, что применит ручка одобрения

Show child attributes

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

«Отправить на одобрение»: человек без права записывать в 1С просит решения у того, у кого право есть. Статус предложения не меняется

Show child attributes

dialog_id · string | null · обязательно

Разговор чата, в котором ИИ подготовил предложение: «Открыть разговор» — GET …/chat/{dialog_id} (если он ваш). null — не из разговора человека (пачка из ручки, автоматизация, MCP)

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

Откуда пришло предложение и ссылки на источник — вычисляется из связей предложения

Show child attributes

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

Адрес карточки в API: GET по нему отдаёт ProposalCard

Пример:

"/v1/companies/co_01jx0000000000000000000000/proposals/P-000123"

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

Откуда пришло предложение

Show child attributes

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

Намерение ИИ в предметных терминах (ключи snake_case) — для аудита и отладки; интерфейсу показывать не нужно

Show child attributes

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

Шапка документа: дата, стороны, итоги, счета

Show child attributes

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

Строки товаров и услуг; пусто у платёжек, кассовых ордеров и справочников

Show child attributes

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

Ожидаемые проводки — что получится в учёте после проведения

Show child attributes

warnings · string[] · обязательно

Предупреждения — показать жёлтым; одобрению не мешают

blockers · string[] · обязательно

Блокеры — показать красным: пока они есть, одобрить нельзя. Снимает их ответ человека в чате (ИИ пересоберёт предложение)

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

Кнопки карточки в нужном порядке: approve, approve_draft, reject

Show child attributes

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

История статусов, от старых к новым

Show child attributes

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

Текстовое превью документа (для чата и логов). Интерфейс рисует карточку по полям выше

counterparty · object

Контрагент документа; нет — у документа его нет (например, кассовый ордер без контрагента)

Show child attributes

document_number · string

Номер документа в 1С — есть, когда документ уже записан

Пример:

"0000-000123"

advance_offset · object

Есть, если при проведении 1С зачтёт аванс контрагента

Show child attributes

result · object

Есть, когда документ уже записан в 1С

Show child attributes