Делайте из своей системы всё то же, что и в интерфейсе, по тем же правилам.

1. Проверьте ключ

Каждый запрос несёт Authorization: Bearer. Первый вызов покажет, к какому бизнесу и к какой компании привязан ключ и что ему разрешено:

curl -s "https://api.kumpara.net/v1/me" \
  -H "Authorization: Bearer kp_live_a1b2c3d4_…"

{
  "data": {
    "tenant":    { "id": "…", "name": "Örnek Ticaret A.Ş.", "plan": "Pro" },
    "company":   { "id": "…", "legalName": "Örnek Ticaret A.Ş.", "baseCurrency": "TRY" },
    "apiClient": { "prefix": "kp_live_a1b2c3d4", "environment": "live",
                   "scopes": ["me:read", "contacts:write", "sales:write", "sales:approve"] }
  }
}

GET /v1/capabilities сообщит, подключены ли электронные документы, сколько осталось кредитов и какова базовая валюта компании.

2. Сопоставьте контрагента своим ключом

Не нужно искать клиента каждый раз: используйте upsert по ИНН или коду. Существующая запись обновляется, отсутствующая создаётся.

curl -s -X POST "https://api.kumpara.net/v1/contacts/actions/upsert?matchBy=taxNumber" \
  -H "Authorization: Bearer kp_live_…" \
  -H "Idempotency-Key: contact-4711-2026-09-23" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Örnek Gıda Ltd. Şti.", "type": "customer", "taxNumber": "1234567890", "preferredCurrency": "TRY" }'

Поле created в ответе говорит, создана запись или обновлена. matchBy принимает только taxNumber или code.

3. Выставьте и проведите счёт

В строке счёта нет поля суммы. Вы передаёте количество, цену, скидку и ставку НДС; итог строки, удержанный НДС, базовую сумму и номер документа считает сервер.

curl -s -X POST "https://api.kumpara.net/v1/sales-invoices" \
  -H "Authorization: Bearer kp_live_…" \
  -H "Idempotency-Key: order-88213-invoice" \
  -H "Content-Type: application/json" \
  -d '{
        "contactId": "6f1c…",
        "currency": "TRY",
        "approve": true,
        "lines": [ { "productId": "9a3e…", "quantity": 10, "unitPrice": 250, "vatRate": 20 } ]
      }'

approve: true выполняет создание и проведение одной транзакцией. Это денежная мутация, поэтому ключу нужен sales:approve вместе с sales:write, иначе вернётся 403 insufficient_scope.

4. Проведите оплату и закройте счёт

curl -s -X POST "https://api.kumpara.net/v1/payments" \
  -H "Authorization: Bearer kp_live_…" \
  -H "Idempotency-Key: payment-88213" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "6f1c…", "cashAccountId": "2b77…", "direction": "incoming",
        "amount": 3060, "invoiceType": "sales_invoice", "invoiceId": "c41b…" }'

Касса, расчёты с контрагентом и распределение пишутся одной транзакцией. Для нескольких счетов — allocations[], для закрытия позже — POST /v1/payments/{id}/actions/allocate.

5. Забирайте изменения

curl -s "https://api.kumpara.net/v1/changes?since=2026-09-23T06:00:00Z&types=sales_invoice,payment" \
  -H "Authorization: Bearer kp_live_…"

В следующем вызове передайте meta.checkpoint как since — граница строгая, одна и та же запись не придёт дважды. Рекомендуем перекрытие в пять минут: чтение идемпотентно, повтор безвреден.

Идентификация и права

Ключ передаётся как Authorization: Bearer kp_live_… (или X-Api-Key). Открытое значение не хранится — Kumpara держит только SHA-256-хеш и префикс. Каждый ключ привязан к одной компании; данные другой компании вернуться не могут архитектурно. Права ключа не могут превышать роль создавшего его пользователя.

Права имеют вид {ресурс}:{действие}, их двадцать восемь: read — просмотр, write — создание и изменение, approve — проведение, отмена и сторно, issue/cancel/incoming — электронные документы. Недоступный эндпоинт возвращает 403 insufficient_scope и называет недостающее право.

