API счетов и ежемесячного выставления

01Доступ

Базовый адрес https://waix.kz/api/v1. Используйте Bearer API-ключ с payments:read для чтения и payments:write для создания, отправки и отмены. Реквизиты компании и отметка поступления банковского перевода доступны сотрудникам с ролью владельца, администратора или бухгалтера в кабинете.

На создании обязателен Idempotency-Key длиной 8–160 символов. Повтор с тем же ключом и телом возвращает тот же документ. Изменённое тело с прежним ключом — 409. Новый ключ создаёт новый счёт.

02Создать и выставить

curl https://waix.kz/api/v1/invoices \
 -H "Authorization: Bearer $WAIX_API_KEY" \
 -H 'Content-Type: application/json' \
 -H 'Idempotency-Key: invoice-order-481-v1' \
 -d '{"invoice":{"items":[{"description":"Обслуживание оборудования","quantity":1,"unit":"усл.","unit_price_minor":4500000}],"due_date":"2026-11-10"},"customer":{"name":"ТОО Покупатель","phone":"+77071234567","email":"accounting@example.kz"},"issue":true}'

POST /invoices возвращает data с id, number, status, lifecycle_status, total_minor, currency, items, supplier, customer и dispatches. Суммы — целые тиыны, валюта — KZT. 4 500 000 тиын = 45 000 тенге. customer создаёт покупателя; для сохранённого передайте invoice.customer_id вместо customer. GET /invoices/customers — справочник (по 100, offset).

issue=false сохраняет черновик. PATCH /invoices/{id} изменяет только черновик; передавайте expected_revision из последнего ответа. POST /invoices/{id}/issue выставляет его. После выставления коммерческие поля и снимок реквизитов неизменны. POST /invoices/{id}/cancel с reason отменяет неоплаченный счёт.

03Отправить и скачать

GET /invoices/{id} — документ и история. GET /invoices/{id}/pdf — файл application/pdf. POST /invoices/{id}/send принимает recipients. При создании тот же массив можно передать в delivery. Одного получателя WAIX не добавляет повторно к тому же счёту.

{
  "recipients": [
    {
      "channel": "whatsapp",
      "recipient": "+77071234567",
      "connection_id": "CONNECTION_UUID",
      "template_name": "waix_invoice_v1",
      "template_language": "ru"
    },
    {
      "channel": "email",
      "recipient": "accounting@example.kz"
    }
  ]
}

Шаблон WhatsApp содержит четыре текстовые переменные: номер счёта, сумма в тенге, название продавца, ссылка на PDF. Подготовьте одобренный шаблон в кабинете. Максимум 10 получателей. WhatsApp требует активный доступ к отправке с выбранного номера.

Для группы сначала получите GET /invoices/groups?connection_id=UUID (следующие страницы — after). Выберите id из ответа. В recipients передайте channel=whatsapp_group, recipient=GROUP_ID, connection_id и template_name=waix_invoice_group_v1. Произвольную группу из приложения использовать нельзя.

04Группы Telegram

Подключите бота и группы в кабинете → Платежи и счета → Реквизиты. GET /invoices/telegram возвращает configured, bot_name и groups; секретный токен не возвращается. Для отправки передайте в recipients объект {"channel":"telegram","recipient":"-1001234567890"}, где recipient — id проверенной группы. PDF придёт вложением. Произвольные chat ID не принимаются.

05Ежемесячный счёт

POST /invoice-schedules создаёт расписание. Покупатель должен быть сохранён: POST /invoices/customers с полями name, phone, email и необязательными реквизитами. Для обоих запросов нужен Idempotency-Key.

{
  "name": "Обслуживание магазина",
  "start_date": "2026-11-01",
  "day_of_month": 1,
  "due_days": 7,
  "invoice": {
    "customer_id": "CUSTOMER_UUID",
    "items": [
      {
        "description": "Ежемесячное обслуживание",
        "quantity": 1,
        "unit_price_minor": 4500000
      }
    ]
  },
  "delivery": []
}

GET /invoice-schedules — список по 50, offset. PATCH /invoice-schedules/{id} с status=paused|active|cancelled управляет расписанием. cancelled нельзя возобновить. PUT /invoice-schedules/{id} принимает полное тело расписания и expected_updated_at из GET; меняет будущие счета, сохраняя паузу и историю. Конфликт версии возвращает 409. День 29–31 переносится на последний день короткого месяца. После перерыва создаётся только последний наступивший период. Ошибка ставит расписание на паузу и заполняет last_error.

06Оплата и события

POST /invoices/{id}/kaspi создаёт один привязанный запрос на сумму счёта и отправляет покупателю сообщение. Сумма должна быть целым количеством тенге, телефон покупателя — сохранён в счёте, Kaspi — включён в настройках.

Подпишитесь на invoice.issued и invoice.paid. Событие содержит id, number, total_minor и currency. invoice.paid также указывает verification_source: customer_receipt для Kaspi или merchant_confirmation для ручной отметки банковского перевода. События создаются при переходе статуса. Доставка вебхуков повторяется: проверяйте подпись и сохраняйте ID события.

07Отчёт и фильтры

GET /payment-workspace возвращает rows, summary, days, sources, timezone и has_more. Фильтры: from/to (YYYY-MM-DD, дата создания в часовом поясе компании), q, kind=all|kaspi|invoice, status=all|draft|waiting|overdue|paid|cancelled|expired, source=all|api|portal|message|subscription|recurring, min/max (тенге), sort=newest|oldest|amount_desc|amount_asc|due, offset. По 50 записей.

GET /payment-workspace/export возвращает JSON data: filename, content (CSV с BOM, разделитель «;»), total. Лимит — 10 000 строк; при превышении ответ 422, без незаметного усечения отчёта. Чтение и экспорт требуют payments:read.