feat!: API correctness audit v2.0.0 — 10 breaking fixes + CI

Breaking changes (методы исправлены по спецификации API СУЗ 3.0):
- send_aggregation: новая структура тела — participantId + aggregationUnits[]
  (был плоский sntins[]); новый датакласс AggregationUnit
- send_dropout: dropout_reason стал обязательным параметром (§4.4.9)
- send_surplus: тело переработано по SurplusReport §4.4.12; productGroup → query param
- get_quality: orderId стал необязательным; QualityResponse → QualityListResponse
- get_quality_cis_list: параметры order_id/gtin → обязательный report_id (§4.4.16)
- get_mod: добавлен обязательный product_group; ModResponse → ModListResponse (§4.4.17)
- get_receipt_document: добавлен обязательный параметр doc_id (§4.4.20)
- search_orders: дефолт page изменён с 0 на 1 (1-based, §4.4.29)

Fixed:
- search_documents: ключ ответа "results" → "result" (§4.4.21)
- BufferInfo.total_codes: тип int → str | int (§4.4.2.2 Table 257)

Added:
- GitHub Actions CI: ruff + mypy --strict + pytest на Python 3.11/3.12/3.13

540 tests pass, mypy --strict clean, ruff clean.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: stemirkhan

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Type-check with mypy
+        run: mypy --strict src/suz_sdk/
+
+      - name: Run tests
+        run: pytest --tb=short

CHANGELOG.md

@@ -11,6 +11,44 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ---
 
+## [2.0.0] — 2026-03-19
+
+### Breaking Changes
+
+- **`send_aggregation()`** — полностью переработана сигнатура по §4.4.10 (Table 119–120).
+  Старые параметры `sntins` и `aggregation_type` удалены; добавлены обязательные
+  `participant_id: str` (ИНН) и `aggregation_units: list[AggregationUnit]`.
+  Новый датакласс `AggregationUnit` содержит поля `sntins`, `unit_serial_number`,
+  `aggregated_items_count`, `aggregation_unit_capacity`; поле `aggregationType`
+  в теле запроса теперь всегда равно `"AGGREGATION"`.
+- **`send_dropout()`** — параметр `dropout_reason` стал обязательным (§4.4.9, «Да»).
+- **`send_surplus()`** — тело запроса переработано согласно `SurplusReport` §4.4.12
+  (Table 175): добавлены `document_date`, `participant_inn`, `primary_document_*`
+  и `codes`; `productGroup` перенесён в query-параметр.
+- **`get_quality()`** — параметр `order_id` стал необязательным; модель ответа
+  переименована `QualityResponse` → `QualityListResponse`; поле `results` теперь
+  `list[str]` (UUID отчётов), а не список объектов.
+- **`get_quality_cis_list()`** — параметры `order_id`/`gtin` заменены на обязательный
+  `report_id: str` (UUID из `get_quality()`); модель ответа полностью изменена.
+- **`get_mod()`** — добавлен обязательный параметр `product_group: str` (§4.4.17);
+  модель ответа переименована `ModResponse` → `ModListResponse`.
+- **`get_receipt_document()`** — добавлен обязательный параметр `doc_id: str` (§4.4.20).
+- **`search_orders()`** — дефолт `page` изменён с `0` на `1` (1-based, §4.4.29).
+
+### Fixed
+
+- **`search_documents()`** — ключ ответа исправлен с `"results"` на `"result"` (§4.4.21).
+- **`BufferInfo.total_codes`** — тип изменён с `int` на `str | int` согласно спецификации
+  (§4.4.2.2, Table 257, тип «Строка»).
+
+### Added
+
+- Датакласс `AggregationUnit` (публичный, экспортируется из `suz_sdk`).
+- GitHub Actions CI (`.github/workflows/ci.yml`) — запуск ruff, mypy, pytest на
+  Python 3.11/3.12/3.13 при каждом push/PR в `main`.
+
+---
+
 ## [0.9.0] — 2026-03-07
 
 ### Changed

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "suz-sdk"
-version = "1.2.0"
+version = "2.0.0"
 description = "Python SDK for СУЗ API 3.0 (СУЗ-Облако 4.0)"
 readme = "README.md"
 requires-python = ">=3.11"

src/suz_sdk/__init__.py