Идемпотентность

Каждая запись требует Idempotency-Key. Ключ сохраняется внутри той же транзакции, что и запись — двойной записи нет. Повторный вызов с тем же ключом не выполняет работу заново. Ответ приходит в одной из двух форм: 409 idempotency_replayed (созданную запись вы читаете через GET) либо 200 с телом первого ответа и флагом replayed: true. Обе означают «операция уже применена»; ваш клиент должен считать успехом и ту и другую.

Деньги, курс и числовые типы

Суммы хранятся как numeric(19,4) и возвращаются в JSON строкой — без ошибок округления. Сумма никогда не отделяется от валюты.

Каждая финансовая строка несёт собственный снимок курса: originalAmount, originalCurrency, exchangeRate, baseAmount, baseCurrency. Даже если курс обновится позже, прошлый документ не изменится. Курс можно передать в exchangeRate; если не передать — применяется 1.

Пагинация

Списки страничатся курсором, offset отсутствует. Ответ несёт meta.nextCursor и meta.hasMore. Размер страницы — pageSize: по умолчанию 50, максимум 200. Для дельты — параметр запроса updatedAfter или поток /v1/changes.

Ошибки

Ошибки — RFC 9457 application/problem+json со стабильным полем code. Словарь зафиксирован.

Лимиты

Чтение и запись — разные корзины. По умолчанию 600 чтений и 120 записей в минуту на ключ; в каждом ответе есть RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset. При превышении — 429 и Retry-After.

Идентификатор запроса и спецификация

Каждый ответ несёт X-Request-Id; это же значение видно как requestId в теле ошибки — им и делитесь с поддержкой. Полный контракт опубликован как OpenAPI 3: https://api.kumpara.net/v1/openapi.json.

Таблица ниже — вся поверхность, работающая сегодня. Полные параметры, тела и схемы ответов — в OpenAPI: https://api.kumpara.net/v1/docs.

Как связывается цепочка документов. В теле накладной есть orderId, в теле счёта — orderId и deliveryNoteIds[], а строки сопоставляются через orderLineId и deliveryNoteLineId. Остаток не хранится счётчиком — он выводится из непогашенных счетов, поэтому отменённый счёт снова освобождает заказ.

Списание склада происходит в одном месте. Отгрузка и проведение счёта не списывают товар дважды: итоговое списание равно max(Σ отгрузок, Σ проведённых счетов), и каждый документ пишет только свою разницу.

Изоляция реализована в базе данных. Компании разделяет не фильтр в приложении, а собственный механизм безопасности строк PostgreSQL. Запрос API подключается ролью с минимальными правами, а контекст пишется в базу при открытии соединения — даже неверный запрос не вернёт строку другого бизнеса. Разделение компаний добавляется сверху: ключ привязан к одной компании.

Ключ не хранится. Хранятся только SHA-256-хеш и префикс (kp_live_a1b2c3d4). Открытое значение показывается один раз при создании; восстановить его нельзя — выпускается новый. В логи ключ не пишется, только префикс. Отзыв действует немедленно.

Повышения прав нет. Права ключа не превышают роль создавшего его пользователя. Создание счёта с approve: true требует sales:approve вместе с sales:write; при отсутствии запрос отклоняется, а не сохраняется черновиком.

Каждое действие оставляет след. Любая запись через API попадает в журнал аудита с префиксом ключа в роли актора (api:kp_live_a1b2c3d4). Интерфейс, мобильное приложение и API пишут в один журнал.

Персональные данные — узкие права. Поля вроде ИНН, IBAN, имени и адреса возвращаются ключам без права pii:read в замаскированном виде: видны последние четыре символа, а эндпоинт продолжает работать. Если интеграции это не нужно — не выдавайте его: лучшая защита, когда данные никуда не уходят.

Как хранить ключ. На сервере, в переменной окружения или менеджере секретов; никогда не в исходном коде, браузере или мобильном приложении. Для каждой интеграции — свой ключ. В обращении в поддержку передавайте requestId и Idempotency-Key, но никогда сам ключ.