API договоров, актов и предложений

01Доступ

Базовый путь https://waix.kz/api/v1/documents. Чтение требует API-ключ payments:read, создание и выпуск — payments:write. Управление общими шаблонами и реквизитами контрагента доступно владельцу, администратору и бухгалтеру в кабинете. Все записи изолированы по компании.

02Создать черновик

GET /templates возвращает templates, variables и kinds. GET /customers — справочник контрагентов (q, offset; по 100). POST /customers создаёт контрагента с обязательным name и необязательными реквизитами; нужен Idempotency-Key. POST /api/v1/documents создаёт черновик. Передавайте уникальный Idempotency-Key длиной 8–160 символов; повтор с тем же телом вернёт тот же документ, изменённое тело — 409.

{
  "kind": "proposal",
  "template_id": "service-proposal",
  "customer_id": "CUSTOMER_UUID",
  "title": "Сопровождение магазина",
  "document_date": "2026-11-01",
  "service": "Обслуживание касс и компьютеров",
  "period_start": "2026-11-01",
  "period_end": "2026-11-30",
  "valid_until": "2026-11-10",
  "payment_terms": "Оплата до начала периода.",
  "delivery_terms": "Настройка касс, удалённая поддержка и ежемесячный отчёт.",
  "items": [
    {
      "description": "Сопровождение магазина",
      "quantity": 1,
      "unit": "месяц",
      "unit_price_minor": 7500000
    }
  ]
}

Суммы — целые тиыны, валюта KZT. kind: contract, act или proposal. Для счетов используйте существующий /api/v1/invoices. Документ принимает до 50 позиций, vat_mode=none|included|on_top, vat_rate_basis_points. sections позволяет передать свою редакцию заголовков и текста. source_document_id связывает с предыдущим документом того же контрагента.

03Редактирование и PDF

GET /{id} возвращает input, снимки реквизитов, итоговые sections, totals, revision и events. PUT /{id} принимает полное тело документа и expected_revision; разрешён только для черновика. POST /preview формирует черновой PDF без сохранения: JSON data содержит filename, content в base64 и content_type.

POST /{id}/finalize с expected_revision проверяет обязательные реквизиты и сохраняет готовый PDF. GET /{id}/pdf возвращает application/pdf. Изменение реквизитов и шаблонов не меняет выпущенный файл. POST /{id}/archive с expected_revision переносит запись в архив. Выпущенный PDF остаётся доступен только пользователям и ключам компании.

Для договора и акта заполните ИИН/БИН обеих сторон, period_start/period_end, supplier_signatory, customer_signatory и delivery_terms. Для акта требуется reference; для договора — payment_terms; для предложения — valid_until и payment_terms. Не хватает данных — 422, чужая запись — 404, конфликт редакции — 409.

04Связанный счёт и поиск

POST /{id}/invoice создаёт один счёт-черновик из готового документа, повтор возвращает тот же id. Дальнейшая проверка, выставление и отправка выполняются через API счетов. GET /api/v1/documents поддерживает kind, status=draft|ready|archived|all, q, customer_id, contact_id, offset. По 50 строк, has_more. В списке есть и существующие счета; их поля payment_status и kind=invoice позволяют открыть платёжный кабинет.