@@ -61,13 +61,14 @@
 )
 from suz_sdk.api.reference import (
     AsyncReferenceApi,
-    ModResponse,
+    ModListResponse,
     ProvidersResponse,
     QualityCisListResponse,
-    QualityResponse,
+    QualityListResponse,
     ReferenceApi,
 )
 from suz_sdk.api.reports import (
+    AggregationUnit,
     ReceiptFilter,
     ReportsApi,
     ReportStatusResponse,
@@ -151,13 +152,14 @@
     "SendSurplusResponse",
     "ReportStatusResponse",
     "SearchReceiptsResponse",
-    # Request models (reports)
+    # Request/input models (reports)
+    "AggregationUnit",
     "ReceiptFilter",
     # Response models (reference)
     "ProvidersResponse",
-    "QualityResponse",
+    "QualityListResponse",
     "QualityCisListResponse",
-    "ModResponse",
+    "ModListResponse",
     # Response models (documents)
     "SearchDocumentsResponse",
     "DeleteDocumentResponse",
@@ -191,4 +193,4 @@
     "RetryConfig",
 ]
 
-__version__ = "1.2.0"
+__version__ = "2.0.0"

src/suz_sdk/api/async_reports.py

@@ -5,6 +5,7 @@
 from typing import Any, cast
 
 from suz_sdk.api.reports import (
+    AggregationUnit,
     ReceiptFilter,
     ReportsApi,
     ReportStatusResponse,
@@ -79,7 +80,7 @@ async def send_dropout(
         self,
         product_group: str,
         sntins: list[str],
-        dropout_reason: str | None = None,
+        dropout_reason: str,
         attributes: dict[str, Any] | None = None,
     ) -> SendDropoutResponse:
         """Send a KM dropout report (POST /api/v3/dropout)."""
@@ -90,9 +91,8 @@ async def send_dropout(
         body_dict: dict[str, Any] = {
             "productGroup": product_group,
             "sntins": sntins,
+            "dropoutReason": dropout_reason,
         }
-        if dropout_reason is not None:
-            body_dict["dropoutReason"] = dropout_reason
         if attributes is not None:
             body_dict["attributes"] = attributes
 
@@ -120,8 +120,8 @@ async def send_dropout(
     async def send_aggregation(
         self,
         product_group: str,
-        sntins: list[str],
-        aggregation_type: str | None = None,
+        participant_id: str,
+        aggregation_units: list[AggregationUnit],
         attributes: dict[str, Any] | None = None,
     ) -> SendAggregationResponse:
         """Send a KM aggregation report (POST /api/v3/aggregation)."""
@@ -131,10 +131,18 @@ async def send_aggregation(
 
         body_dict: dict[str, Any] = {
             "productGroup": product_group,
-            "sntins": sntins,
+            "participantId": participant_id,
+            "aggregationUnits": [
+                {
+                    "aggregatedItemsCount": u.aggregated_items_count,
+                    "aggregationType": "AGGREGATION",
+                    "aggregationUnitCapacity": u.aggregation_unit_capacity,
+                    "sntins": u.sntins,
+                    "unitSerialNumber": u.unit_serial_number,
+                }
+                for u in aggregation_units
+            ],
         }
-        if aggregation_type is not None:
-            body_dict["aggregationType"] = aggregation_type
         if attributes is not None:
             body_dict["attributes"] = attributes
 
@@ -162,20 +170,36 @@ async def send_aggregation(
     async def send_surplus(
         self,
         product_group: str,
-        sntins: list[str],
-        attributes: dict[str, Any] | None = None,
+        document_date: str,
+        participant_inn: str,
+        primary_document_custom_name: str,
+        primary_document_date: str,
+        primary_document_number: str,
+        codes: list[str],
+        document_type: str = "SURPLUS_POSTING",
+        document_version: str = "1.0",
+        participant_kpp: str | None = None,
+        participant_fias: str | None = None,
     ) -> SendSurplusResponse:
-        """Send a KM surplus report (POST /api/v3/surplus)."""
+        """Send a surplus posting notification (POST /api/v3/surplus, §4.4.12)."""
         from suz_sdk.transport.async_httpx_transport import AsyncHttpxTransport
 
         transport: AsyncHttpxTransport = self._transport  # type: ignore[assignment]
 
         body_dict: dict[str, Any] = {
-            "productGroup": product_group,
-            "sntins": sntins,
+            "documentType": document_type,
+            "documentVersion": document_version,
+            "documentDate": document_date,
+            "participantInn": participant_inn,
+            "primaryDocumentCustomName": primary_document_custom_name,
+            "primaryDocumentDate": primary_document_date,
+            "primaryDocumentNumber": primary_document_number,
+            "codes": codes,
         }
-        if attributes is not None:
-            body_dict["attributes"] = attributes
+        if participant_kpp is not None:
+            body_dict["participantKpp"] = participant_kpp
+        if participant_fias is not None:
+            body_dict["participantFias"] = participant_fias
 
         raw_body = json.dumps(body_dict, ensure_ascii=False).encode()
 
@@ -190,7 +214,7 @@ async def send_surplus(
         req = Request(
             method="POST",
             path="/api/v3/surplus",
-            params={"omsId": self._oms_id},
+            params={"omsId": self._oms_id, "productGroup": product_group},
             headers=headers,
             raw_body=raw_body,
         )

src/suz_sdk/api/documents.py

@@ -84,16 +84,19 @@ def __init__(
     # Public methods
     # ------------------------------------------------------------------
 
-    def get_receipt_document(self, result_doc_id: str) -> dict[str, Any]:
-        """Retrieve a receipt document by its result doc ID.
+    def get_receipt_document(self, result_doc_id: str, doc_id: str) -> dict[str, Any]:
+        """Retrieve the document associated with a receipt (§4.4.20).
 
-        GET /api/v3/receipts/document?omsId={omsId}&resultDocId={resultDocId}
+        GET /api/v3/receipts/document?omsId={omsId}&resultDocId={resultDocId}&docId={docId}
+
+        All three query parameters are required (§4.4.20.1, Table 212).
 
         Args:
-            result_doc_id: The resultDocId of the receipt document to retrieve.
+            result_doc_id: UUID of the receipt (order, report, or KM block).
+            doc_id:        UUID of the associated document linked to the receipt.
 
         Returns:
-            Raw response dict (schema is complex and product-group-specific).
+            Raw response dict with ``content`` field (base64-encoded document).
 
         Raises:
             SuzAuthError:       clientToken is missing or invalid.
@@ -107,6 +110,7 @@ def get_receipt_document(self, result_doc_id: str) -> dict[str, Any]:
             params={
                 "omsId": self._oms_id,
                 "resultDocId": result_doc_id,
+                "docId": doc_id,
             },
             headers={
                 "Accept": "application/json",
@@ -163,7 +167,7 @@ def search_documents(
         body: dict[str, Any] = resp.body
         return SearchDocumentsResponse(
             total_count=body["totalCount"],
-            results=body.get("results", []),
+            results=body.get("result", []),
         )
 
     def get_document_content(self, doc_id: str) -> dict[str, Any]:
@@ -298,10 +302,10 @@ def __init__(
     # Public methods
     # ------------------------------------------------------------------
 
-    async def get_receipt_document(self, result_doc_id: str) -> dict[str, Any]:
-        """Retrieve a receipt document by its result doc ID.
+    async def get_receipt_document(self, result_doc_id: str, doc_id: str) -> dict[str, Any]:
+        """Retrieve the document associated with a receipt (§4.4.20).
 
-        GET /api/v3/receipts/document?omsId={omsId}&resultDocId={resultDocId}
+        GET /api/v3/receipts/document?omsId={omsId}&resultDocId={resultDocId}&docId={docId}
         """
         from suz_sdk.transport.async_httpx_transport import AsyncHttpxTransport
 
@@ -312,6 +316,7 @@ async def get_receipt_document(self, result_doc_id: str) -> dict[str, Any]:
             params={
                 "omsId": self._oms_id,
                 "resultDocId": result_doc_id,
+                "docId": doc_id,
             },
             headers={
                 "Accept": "application/json",
@@ -357,7 +362,7 @@ async def search_documents(
         body: dict[str, Any] = resp.body
         return SearchDocumentsResponse(
             total_count=body["totalCount"],
-            results=body.get("results", []),
+            results=body.get("result", []),
         )
 
     async def get_document_content(self, doc_id: str) -> dict[str, Any]:

src/suz_sdk/api/orders.py

@@ -61,7 +61,7 @@ class BufferInfo:
     gtin: str
     buffer_status: str          # ACTIVE | PENDING | REJECTED
     available_codes: int
-    total_codes: int
+    total_codes: str | int
     total_passed: int
     unavailable_codes: int
     left_in_buffer: int
@@ -467,7 +467,7 @@ def search_orders(
         self,
         filter: OrderFilter | None = None,
         limit: int = 10,
-        page: int = 0,
+        page: int = 1,
     ) -> SearchOrdersResponse:
         """Search orders with optional filtering and pagination.
 
@@ -476,7 +476,7 @@ def search_orders(
         Args:
             filter: Optional OrderFilter with search criteria.
             limit:  Maximum number of results to return.
-            page:   Zero-based page number.
+            page:   1-based page number (default 1, max 100).
 
         Returns:
             SearchOrdersResponse with total_count and a list of OrderSummaryInfo.