{ "openapi": "3.0.3", "info": { "title": "К-247 API v1", "version": "1.7.0", "description": "API площадки К-247 для продавцов (прайсы, предложения, склады, заказы) и покупателей-организаций (поиск, перепроверка условий, заказы, биржа). Спецификация: docs/api-v1-spec.md, раздел F. Деньги — целые копейки (*_kop), валюта RUB. Продавец для покупателя обезличен (seller_code). Ключи test/live: Authorization: Bearer k247___. Клиент обязан игнорировать неизвестные поля. Синхронизация заказов и предложений — по since_seq (монотонный change_seq), since (ISO) только для людей. Песочница — тот же адрес, отличие только в ключе k247_test_… (поле env в ping). Вебхуки — подписка методами /webhooks (окружение подписки = окружение ключа), доставка описана в x-webhooks (в OpenAPI 3.0.3 нет раздела webhooks): POST JSON-конверта {id, type, created_at, env, api_version, data} на адрес подписки; заголовки X-K247-Event, X-K247-Event-Id, X-K247-Delivery-Attempt, X-K247-Signature: t=,v1=; проверка: пересчитать HMAC по сырому телу, сравнить за постоянное время, |now − t| ≤ 300 с, хранить обработанные id не меньше 72 ч; успех — любой 2xx за 10 с, повторы 1м, 5м, 30м, 2ч, 6ч, 24ч. Ответы nginx 413/429/502–504 тоже JSON формата Error. Примеры curl — x-codeSamples у каждой операции; страница https://k-247.ru/api.html генерируется из этого файла. Биржа (заявки и КП, спец. M): программа продавца — /seller/exchange/* (право exchange, регион заявок ключа own|all), программа покупателя-организации — /buyer/exchange/* (право exchange, только организации), тестовые заявки робота-покупателя — /sandbox/exchange/requests, справочник — /dictionary/exchange; заказы из КП в /seller/orders — source exchange; вебхуки exchange.* («*» их не включает). Методы, создающие обязательства (прайс, пакет предложений, утверждение загрузки, КП), боевому ключу компании без принятых документов площадки отвечают 403 LEGAL_NEEDS. Перечисления ответов открыты (x-extensible-enum): неизвестное значение клиент пропускает. Примеры curl написаны для bash (Linux, macOS, Git Bash): в Windows русские буквы из -d '…' уходят в cp1251 — 400 BAD_REQUEST «Тело запроса не в кодировке UTF-8»; тело с русскими буквами сохраните в файл UTF-8 и отправьте curl --data-binary @body.json (этот ответ 400 за Idempotency-Key не закрепляется).", "contact": { "name": "К-247", "url": "https://k-247.ru/api.html" } }, "servers": [ { "url": "https://k-247.ru/api/v1", "description": "Боевой сервер (live-ключ k247_live_…)" }, { "url": "https://k-247.ru/api/v1", "description": "Песочница: тот же адрес, ключ k247_test_… (dry run, test-заказы)" }, { "url": "http://localhost:3247/api/v1", "description": "Локальный стенд" } ], "tags": [ { "name": "common" }, { "name": "dictionary" }, { "name": "seller" }, { "name": "exchange-seller", "description": "Биржа: программа продавца — заявки покупателей и КП" }, { "name": "buyer" }, { "name": "exchange-buyer", "description": "Биржа: программа покупателя-организации — заявки, КП и «Принять»" }, { "name": "webhooks" }, { "name": "sandbox" } ], "security": [ { "bearer": [] } ], "paths": { "/ping": { "get": { "security": [ { "bearer": [] } ], "tags": [ "common" ], "operationId": "ping", "summary": "Проверка ключа, окружения, прав и лимитов", "responses": { "200": { "description": "Ключ действителен", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ping" }, "example": { "ok": true, "env": "test", "company": { "seller_code": "ТТ-014", "type": "shop", "verified": true, "city": "Санкт-Петербург", "confirm_orders": true }, "key": { "prefix": "k247_test_8f3kq2mz", "scopes": [ "offers", "orders" ], "created_at": "2026-09-15T07:00:00.000Z", "exchange_region": "own" }, "rate_limit": { "default": { "limit": 24, "remaining": 11 }, "search": { "limit": 12, "remaining": 6 }, "bulk": { "limit": 2, "remaining": 1 } }, "server_time": "2026-09-15T09:12:00.000Z", "api_version": "1.1", "capabilities": { "exchange": { "enabled": true, "seller": true, "buyer": true, "orders": "all", "counter_offer": false } }, "legal_needs": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/ping -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/dictionary/fields": { "get": { "security": [ { "bearer": [] } ], "tags": [ "dictionary" ], "operationId": "dictionaryFields", "summary": "Поля прайса v1 (CSV/XLSX/offers.batch)", "responses": { "200": { "description": "Спецификация полей", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldsDictionary" }, "example": { "version": "1", "fields": [ { "key": "brand", "required": true, "type": "string", "max_length": 60, "headers": [ "бренд", "производитель", "brand" ] }, { "key": "price_kop", "required": true, "type": "integer", "min": 100, "max": 10000000000, "file_key": "price", "file_type": "money_rub" } ], "file": { "formats": [ "csv", "xlsx", "zip" ], "encodings": [ "utf-8", "windows-1251", "utf-16" ], "delimiters": [ ";", "\t", ",", "|" ], "max_file_mb": 100, "max_rows": 500000, "docpart_five_columns": [ "Производитель", "Артикул", "Наименование", "Количество", "Цена" ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/dictionary/fields -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/dictionary/brands": { "get": { "security": [ { "bearer": [] } ], "tags": [ "dictionary" ], "operationId": "dictionaryBrands", "summary": "Канонические бренды и синонимы; бренды по артикулу", "x-rate-limit-class": "search", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 60 }, "description": "Префикс бренда или синонима" }, { "name": "article", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 60 }, "description": "Бренды, у которых есть предложения или кроссы по артикулу" }, { "$ref": "#/components/parameters/Limit200" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Список брендов", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "example": { "items": [ { "brand_id": 17, "name": "FEBI BILSTEIN", "group": null, "country": "DE", "kind": "aftermarket", "aliases": [ "FEBI", "FEBIBILSTEIN" ] } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s \"https://k-247.ru/api/v1/dictionary/brands?q=feb&limit=20\" -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/dictionary/statuses": { "get": { "security": [ { "bearer": [] } ], "tags": [ "dictionary" ], "operationId": "dictionaryStatuses", "summary": "Коды статусов заказа, строки, причин отказа, импорта, событий", "responses": { "200": { "description": "Справочник", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusesDictionary" }, "example": { "order_statuses": [ { "code": "awaiting_confirmation", "name": "Ожидает подтверждения" }, { "code": "cancelled", "name": "Отменён" } ], "line_statuses": [ { "code": "confirmed", "name": "Подтверждена" } ], "reject_reasons": [ { "code": "out_of_stock", "name": "Нет в наличии", "counts_as_refusal": true } ], "import_statuses": [ "awaiting_mapping", "queued", "running", "held", "publishing", "published", "failed", "rejected" ], "webhook_events": [ "order.created", "order.line_confirmed", "order.line_rejected", "order.line_cancelled", "order.shipped", "import.finished", "import.held", "price.stale" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/dictionary/statuses -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/dictionary/exchange": { "get": { "security": [ { "bearer": [] } ], "tags": [ "dictionary" ], "operationId": "dictionaryExchange", "summary": "Справочник биржи: коды перечислений и подписи, регионы, фотохостинги, пределы", "description": "Без права ключа. На вход методы биржи принимают код или подпись (без учёта регистра, «ё» и вида тире).\n\nlimits — пределы окружения ключа: у test-ключа requests_per_hour — 0,2 от боевого (целое, не меньше 1), active_api_requests — 20.", "responses": { "200": { "description": "Справочник", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeDictionary" }, "example": { "version": "1", "exchanges": [ { "code": "new", "name": "Новые запчасти" }, { "code": "used", "name": "Б/у запчасти" }, { "code": "all", "name": "Все варианты" } ], "vgroups": [ { "code": "car", "name": "Легковые", "markets": true }, { "code": "truck", "name": "Грузовые", "markets": true }, { "code": "special", "name": "Спецтехника", "markets": false }, { "code": "equip", "name": "Доп. оборудование", "markets": false }, { "code": "other", "name": "Иное", "markets": false } ], "markets": [ { "code": "eu", "name": "Европа" }, { "code": "cn", "name": "Китай" }, { "code": "jp", "name": "Япония" }, { "code": "kr", "name": "Корея" }, { "code": "us", "name": "США" }, { "code": "ru", "name": "Россия" } ], "deadlines": [ { "code": "today", "name": "сегодня", "expires": "end_of_day_msk" }, { "code": "days_2_3", "name": "2-3 дня", "hours": 72 }, { "code": "week", "name": "неделя", "hours": 168 } ], "priorities": [ { "code": "fast", "name": "быстрее" }, { "code": "cheap", "name": "дешевле" }, { "code": "any", "name": "все" } ], "pickups": [ { "code": "delivery", "name": "доставка" }, { "code": "pickup", "name": "самовывоз" } ], "deliveries": [ { "code": "main", "name": "основной" }, { "code": "pickup", "name": "самовывоз" }, { "code": "express", "name": "экспресс (2 часа)" } ], "payments": [ { "code": "balance", "name": "с баланса" }, { "code": "invoice", "name": "счёт" }, { "code": "card_on_delivery", "name": "картой при получении" } ], "vats": [ { "code": "vat22", "name": "НДС 22%" }, { "code": "vat5", "name": "НДС 5%" }, { "code": "no_vat", "name": "Без НДС" } ], "terms": [ { "code": "in_stock", "name": "В наличии", "days": 0 }, { "code": "hours_3", "name": "через 3 часа", "days": 0 }, { "code": "tomorrow_am", "name": "завтра с утра", "days": 1 }, { "code": "days_2_3", "name": "2-3 дня", "days": 3 }, { "code": "days_4_5", "name": "4-5 дней", "days": 5 }, { "code": "week", "name": "через неделю", "days": 7 }, { "code": "on_order", "name": "под заказ", "days": null } ], "regions": [ "Москва", "Самарская область", "Санкт-Петербург" ], "request_statuses": [ "active", "done", "closed", "expired" ], "proposal_statuses": [ "draft", "sent", "partial", "accepted", "rejected", "superseded", "withdrawn", "closed", "done", "returned" ], "line_statuses": [ "pending", "accepted", "rejected", "closed" ], "max_proposals": { "min": 0, "max": 50, "cabinet": [ 0 ] }, "photo_hosts": [ "disk.yandex.ru", "cloud.mail.ru", "drive.google.com", "imgur.com" ], "limits": { "items_per_request": 100, "lines_per_proposal": 200, "variants_per_item": 20, "accept_lines": 200, "requests_per_hour": 60, "active_api_requests": 300, "replace_min_sec": 300, "replaces_per_request": 10, "sandbox_active_requests": 20 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/dictionary/exchange -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/seller/pricelists": { "post": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerUploadPricelist", "summary": "Загрузка файла прайса в конвейер импорта", "x-scope": "offers", "x-rate-limit-class": "bulk", "x-idempotency": "required", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "replace", "upsert" ], "default": "replace" }, "description": "Режим" }, { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 20 }, "description": "Код склада по умолчанию" }, { "name": "source_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Источник компании kind=file|api" }, { "name": "filename", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Имя файла для сырого тела" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "mode": { "type": "string", "enum": [ "replace", "upsert" ] }, "warehouse": { "type": "string" }, "profile": { "type": "string", "description": "JSON профиля колонок" } } }, "example": { "file": "price.csv (файл прайса: CSV, XLSX, XLS, XML или ZIP)", "mode": "replace", "warehouse": "MAIN" } }, "text/csv": { "schema": { "type": "string", "format": "binary" }, "example": "Производитель;Артикул;Наименование;Количество;Цена\nFEBI BILSTEIN;01-089;Термостат;12;1234,50\n" }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/zip": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "202": { "description": "Импорт поставлен в очередь", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportAccepted" }, "example": { "import_id": "imp_7d2f1c9a0b", "status": "queued", "env": "live", "mode": "replace", "source_id": "src_91ab", "status_url": "/api/v1/seller/imports/imp_7d2f1c9a0b" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://k-247.ru/api/v1/seller/pricelists?mode=replace&warehouse=MAIN\" -H \"Authorization: Bearer $K247_TOKEN\" -H \"Idempotency-Key: price-2026-09-15\" -F \"file=@price.csv\"" } ], "description": "Загрузка файла прайса в конвейер импорта Юридические ворота (M.2.5): боевой ключ компании, администратор которой не принял документы площадки, — 403 LEGAL_NEEDS." } }, "/seller/imports": { "get": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerListImports", "summary": "Импорты компании", "x-scope": "offers", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Статусы через запятую" }, { "$ref": "#/components/parameters/Since" }, { "$ref": "#/components/parameters/Limit200" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Список", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ImportSummary" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "example": { "items": [ { "import_id": "imp_7d2f1c9a0b", "status": "published", "phase": "zero", "env": "live", "channel": "api", "mode": "replace", "source_id": "src_91ab", "filename": "price.csv", "rows_total": 48210, "counters": { "added": 120, "updated": 3400, "unchanged": 44580, "adopted": 0, "zeroed": 15, "skipped": 110, "unknown_brands": 4, "skipped_newer": 0 }, "held_reason": [], "created_at": "2026-09-15T09:00:00.000Z", "finished_at": "2026-09-15T09:01:40.000Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s \"https://k-247.ru/api/v1/seller/imports?status=held&limit=20\" -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/seller/imports/{id}": { "get": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerGetImport", "summary": "Статус и отчёт импорта", "x-scope": "offers", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "errors_offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 5000 }, "description": "Смещение списка ошибок" } ], "responses": { "200": { "description": "Отчёт", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportReport" }, "example": { "import_id": "imp_7d2f1c9a0b", "status": "held", "phase": "check", "env": "live", "channel": "api", "mode": "replace", "source_id": "src_91ab", "filename": "price.csv", "rows_total": 48210, "counters": { "added": 120, "updated": 3400, "unchanged": 44580, "adopted": 0, "zeroed": 15, "skipped": 110, "unknown_brands": 4, "skipped_newer": 0 }, "held_reason": [ { "code": "VANISHED", "value": 42.1, "limit": 30, "message": "Пропало 42,1 % позиций (порог 30 %)" } ], "created_at": "2026-09-15T09:00:00.000Z", "finished_at": null, "format": "csv", "encoding": "windows-1251", "delimiter": ";", "rows_valid": 48100, "progress": 48210, "checks": { "vanished_pct": 42.1, "price_change_share": 3.2 }, "errors_total": 110, "errors": [ { "row": 17, "field": "brand", "code": "BRAND_UNKNOWN", "message": "Бренд «Febi Bilst.» не найден в справочнике", "raw": "Febi Bilst.;01-089;Термостат;1234,50;12" } ], "unknown_brands": [ { "sample": "Febi Bilst.", "rows": 12 } ], "started_at": "2026-09-15T09:00:02.000Z", "held_expires_at": "2026-09-16T09:00:40.000Z", "error": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/seller/imports/imp_7d2f1c9a0b -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/seller/imports/{id}/approve": { "post": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerApproveImport", "summary": "Опубликовать импорт в статусе held", "x-scope": "offers", "x-idempotency": "recommended", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionComment" }, "example": { "comment": "Сезонная распродажа, так и задумано" } } } }, "responses": { "200": { "description": "Импорт публикуется", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportSummary" }, "example": { "import_id": "imp_7d2f1c9a0b", "status": "publishing", "phase": "zero", "env": "live", "channel": "api", "mode": "replace", "source_id": "src_91ab", "filename": "price.csv", "rows_total": 48210, "counters": { "added": 120, "updated": 3400, "unchanged": 44580, "adopted": 0, "zeroed": 15, "skipped": 110, "unknown_brands": 4, "skipped_newer": 0 }, "held_reason": [], "created_at": "2026-09-15T09:00:00.000Z", "finished_at": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "Повтор approve уже одобренного — 200 с Idempotent-Replayed: state. Публикация пропускает строки, изменённые другим источником после разбора (counters.skipped_newer). Новый импорт того же источника переводит held в rejected (IMPORT_SUPERSEDED). Юридические ворота (M.2.5): боевой ключ компании, администратор которой не принял документы площадки, — 403 LEGAL_NEEDS.", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/seller/imports/imp_7d2f1c9a0b/approve -H \"Authorization: Bearer $K247_TOKEN\" -H \"Content-Type: application/json\" -d '{\"comment\":\"Сезонная распродажа\"}'" } ] } }, "/seller/imports/{id}/reject": { "post": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerRejectImport", "summary": "Отклонить импорт в статусе held", "x-scope": "offers", "x-idempotency": "recommended", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionComment" }, "example": { "comment": "Выгрузка неполная" } } } }, "responses": { "200": { "description": "Импорт отклонён", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportSummary" }, "example": { "import_id": "imp_7d2f1c9a0b", "status": "rejected", "phase": "zero", "env": "live", "channel": "api", "mode": "replace", "source_id": "src_91ab", "filename": "price.csv", "rows_total": 48210, "counters": { "added": 120, "updated": 3400, "unchanged": 44580, "adopted": 0, "zeroed": 15, "skipped": 110, "unknown_brands": 4, "skipped_newer": 0 }, "held_reason": [], "created_at": "2026-09-15T09:00:00.000Z", "finished_at": "2026-09-15T09:01:40.000Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/seller/imports/imp_7d2f1c9a0b/reject -H \"Authorization: Bearer $K247_TOKEN\" -H \"Content-Type: application/json\" -d '{\"comment\":\"Выгрузка неполная\"}'" } ] } }, "/seller/offers/batch": { "post": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerOffersBatch", "summary": "Синхронный upsert до 1000 предложений", "x-scope": "offers", "x-rate-limit-class": "bulk", "x-idempotency": "required", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OffersBatchRequest" }, "example": { "warehouse": "MAIN", "offers": [ { "brand": "FEBI BILSTEIN", "article": "01-089", "name": "Термостат", "price_kop": 123450, "qty": 12, "term_days_min": 1, "term_days_max": 3, "external_id": "A-778", "updated_at": "2026-09-15T08:59:00.000Z" }, { "external_id": "A-779", "qty": 0 } ] } } } }, "responses": { "200": { "description": "Результат построчно", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OffersBatchResponse" }, "example": { "dry_run": false, "received": 3, "created": 1, "updated": 1, "unchanged": 0, "skipped": 1, "results": [ { "index": 0, "status": "created", "offer_id": "p_3c1f9e2a7b", "external_id": "A-778" }, { "index": 1, "status": "updated", "offer_id": "p_77aa01bc3d", "external_id": "A-779" }, { "index": 2, "status": "skipped", "offer_id": null, "external_id": "A-780", "code": "PRICE_BELOW_MIN", "field": "price_kop", "message": "Цена меньше 1 ₽" } ], "errors": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/seller/offers/batch -H \"Authorization: Bearer $K247_TOKEN\" -H \"Idempotency-Key: stock-20260915-0900\" -H \"Content-Type: application/json\" -d '{\"warehouse\":\"MAIN\",\"offers\":[{\"external_id\":\"A-779\",\"qty\":0,\"updated_at\":\"2026-09-15T08:59:00.000Z\"}]}'" } ], "description": "Синхронный upsert до 1000 предложений Юридические ворота (M.2.5): боевой ключ компании, администратор которой не принял документы площадки, — 403 LEGAL_NEEDS." } }, "/seller/offers": { "get": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerListOffers", "summary": "Предложения компании постранично (синхронизация по since)", "x-scope": "offers", "parameters": [ { "$ref": "#/components/parameters/SinceSeq" }, { "$ref": "#/components/parameters/Since" }, { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "article", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "stale", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } }, { "$ref": "#/components/parameters/Limit200" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Страница", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SellerOffer" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "example": { "items": [ { "offer_id": "p_3c1f9e2a7b", "external_id": "A-778", "brand": "FEBI BILSTEIN", "brand_id": 17, "article": "01-089", "article_norm": "01089", "name": "Термостат", "price_kop": 123450, "currency": "RUB", "qty": 12, "qty_reserved": 2, "qty_available": 10, "multiplicity": 1, "min_order": 1, "term_days_min": 1, "term_days_max": 3, "probability": 95, "warehouse": "СПб-1", "condition": "new", "vat": "НДС 22%", "returnable": true, "source_id": "src_api01", "source_kind": "api", "visible": true, "stale": false, "withdrawn": false, "change_seq": 184223, "updated_at": "2026-09-15T09:00:01.000Z", "source_updated_at": "2026-09-15T08:59:00.000Z" } ], "next_cursor": "eyJzIjoxODQyMjN9", "has_more": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "Сортировка change_seq ASC при since_seq (синхронизация), иначе updated_at ASC.", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s \"https://k-247.ru/api/v1/seller/offers?since_seq=184000&limit=200\" -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/seller/offers/{external_id}": { "delete": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerZeroOffer", "summary": "Снять позицию по внешнему коду (остаток 0, отметка withdrawn)", "x-scope": "offers", "parameters": [ { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^\\x00-\\x1f]{1,64}$" } }, { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Код склада; обязателен, если позиция с этим external_id есть на нескольких складах (иначе 409 AMBIGUOUS_OFFER)" } ], "responses": { "200": { "description": "Позиция обнулена", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "offer_id": { "type": "string" }, "external_id": { "type": "string" }, "qty": { "type": "integer" }, "dry_run": { "type": "boolean" }, "warehouse": { "type": "string" }, "withdrawn": { "type": "boolean" } } }, "example": { "offer_id": "p_3c1f9e2a7b", "external_id": "A-778", "warehouse": "MAIN", "qty": 0, "withdrawn": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "Строка не удаляется: stock = 0 и withdrawn = true; снятая позиция покупателю не показывается, следующий batch или импорт с любым qty её возвращает. external_id в пути — percent-encoded (может содержать / и не-ASCII), 1–64 символа без управляющих. Test-ключ — dry_run.", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X DELETE \"https://k-247.ru/api/v1/seller/offers/A-778?warehouse=MAIN\" -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/seller/warehouses": { "get": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerGetWarehouses", "summary": "Склады компании", "x-scope": "offers", "responses": { "200": { "description": "Склады", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseList" }, "example": { "items": [ { "code": "MAIN", "name": "Санкт-Петербург", "city": "Санкт-Петербург", "city_id": 2, "region": "Санкт-Петербург", "country": "RU", "address": "ул. Софийская, 8", "is_default": true, "active": true, "delivery_terms": { "extra_days": 0, "note": "" }, "offers": 1240 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/seller/warehouses -H \"Authorization: Bearer $K247_TOKEN\"" } ] }, "put": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerPutWarehouses", "summary": "Полный список складов (upsert по коду)", "x-scope": "offers", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseListInput" }, "example": { "items": [ { "code": "MAIN", "name": "Основной", "city": "Санкт-Петербург", "region": "Санкт-Петербург", "country": "RU", "address": "ул. Софийская, 8", "is_default": true, "delivery_terms": { "extra_days": 0 } } ] } } } }, "responses": { "200": { "description": "Склады", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseList" }, "example": { "items": [ { "code": "MAIN", "name": "Санкт-Петербург", "city": "Санкт-Петербург", "city_id": 2, "region": "Санкт-Петербург", "country": "RU", "address": "ул. Софийская, 8", "is_default": true, "active": true, "delivery_terms": { "extra_days": 0, "note": "" }, "offers": 1240 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X PUT https://k-247.ru/api/v1/seller/warehouses -H \"Authorization: Bearer $K247_TOKEN\" -H \"Content-Type: application/json\" -d '{\"items\":[{\"code\":\"MAIN\",\"name\":\"Основной\",\"city\":\"Санкт-Петербург\",\"country\":\"RU\",\"is_default\":true}]}'" } ] } }, "/seller/orders": { "get": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerListOrders", "summary": "Заказы продавца (опрос по since)", "x-scope": "orders | exchange", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Коды статусов через запятую; awaiting_confirmation — есть строки на подтверждении" }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "shop", "exchange" ] }, "description": "shop — заказы магазина, exchange — заказы из КП биржи" }, { "$ref": "#/components/parameters/SinceSeq" }, { "$ref": "#/components/parameters/Since" }, { "$ref": "#/components/parameters/Limit100" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Страница", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SellerOrder" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "example": { "items": [ { "order_id": "ord_5e1a2b3c4d", "number": "2609-1190", "status": "awaiting_confirmation", "status_name": "Ожидает подтверждения", "test": false, "created_at": "2026-09-15T09:05:00.000Z", "updated_at": "2026-09-15T09:05:00.000Z", "change_seq": 184230, "confirm_deadline_at": "2026-09-15T11:05:00.000Z", "auto_cancel_at": "2026-09-15T13:05:00.000Z", "buyer": { "code": "Покупатель", "city": "Санкт-Петербург" }, "delivery": { "type": "основной", "address": "ул. Салова, 27", "express": false }, "payment": "с баланса", "comment": "", "currency": "RUB", "total_kop": 246900, "delivery_kop": 0, "accounting_total_rub": 2469, "lines": [ { "line_id": "l_9a8b7c6d5e", "offer_id": "p_3c1f9e2a7b", "external_id": "A-778", "brand": "FEBI BILSTEIN", "article": "01-089", "name": "Термостат", "qty": 2, "confirmed_qty": null, "shipped_qty": 0, "price_kop": 123450, "sum_kop": 246900, "status": "awaiting_confirmation", "reject_reason_code": null, "term_days_min": 1, "term_days_max": 3, "term_days_confirmed": null, "warehouse": "СПб-1", "external_order_ref": null, "plate": "" } ], "documents": { "invoice": "", "upd": "", "ksf": "" } } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "Live-ключ — заказы test=false. Test-ключ — только test-заказы песочницы своей компании (покупатель c_sandbox). Сортировка change_seq ASC при since_seq, иначе updated_at ASC. Ключ с правом exchange без orders видит только заказы из КП (source exchange), остальные — 404.", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s \"https://k-247.ru/api/v1/seller/orders?status=awaiting_confirmation&since_seq=184000\" -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/seller/orders/{id}": { "get": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerGetOrder", "summary": "Заказ продавца", "x-scope": "orders | exchange", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Заказ", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerOrder" }, "example": { "order_id": "ord_5e1a2b3c4d", "number": "2609-1190", "status": "awaiting_confirmation", "status_name": "Ожидает подтверждения", "test": false, "created_at": "2026-09-15T09:05:00.000Z", "updated_at": "2026-09-15T09:05:00.000Z", "change_seq": 184230, "confirm_deadline_at": "2026-09-15T11:05:00.000Z", "auto_cancel_at": "2026-09-15T13:05:00.000Z", "buyer": { "code": "Покупатель", "city": "Санкт-Петербург" }, "delivery": { "type": "основной", "address": "ул. Салова, 27", "express": false }, "payment": "с баланса", "comment": "", "currency": "RUB", "total_kop": 246900, "delivery_kop": 0, "accounting_total_rub": 2469, "lines": [ { "line_id": "l_9a8b7c6d5e", "offer_id": "p_3c1f9e2a7b", "external_id": "A-778", "brand": "FEBI BILSTEIN", "article": "01-089", "name": "Термостат", "qty": 2, "confirmed_qty": null, "shipped_qty": 0, "price_kop": 123450, "sum_kop": 246900, "status": "awaiting_confirmation", "reject_reason_code": null, "term_days_min": 1, "term_days_max": 3, "term_days_confirmed": null, "warehouse": "СПб-1", "external_order_ref": null, "plate": "" } ], "documents": { "invoice": "", "upd": "", "ksf": "" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/seller/orders/ord_5e1a2b3c4d -H \"Authorization: Bearer $K247_TOKEN\"" } ], "description": "Заказ продавца Ключ с правом exchange без orders видит только заказы из КП (source exchange), остальные — 404." } }, "/seller/orders/{id}/confirm": { "post": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerConfirmOrder", "summary": "Подтверждение целиком или построчно", "x-scope": "orders | exchange", "x-idempotency": "recommended", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmRequest" }, "example": { "lines": [ { "line_id": "l_9a8b7c6d5e", "qty": 1, "term_days": 2, "external_order_ref": "ЗК-5512" } ] } } } }, "responses": { "200": { "description": "Заказ после подтверждения", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerOrder" }, "example": { "order_id": "ord_5e1a2b3c4d", "number": "2609-1190", "status": "assembling", "status_name": "В сборке", "test": false, "created_at": "2026-09-15T09:05:00.000Z", "updated_at": "2026-09-15T09:05:00.000Z", "change_seq": 184230, "confirm_deadline_at": "2026-09-15T11:05:00.000Z", "auto_cancel_at": "2026-09-15T13:05:00.000Z", "buyer": { "code": "Покупатель", "city": "Санкт-Петербург" }, "delivery": { "type": "основной", "address": "ул. Салова, 27", "express": false }, "payment": "с баланса", "comment": "", "currency": "RUB", "total_kop": 123450, "delivery_kop": 0, "accounting_total_rub": 1234.5, "lines": [ { "line_id": "l_9a8b7c6d5e", "offer_id": "p_3c1f9e2a7b", "external_id": "A-778", "brand": "FEBI BILSTEIN", "article": "01-089", "name": "Термостат", "qty": 2, "confirmed_qty": 1, "shipped_qty": 0, "price_kop": 123450, "sum_kop": 123450, "status": "confirmed", "reject_reason_code": "partial_stock", "term_days_min": 1, "term_days_max": 3, "term_days_confirmed": 2, "warehouse": "СПб-1", "external_order_ref": "ЗК-5512", "plate": "" } ], "documents": { "invoice": "", "upd": "", "ksf": "" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "Идемпотентность по состоянию: если все переданные строки уже в целевом статусе с теми же параметрами, ответ 200 с текущим заказом и заголовком Idempotent-Replayed: state; другой статус или другие параметры — 409 INVALID_STATE, ничего не меняется. Ключ с правом exchange без orders видит только заказы из КП (source exchange), остальные — 404. Заказ из КП биржи не подтверждается и не отклоняется: 409 EXCHANGE_ORDER, в details — {source, proposal_id, actions}.", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/seller/orders/ord_5e1a2b3c4d/confirm -H \"Authorization: Bearer $K247_TOKEN\" -H \"Content-Type: application/json\" -d '{\"lines\":[{\"line_id\":\"l_9a8b7c6d5e\",\"qty\":1,\"term_days\":2}]}'" } ] } }, "/seller/orders/{id}/reject": { "post": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerRejectOrder", "summary": "Отказ по заказу или строкам", "x-scope": "orders | exchange", "x-idempotency": "recommended", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectRequest" }, "example": { "lines": [ { "line_id": "l_9a8b7c6d5e", "reason": "out_of_stock", "comment": "Последнюю продали в рознице" } ] } } } }, "responses": { "200": { "description": "Заказ после отказа", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerOrder" }, "example": { "order_id": "ord_5e1a2b3c4d", "number": "2609-1190", "status": "cancelled", "status_name": "Отменён", "test": false, "created_at": "2026-09-15T09:05:00.000Z", "updated_at": "2026-09-15T09:05:00.000Z", "change_seq": 184230, "confirm_deadline_at": "2026-09-15T11:05:00.000Z", "auto_cancel_at": "2026-09-15T13:05:00.000Z", "buyer": { "code": "Покупатель", "city": "Санкт-Петербург" }, "delivery": { "type": "основной", "address": "ул. Салова, 27", "express": false }, "payment": "с баланса", "comment": "", "currency": "RUB", "total_kop": 0, "delivery_kop": 0, "accounting_total_rub": 0, "lines": [ { "line_id": "l_9a8b7c6d5e", "offer_id": "p_3c1f9e2a7b", "external_id": "A-778", "brand": "FEBI BILSTEIN", "article": "01-089", "name": "Термостат", "qty": 2, "confirmed_qty": null, "shipped_qty": 0, "price_kop": 123450, "sum_kop": 0, "status": "rejected", "reject_reason_code": "out_of_stock", "term_days_min": 1, "term_days_max": 3, "term_days_confirmed": null, "warehouse": "СПб-1", "external_order_ref": null, "plate": "" } ], "documents": { "invoice": "", "upd": "", "ksf": "" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "Идемпотентность по состоянию: если все переданные строки уже в целевом статусе с теми же параметрами, ответ 200 с текущим заказом и заголовком Idempotent-Replayed: state; другой статус или другие параметры — 409 INVALID_STATE, ничего не меняется. Ключ с правом exchange без orders видит только заказы из КП (source exchange), остальные — 404. Заказ из КП биржи не подтверждается и не отклоняется: 409 EXCHANGE_ORDER, в details — {source, proposal_id, actions}.", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/seller/orders/ord_5e1a2b3c4d/reject -H \"Authorization: Bearer $K247_TOKEN\" -H \"Content-Type: application/json\" -d '{\"lines\":[{\"line_id\":\"l_9a8b7c6d5e\",\"reason\":\"out_of_stock\"}]}'" } ] } }, "/seller/orders/{id}/ship": { "post": { "security": [ { "bearer": [] } ], "tags": [ "seller" ], "operationId": "sellerShipOrder", "summary": "Отгрузка, в том числе частичная по строкам", "x-scope": "orders | exchange", "x-idempotency": "recommended", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipRequest" }, "example": { "lines": [ "l_9a8b7c6d5e" ], "track": "CDEK 1234567890", "upd_number": "УПД-2609-1190" } } } }, "responses": { "200": { "description": "Заказ после отгрузки", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerOrder" }, "example": { "order_id": "ord_5e1a2b3c4d", "number": "2609-1190", "status": "shipped", "status_name": "Отгружен", "test": false, "created_at": "2026-09-15T09:05:00.000Z", "updated_at": "2026-09-15T09:05:00.000Z", "change_seq": 184230, "confirm_deadline_at": "2026-09-15T11:05:00.000Z", "auto_cancel_at": "2026-09-15T13:05:00.000Z", "buyer": { "code": "Покупатель", "city": "Санкт-Петербург" }, "delivery": { "type": "основной", "address": "ул. Салова, 27", "express": false }, "payment": "с баланса", "comment": "", "currency": "RUB", "total_kop": 246900, "delivery_kop": 0, "accounting_total_rub": 2469, "lines": [ { "line_id": "l_9a8b7c6d5e", "offer_id": "p_3c1f9e2a7b", "external_id": "A-778", "brand": "FEBI BILSTEIN", "article": "01-089", "name": "Термостат", "qty": 2, "confirmed_qty": 2, "shipped_qty": 2, "price_kop": 123450, "sum_kop": 246900, "status": "shipped", "reject_reason_code": null, "term_days_min": 1, "term_days_max": 3, "term_days_confirmed": null, "warehouse": "СПб-1", "external_order_ref": null, "plate": "" } ], "documents": { "invoice": "", "upd": "", "ksf": "" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "Идемпотентность по состоянию: если все переданные строки уже в целевом статусе с теми же параметрами, ответ 200 с текущим заказом и заголовком Idempotent-Replayed: state; другой статус или другие параметры — 409 INVALID_STATE, ничего не меняется. Ключ с правом exchange без orders видит только заказы из КП (source exchange), остальные — 404. Заказ из КП биржи (source exchange) отгружается целиком: lines на отгрузку не влияют, но переданные line_id должны быть из этого заказа, иначе 400 VALIDATION_FAILED; у строк такого заказа status — null, shipped_qty — 0, отгрузка видна по status заказа (shipped).", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/seller/orders/ord_5e1a2b3c4d/ship -H \"Authorization: Bearer $K247_TOKEN\" -H \"Content-Type: application/json\" -d '{\"track\":\"CDEK 1234567890\"}'" } ] } }, "/seller/exchange/requests": { "get": { "security": [ { "bearer": [] } ], "tags": [ "exchange-seller" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "sellerListExchangeRequests", "summary": "Лента заявок покупателей (набор — как у сотрудника в кабинете), синхронизация по since_seq", "description": "Набор: заявки не своей компании, видимые продавцу (реквизиты проверены, биржа по типу компании, регион заявки = регион компании у ключа own) или с КП компании в любом статусе; test-ключ — только тестовые заявки робота для своей компании. Без since_seq и status — действующие заявки и заявки с КП компании; с since_seq — весь набор в любом статусе. Покупатель — псевдоним buyer.ref; госномера и адреса получения нет, свободный текст очищен от контактов.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Через запятую: active, done, closed, expired или all" }, { "name": "exchange", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new", "used" ] } }, { "name": "vgroup", "in": "query", "required": false, "description": "Группа техники из справочника. Заявки группы «Иное» (other) проходят фильтр любой группы; vgroup=other — только они", "schema": { "type": "string", "enum": [ "car", "truck", "special", "equip", "other" ] } }, { "name": "market", "in": "query", "required": false, "description": "Рынок из справочника. Фильтр проходят и заявки с рынком «Иное» — легковые и грузовые без рынка (market = null), и заявки группы «Иное»", "schema": { "type": "string", "enum": [ "eu", "cn", "jp", "kr", "us", "ru" ] } }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Марка без учёта регистра" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "own", "all" ] }, "description": "own — сузить ленту ключа all; all ключом own — 400" }, { "name": "answered", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true — только с КП компании, false — без КП" }, { "$ref": "#/components/parameters/SinceSeq" }, { "$ref": "#/components/parameters/Since" }, { "$ref": "#/components/parameters/Limit100" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Страница заявок", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerExchangeRequestList" }, "example": { "items": [ { "exchange_request_id": "r_8c1d2e3f4a", "number": "2609-412", "status": "active", "exchange": "new", "test": false, "created_at": "2026-09-22T07:10:00.000Z", "updated_at": "2026-09-22T07:42:11.000Z", "revision": 0, "revised_at": null, "expires_at": "2026-09-22T20:59:59.000Z", "deadline": "today", "deadline_name": "сегодня", "priority": "fast", "priority_name": "быстрее", "vehicle": { "vgroup": "truck", "market": "eu", "category": "Грузовые / Европа", "brand": "MAN", "model": "TGX", "year": "2016", "vin": "WMA06XZZ0FP000001" }, "buyer": { "ref": "П-7F3A9C", "city": "Санкт-Петербург" }, "city": "Санкт-Петербург", "region": "Санкт-Петербург", "delivery": "main", "delivery_name": "основной", "pickup": "delivery", "pickup_name": "доставка", "payment": "invoice", "payment_name": "счёт", "comment": "Машина на линии, звонить [скрыто]", "items": [ { "item_id": "i_1a2b3c4d5e", "position": 1, "name": "Фильтр масляный", "qty": 2, "comment": "по VIN", "open": true }, { "item_id": "i_2b3c4d5e6f", "position": 2, "name": "Ремень приводной", "qty": 1, "comment": "", "open": true } ], "max_proposals": 5, "competition": { "proposals": 3, "sellers": 3, "limit": 5, "slots_left": 2, "my_rank": 2, "my_value_kop": 452900, "basis": "accept_plan" }, "my_proposals": [ { "proposal_id": "o_5f6a7b8c9d", "number": "ТТ-014-00131", "status": "sent", "value_kop": 452900 } ], "current_proposal_id": "o_5f6a7b8c9d", "can_propose": true, "cannot_propose_reason": null, "replace_available_at": null, "unread_messages": 1, "change_seq": 184300 } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s \"https://k-247.ru/api/v1/seller/exchange/requests?since_seq=0&limit=100\" -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/seller/exchange/requests/{id}": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "security": [ { "bearer": [] } ], "tags": [ "exchange-seller" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "sellerGetExchangeRequest", "summary": "Заявка набора продавца в любом статусе", "description": "Заявки нет, она другого окружения или не входит в набор — 404 (недоступное не отличается от несуществующего).", "responses": { "200": { "description": "Заявка", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerExchangeRequest" }, "example": { "exchange_request_id": "r_8c1d2e3f4a", "number": "2609-412", "status": "active", "exchange": "new", "test": false, "created_at": "2026-09-22T07:10:00.000Z", "updated_at": "2026-09-22T07:42:11.000Z", "revision": 0, "revised_at": null, "expires_at": "2026-09-22T20:59:59.000Z", "deadline": "today", "deadline_name": "сегодня", "priority": "fast", "priority_name": "быстрее", "vehicle": { "vgroup": "truck", "market": "eu", "category": "Грузовые / Европа", "brand": "MAN", "model": "TGX", "year": "2016", "vin": "WMA06XZZ0FP000001" }, "buyer": { "ref": "П-7F3A9C", "city": "Санкт-Петербург" }, "city": "Санкт-Петербург", "region": "Санкт-Петербург", "delivery": "main", "delivery_name": "основной", "pickup": "delivery", "pickup_name": "доставка", "payment": "invoice", "payment_name": "счёт", "comment": "Машина на линии, звонить [скрыто]", "items": [ { "item_id": "i_1a2b3c4d5e", "position": 1, "name": "Фильтр масляный", "qty": 2, "comment": "по VIN", "open": true }, { "item_id": "i_2b3c4d5e6f", "position": 2, "name": "Ремень приводной", "qty": 1, "comment": "", "open": true } ], "max_proposals": 5, "competition": { "proposals": 3, "sellers": 3, "limit": 5, "slots_left": 2, "my_rank": 2, "my_value_kop": 452900, "basis": "accept_plan" }, "my_proposals": [ { "proposal_id": "o_5f6a7b8c9d", "number": "ТТ-014-00131", "status": "sent", "value_kop": 452900 } ], "current_proposal_id": "o_5f6a7b8c9d", "can_propose": true, "cannot_propose_reason": null, "replace_available_at": null, "unread_messages": 1, "change_seq": 184300 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/seller/exchange/requests/r_8c1d2e3f4a -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/seller/exchange/requests/{id}/proposals": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "security": [ { "bearer": [] } ], "tags": [ "exchange-seller" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "sellerCreateProposal", "summary": "Отправить КП покупателю (mode send) или сохранить черновик (mode draft)", "x-idempotency": "required", "description": "Те же проверки, что у кнопок кабинета: доступ к заявке, срок, лимит КП (считает продавцов), строки по позициям заявки, строка по выкупленной позиции — 409 ALREADY_BOUGHT, контакты в тексте — 422 CONTACTS_FORBIDDEN. Повторная отправка заменяет КП sent (superseded); частично купленное КП живёт рядом. Замена через API — не чаще раза в 5 минут и не больше 10 на заявку (409 PROPOSAL_REPLACE_LIMIT). Юридические ворота: боевой ключ компании без принятых документов — 403 LEGAL_NEEDS.\n\nПредел замен (M.10.2) считает повторные отправки КП компании по заявке: замену действующего КП (superseded) и отправку после снятия своего отправленного КП (withdrawn). Снятые черновики, которые не отправлялись, не считаются. Тексты КП (комментарий, строки, путь ссылки на фото) не должны содержать контактов и сведений о продавце: реквизитов, названия, адреса компании и складов, фамилий сотрудников — 422 CONTACTS_FORBIDDEN с kind в details.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalInput" }, "example": { "mode": "send", "comment": "Отгрузка со склада СПб в день оплаты", "lines": [ { "item_id": "i_1a2b3c4d5e", "brand": "MANN", "article": "W 950/26", "oem": "51.05504-0108", "price_kop": 123450, "qty": 2, "vat": "vat22", "term": "in_stock", "stock": 12, "comment": "оригинальная упаковка", "external_id": "A-778" }, { "item_id": "i_1a2b3c4d5e", "brand": "FILTRON", "article": "OP 592/7", "price_kop": 98000, "qty": 2, "vat": "vat22", "term_days": 2 }, { "item_id": "i_2b3c4d5e6f", "brand": "Contitech", "article": "6PK1873", "price_kop": 210000, "qty": 1, "vat": "vat22", "term": "in_stock", "photo_url": "https://disk.yandex.ru/i/Ab3dE6fG" } ] } } } }, "responses": { "201": { "description": "КП продавца", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerProposal" }, "example": { "proposal_id": "o_6a7b8c9d0e", "number": "ТТ-014-00132", "exchange_request_id": "r_8c1d2e3f4a", "status": "sent", "test": false, "via": "api", "replaces_proposal_id": null, "created_at": "2026-09-22T07:45:02.000Z", "updated_at": "2026-09-22T07:45:02.000Z", "comment": "Отгрузка со склада СПб в день оплаты", "value_kop": 406000, "lines_sum_kop": 652900, "coverage": { "items_open": 2, "items_offered": 2, "items_full": 2 }, "lines": [ { "proposal_line_id": "ol_91a2b3c4d5", "item_id": "i_1a2b3c4d5e", "brand": "MANN", "article": "W 950/26", "oem": "51.05504-0108", "price_kop": 123450, "qty": 2, "sum_kop": 246900, "vat": "vat22", "vat_name": "НДС 22%", "term": "in_stock", "term_name": "В наличии", "term_days": 0, "availability": "in_stock", "stock": 12, "comment": "оригинальная упаковка", "photo_url": null, "external_id": "A-778", "status": "pending", "bought_qty": 0, "left_qty": 2, "counter_price_kop": null }, { "proposal_line_id": "ol_92b3c4d5e6", "item_id": "i_1a2b3c4d5e", "brand": "FILTRON", "article": "OP 592/7", "oem": "", "price_kop": 98000, "qty": 2, "sum_kop": 196000, "vat": "vat22", "vat_name": "НДС 22%", "term": "days_2_3", "term_name": "2-3 дня", "term_days": 2, "availability": "on_order", "stock": 0, "comment": "", "photo_url": null, "external_id": null, "status": "pending", "bought_qty": 0, "left_qty": 2, "counter_price_kop": null }, { "proposal_line_id": "ol_93c4d5e6f7", "item_id": "i_2b3c4d5e6f", "brand": "Contitech", "article": "6PK1873", "oem": "", "price_kop": 210000, "qty": 1, "sum_kop": 210000, "vat": "vat22", "vat_name": "НДС 22%", "term": "in_stock", "term_name": "В наличии", "term_days": 0, "availability": "in_stock", "stock": 0, "comment": "", "photo_url": "https://disk.yandex.ru/i/Ab3dE6fG", "external_id": null, "status": "pending", "bought_qty": 0, "left_qty": 1, "counter_price_kop": null } ], "orders": [], "actions": [ "withdraw" ], "counter": null, "competition": { "proposals": 3, "sellers": 3, "limit": 5, "slots_left": 2, "my_rank": 1, "my_value_kop": 406000, "basis": "accept_plan" }, "change_seq": 184311 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/seller/exchange/requests/r_8c1d2e3f4a/proposals -H \"Authorization: Bearer $K247_TOKEN\" -H \"Content-Type: application/json\" -H \"Idempotency-Key: kp-2609-412-1\" -d '{\"comment\":\"Отгрузка в день оплаты\",\"lines\":[{\"item_id\":\"i_1a2b3c4d5e\",\"brand\":\"MANN\",\"article\":\"W 950/26\",\"price_kop\":123450,\"qty\":2,\"vat\":\"vat22\",\"term\":\"in_stock\",\"external_id\":\"A-778\"},{\"item_id\":\"i_2b3c4d5e6f\",\"brand\":\"Contitech\",\"article\":\"6PK1873\",\"price_kop\":210000,\"qty\":1,\"photo_url\":\"https://disk.yandex.ru/i/Ab3dE6fG\"}]}'" } ] } }, "/seller/exchange/proposals": { "get": { "security": [ { "bearer": [] } ], "tags": [ "exchange-seller" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "sellerListProposals", "summary": "КП компании в любом статусе, включая черновики и КП из кабинета (via cabinet)", "parameters": [ { "name": "exchange_request_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Через запятую, по умолчанию все" }, { "$ref": "#/components/parameters/SinceSeq" }, { "$ref": "#/components/parameters/Since" }, { "$ref": "#/components/parameters/Limit100" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Страница КП (без competition)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerProposalList" }, "example": { "items": [ { "proposal_id": "o_6a7b8c9d0e", "number": "ТТ-014-00132", "exchange_request_id": "r_8c1d2e3f4a", "status": "sent", "test": false, "via": "api", "replaces_proposal_id": null, "created_at": "2026-09-22T07:45:02.000Z", "updated_at": "2026-09-22T07:45:02.000Z", "comment": "Отгрузка со склада СПб в день оплаты", "value_kop": 406000, "lines_sum_kop": 652900, "coverage": { "items_open": 2, "items_offered": 2, "items_full": 2 }, "lines": [ { "proposal_line_id": "ol_91a2b3c4d5", "item_id": "i_1a2b3c4d5e", "brand": "MANN", "article": "W 950/26", "oem": "51.05504-0108", "price_kop": 123450, "qty": 2, "sum_kop": 246900, "vat": "vat22", "vat_name": "НДС 22%", "term": "in_stock", "term_name": "В наличии", "term_days": 0, "availability": "in_stock", "stock": 12, "comment": "оригинальная упаковка", "photo_url": null, "external_id": "A-778", "status": "pending", "bought_qty": 0, "left_qty": 2, "counter_price_kop": null }, { "proposal_line_id": "ol_92b3c4d5e6", "item_id": "i_1a2b3c4d5e", "brand": "FILTRON", "article": "OP 592/7", "oem": "", "price_kop": 98000, "qty": 2, "sum_kop": 196000, "vat": "vat22", "vat_name": "НДС 22%", "term": "days_2_3", "term_name": "2-3 дня", "term_days": 2, "availability": "on_order", "stock": 0, "comment": "", "photo_url": null, "external_id": null, "status": "pending", "bought_qty": 0, "left_qty": 2, "counter_price_kop": null }, { "proposal_line_id": "ol_93c4d5e6f7", "item_id": "i_2b3c4d5e6f", "brand": "Contitech", "article": "6PK1873", "oem": "", "price_kop": 210000, "qty": 1, "sum_kop": 210000, "vat": "vat22", "vat_name": "НДС 22%", "term": "in_stock", "term_name": "В наличии", "term_days": 0, "availability": "in_stock", "stock": 0, "comment": "", "photo_url": "https://disk.yandex.ru/i/Ab3dE6fG", "external_id": null, "status": "pending", "bought_qty": 0, "left_qty": 1, "counter_price_kop": null } ], "orders": [], "actions": [ "withdraw" ], "counter": null, "change_seq": 184311 } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s \"https://k-247.ru/api/v1/seller/exchange/proposals?since_seq=0\" -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/seller/exchange/proposals/{id}": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "security": [ { "bearer": [] } ], "tags": [ "exchange-seller" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "sellerGetProposal", "summary": "КП компании", "description": "Чужое КП и КП другого окружения — 404.", "responses": { "200": { "description": "КП", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerProposal" }, "example": { "proposal_id": "o_6a7b8c9d0e", "number": "ТТ-014-00132", "exchange_request_id": "r_8c1d2e3f4a", "status": "sent", "test": false, "via": "api", "replaces_proposal_id": null, "created_at": "2026-09-22T07:45:02.000Z", "updated_at": "2026-09-22T07:45:02.000Z", "comment": "Отгрузка со склада СПб в день оплаты", "value_kop": 406000, "lines_sum_kop": 652900, "coverage": { "items_open": 2, "items_offered": 2, "items_full": 2 }, "lines": [ { "proposal_line_id": "ol_91a2b3c4d5", "item_id": "i_1a2b3c4d5e", "brand": "MANN", "article": "W 950/26", "oem": "51.05504-0108", "price_kop": 123450, "qty": 2, "sum_kop": 246900, "vat": "vat22", "vat_name": "НДС 22%", "term": "in_stock", "term_name": "В наличии", "term_days": 0, "availability": "in_stock", "stock": 12, "comment": "оригинальная упаковка", "photo_url": null, "external_id": "A-778", "status": "pending", "bought_qty": 0, "left_qty": 2, "counter_price_kop": null }, { "proposal_line_id": "ol_92b3c4d5e6", "item_id": "i_1a2b3c4d5e", "brand": "FILTRON", "article": "OP 592/7", "oem": "", "price_kop": 98000, "qty": 2, "sum_kop": 196000, "vat": "vat22", "vat_name": "НДС 22%", "term": "days_2_3", "term_name": "2-3 дня", "term_days": 2, "availability": "on_order", "stock": 0, "comment": "", "photo_url": null, "external_id": null, "status": "pending", "bought_qty": 0, "left_qty": 2, "counter_price_kop": null }, { "proposal_line_id": "ol_93c4d5e6f7", "item_id": "i_2b3c4d5e6f", "brand": "Contitech", "article": "6PK1873", "oem": "", "price_kop": 210000, "qty": 1, "sum_kop": 210000, "vat": "vat22", "vat_name": "НДС 22%", "term": "in_stock", "term_name": "В наличии", "term_days": 0, "availability": "in_stock", "stock": 0, "comment": "", "photo_url": "https://disk.yandex.ru/i/Ab3dE6fG", "external_id": null, "status": "pending", "bought_qty": 0, "left_qty": 1, "counter_price_kop": null } ], "orders": [], "actions": [ "withdraw" ], "counter": null, "competition": { "proposals": 3, "sellers": 3, "limit": 5, "slots_left": 2, "my_rank": 1, "my_value_kop": 406000, "basis": "accept_plan" }, "change_seq": 184311 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/seller/exchange/proposals/o_6a7b8c9d0e -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/seller/exchange/proposals/{id}/withdraw": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "security": [ { "bearer": [] } ], "tags": [ "exchange-seller" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "sellerWithdrawProposal", "summary": "Снять КП", "x-idempotency": "recommended", "description": "Снять можно черновик и КП sent, по которому ничего не куплено: купленное — 409 INVALID_STATE, заменённое или закрытое — 409 PROPOSAL_NOT_ACTIVE. Уже снятое — 200 и Idempotent-Replayed: state. Юридические ворота не действуют.\n\nСнятие отправленного КП не обнуляет предел замен API (M.10.2): следующая отправка по этой заявке считается заменой — не раньше replace_min_sec после прошлой отправки и не больше replaces_per_request раз (409 PROPOSAL_REPLACE_LIMIT; в заявке can_propose: false, cannot_propose_reason: replace_limit, replace_available_at). Снятый черновик, который ни разу не отправлялся, заменой не считается.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "responses": { "200": { "description": "КП со статусом withdrawn", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerProposal" }, "example": { "proposal_id": "o_6a7b8c9d0e", "number": "ТТ-014-00132", "exchange_request_id": "r_8c1d2e3f4a", "status": "withdrawn", "test": false, "via": "api", "replaces_proposal_id": null, "created_at": "2026-09-22T07:45:02.000Z", "updated_at": "2026-09-22T07:45:02.000Z", "comment": "Отгрузка со склада СПб в день оплаты", "value_kop": 406000, "lines_sum_kop": 652900, "coverage": { "items_open": 2, "items_offered": 2, "items_full": 2 }, "lines": [ { "proposal_line_id": "ol_91a2b3c4d5", "item_id": "i_1a2b3c4d5e", "brand": "MANN", "article": "W 950/26", "oem": "51.05504-0108", "price_kop": 123450, "qty": 2, "sum_kop": 246900, "vat": "vat22", "vat_name": "НДС 22%", "term": "in_stock", "term_name": "В наличии", "term_days": 0, "availability": "in_stock", "stock": 12, "comment": "оригинальная упаковка", "photo_url": null, "external_id": "A-778", "status": "pending", "bought_qty": 0, "left_qty": 2, "counter_price_kop": null }, { "proposal_line_id": "ol_92b3c4d5e6", "item_id": "i_1a2b3c4d5e", "brand": "FILTRON", "article": "OP 592/7", "oem": "", "price_kop": 98000, "qty": 2, "sum_kop": 196000, "vat": "vat22", "vat_name": "НДС 22%", "term": "days_2_3", "term_name": "2-3 дня", "term_days": 2, "availability": "on_order", "stock": 0, "comment": "", "photo_url": null, "external_id": null, "status": "pending", "bought_qty": 0, "left_qty": 2, "counter_price_kop": null }, { "proposal_line_id": "ol_93c4d5e6f7", "item_id": "i_2b3c4d5e6f", "brand": "Contitech", "article": "6PK1873", "oem": "", "price_kop": 210000, "qty": 1, "sum_kop": 210000, "vat": "vat22", "vat_name": "НДС 22%", "term": "in_stock", "term_name": "В наличии", "term_days": 0, "availability": "in_stock", "stock": 0, "comment": "", "photo_url": "https://disk.yandex.ru/i/Ab3dE6fG", "external_id": null, "status": "pending", "bought_qty": 0, "left_qty": 1, "counter_price_kop": null } ], "orders": [], "actions": [], "counter": null, "competition": { "proposals": 3, "sellers": 3, "limit": 5, "slots_left": 2, "my_rank": 1, "my_value_kop": 406000, "basis": "accept_plan" }, "change_seq": 184311 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/seller/exchange/proposals/o_6a7b8c9d0e/withdraw -H \"Authorization: Bearer $K247_TOKEN\" -H \"Content-Type: application/json\" -d '{}'" } ] } }, "/buyer/search": { "get": { "security": [ { "bearer": [] } ], "tags": [ "buyer" ], "operationId": "buyerSearch", "summary": "Поиск предложений: бренды по артикулу или предложения", "x-rate-limit-class": "search", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "article", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 60 } }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 60 } }, { "name": "brand_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Один или несколько id через запятую" }, { "name": "analogs", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 1 } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "auto", "brands", "offers" ], "default": "auto" }, "description": "auto — артикул без бренда: список брендов (mode: brands), если брендов у артикула больше одного; при одном бренде сразу предложения (mode: offers). brands — список брендов при любом их числе. offers — сразу предложения. Второй шаг — ?article=&brand_id= пары из списка: предложения искомого товара (группа requested), затем аналоги (oem, analog), в том числе присланные поставщиками площадки" }, { "name": "similar", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "1 — в ответе mode: brands ещё похожие номера (similar): номера, которые начинаются с введённого (после нормализации), до 30 пар «бренд + номер». С mode=auto список приходит и при одном бренде, если похожие номера есть. Без параметра ответ прежний" }, { "name": "price_min_kop", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "price_max_kop", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "term_max", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 365 } }, { "name": "city_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "id через запятую" }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "seller", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Код продавца ТТ-xxx" }, { "name": "in_stock", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } }, { "name": "condition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new", "used" ] } }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "relevance", "price", "price_desc", "term", "updated" ], "default": "relevance" } }, { "$ref": "#/components/parameters/Limit100" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Бренды или предложения", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SearchBrands" }, { "$ref": "#/components/schemas/SearchOffers" } ], "discriminator": { "propertyName": "mode", "mapping": { "brands": "#/components/schemas/SearchBrands", "offers": "#/components/schemas/SearchOffers" } } }, "example": { "mode": "offers", "query": { "brand_id": 17, "article_norm": "01089", "analogs": true }, "total": 1, "total_exact": true, "groups": [ { "kind": "requested", "brand_id": 17, "brand": "FEBI BILSTEIN", "article": "01-089", "article_norm": "01089", "offers": [ { "offer_key": "eyJvIjoicF8zYzFmOWUyYTdiIiwicCI6MTIzNDUwfQ.m7Q2x9Lh0aV1c3kP", "name": "Термостат", "seller_code": "ТТ-014", "seller_rating": 4.1, "refusal_pct": 6.5, "city": "Санкт-Петербург", "region": "Санкт-Петербург", "country": "RU", "warehouse_code": "ТТ-014-1", "price_kop": 123450, "currency": "RUB", "qty": 10, "multiplicity": 1, "min_order": 1, "term_days_min": 1, "term_days_max": 3, "probability": 95, "condition": "new", "returnable": true, "vat": "НДС 22%", "availability": "in_stock", "stale": false, "price_age_hours": 3, "photo": null, "updated_at": "2026-09-15T08:00:00.000Z" } ] } ], "next_cursor": null, "has_more": false, "warnings": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "Лимит search на ключ и на компанию. Test-ключ: 0,2 лимита и limit ≤ 20. Без article/q — листинг глубиной до 500 предложений (warnings: LISTING_DEPTH_LIMIT). Склад — только город и обезличенный warehouse_code.", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s \"https://k-247.ru/api/v1/buyer/search?article=01-089&brand_id=17\" -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/buyer/quotes": { "post": { "security": [ { "bearer": [] } ], "tags": [ "buyer" ], "operationId": "buyerQuotes", "summary": "Перепроверка до 50 offer_key", "x-rate-limit-class": "search", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotesRequest" }, "example": { "items": [ { "offer_key": "eyJvIjoicF8zYzFmOWUyYTdiIiwicCI6MTIzNDUwfQ.m7Q2x9Lh0aV1c3kP", "qty": 2 } ] } } } }, "responses": { "200": { "description": "Актуальные условия", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotesResponse" }, "example": { "items": [ { "offer_key": "eyJvIjoicF8zYzFmOWUyYTdiIiwicCI6MTIzNDUwfQ.m7Q2x9Lh0aV1c3kPN", "requested_offer_key": "eyJvIjoicF8zYzFmOWUyYTdiIiwicCI6MTIzNDUwfQ.m7Q2x9Lh0aV1c3kP", "status": "ok", "price_kop": 123450, "qty_available": 10, "qty_requested": 2, "multiplicity": 1, "min_order": 1, "term_days_min": 1, "term_days_max": 3, "availability": "in_stock", "expires_at": "2026-09-15T09:42:00.000Z" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/buyer/quotes -H \"Authorization: Bearer $K247_TOKEN\" -H \"Content-Type: application/json\" -d '{\"items\":[{\"offer_key\":\"\",\"qty\":2}]}'" } ], "description": "Перепроверка до 50 offer_key прямо сейчас: цена, доступный остаток, срок. Свежий offer_key выдаётся для ok и price_changed. Кратность и минимальная партия отдаются для сведения: заказ они не блокируют (M.6 п.4)." } }, "/buyer/orders": { "post": { "security": [ { "bearer": [] } ], "tags": [ "buyer" ], "operationId": "buyerCreateOrder", "summary": "Заказ по offer_key (делится по продавцам)", "x-scope": "orders", "x-rate-limit-class": "bulk", "x-rate-limit-class-test": "default", "x-idempotency": "required", "description": "Тестовым ключом (песочница): в заказе — не больше 20 позиций; тестовых заказов компании — не больше 50 действующих (409 LIMIT_EXCEEDED) и 200 за сутки (429 RATE_LIMITED с Retry-After). Тестовые заказы удаляются через exchangeTestRetentionDays (7 дней) после создания.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerOrderRequest" }, "example": { "reference": "ТК-Север-4471", "items": [ { "offer_key": "eyJvIjoi…", "qty": 2 } ], "delivery": { "type": "основной", "address": "ул. Салова, 27", "express": false }, "payment": "счёт", "accept_terms": true, "price_policy": "strict" } } } }, "responses": { "201": { "description": "Заказы созданы", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerOrderCreated" }, "example": { "reference": "ТК-Север-4471", "orders": [ { "order_id": "ord_6f2b", "number": "2609-1191", "seller_code": "ТТ-014", "status": "awaiting_confirmation", "total_kop": 246900, "accounting_total_rub": 2469, "lines": [ { "line_id": "l_1a2b", "brand": "FEBI BILSTEIN", "article": "01-089", "qty": 2, "price_kop": 123450, "status": "awaiting_confirmation" } ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "Только организация (у автовладельца — 403 FORBIDDEN_ROLE); боевому ключу компании без принятых документов площадки — 403 LEGAL_NEEDS. Правила — как у корзины сайта; кратность и минимальная партия не проверяются. Test-ключ: заказ test = true на служебного продавца (реальный продавец его не видит), робот песочницы подтверждает строки, строку с qty = 13 отклоняет out_of_stock и через Δ отгружает подтверждённые. Лимит: боевой ключ — класс bulk, тестовый — класс default (x-rate-limit-class-test), чтобы тестовые заказы подряд не упирались в 429.\n\nИстёкший offer_key (старше quoteTtlMinutes) — 409 OFFER_KEY_EXPIRED: повторите поиск (GET /buyer/search), quotes истёкший ключ не продлевает.", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/buyer/orders -H \"Authorization: Bearer $K247_TOKEN\" -H \"Idempotency-Key: TK-4471\" -H \"Content-Type: application/json\" -d '{\"reference\":\"ТК-Север-4471\",\"items\":[{\"offer_key\":\"\",\"qty\":2}],\"payment\":\"invoice\",\"accept_terms\":true}'" } ] }, "get": { "security": [ { "bearer": [] } ], "tags": [ "buyer" ], "operationId": "buyerListOrders", "summary": "Заказы покупателя: по ids, reference или since", "x-scope": "orders | exchange", "parameters": [ { "name": "ids", "in": "query", "required": false, "schema": { "type": "string" }, "description": "До 50 id через запятую" }, { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "shop", "exchange" ] }, "description": "Источник заказа" }, { "$ref": "#/components/parameters/SinceSeq" }, { "$ref": "#/components/parameters/Since" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit100" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Страница", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BuyerOrder" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "example": { "items": [ { "order_id": "ord_6f2b3c4d5e", "number": "2609-1190", "status": "awaiting_confirmation", "status_name": "Ожидает подтверждения", "test": false, "created_at": "2026-09-15T09:05:00.000Z", "updated_at": "2026-09-15T09:05:00.000Z", "confirm_deadline_at": "2026-09-15T11:05:00.000Z", "auto_cancel_at": "2026-09-15T13:05:00.000Z", "source": "shop", "exchange": null, "requires_confirmation": true, "seller": { "code": "ТТ-014", "city": "Санкт-Петербург", "rating": 4.1 }, "delivery": { "type": "основной", "address": "ул. Салова, 27", "express": false }, "payment": "счёт", "comment": "", "currency": "RUB", "total_kop": 246900, "delivery_kop": 0, "accounting_total_rub": 2469, "reference": "ТК-Север-4471", "lines": [ { "line_id": "l_9a8b7c6d5e", "offer_id": "p_3c1f9e2a7b", "brand": "FEBI BILSTEIN", "article": "01-089", "oem": "", "name": "Термостат", "qty": 2, "confirmed_qty": null, "shipped_qty": 0, "price_kop": 123450, "sum_kop": 246900, "status": "awaiting_confirmation", "reject_reason_code": null, "term_days_min": 1, "term_days_max": 3, "term_days_confirmed": null, "warehouse": "СПб-1", "plate": "", "exchange": null } ], "documents": { "invoice": "", "upd": "", "ksf": "" }, "change_seq": 184230 } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "Заказы компании своего окружения: из магазина (source shop) и из КП биржи (source exchange, поле exchange). Ключ только с правом exchange видит лишь заказы из КП. Синхронизация — since_seq.", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s \"https://k-247.ru/api/v1/buyer/orders?since_seq=184000\" -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/buyer/orders/{id}": { "get": { "security": [ { "bearer": [] } ], "tags": [ "buyer" ], "operationId": "buyerGetOrder", "summary": "Заказ покупателя", "x-scope": "orders | exchange", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Заказ", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerOrder" }, "example": { "order_id": "ord_6f2b3c4d5e", "number": "2609-1190", "status": "awaiting_confirmation", "status_name": "Ожидает подтверждения", "test": false, "created_at": "2026-09-15T09:05:00.000Z", "updated_at": "2026-09-15T09:05:00.000Z", "confirm_deadline_at": "2026-09-15T11:05:00.000Z", "auto_cancel_at": "2026-09-15T13:05:00.000Z", "source": "shop", "exchange": null, "requires_confirmation": true, "seller": { "code": "ТТ-014", "city": "Санкт-Петербург", "rating": 4.1 }, "delivery": { "type": "основной", "address": "ул. Салова, 27", "express": false }, "payment": "счёт", "comment": "", "currency": "RUB", "total_kop": 246900, "delivery_kop": 0, "accounting_total_rub": 2469, "reference": "ТК-Север-4471", "lines": [ { "line_id": "l_9a8b7c6d5e", "offer_id": "p_3c1f9e2a7b", "brand": "FEBI BILSTEIN", "article": "01-089", "oem": "", "name": "Термостат", "qty": 2, "confirmed_qty": null, "shipped_qty": 0, "price_kop": 123450, "sum_kop": 246900, "status": "awaiting_confirmation", "reject_reason_code": null, "term_days_min": 1, "term_days_max": 3, "term_days_confirmed": null, "warehouse": "СПб-1", "plate": "", "exchange": null } ], "documents": { "invoice": "", "upd": "", "ksf": "" }, "change_seq": 184230 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/buyer/orders/ord_6f2b3c4d5e -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/webhooks": { "get": { "security": [ { "bearer": [] } ], "tags": [ "webhooks" ], "operationId": "listWebhooks", "summary": "Подписки окружения ключа", "x-scope": "offers | orders | exchange", "responses": { "200": { "description": "Подписки", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "items" ] }, "example": { "items": [ { "webhook_id": "wh_4b2a1c0d9e", "url": "https://erp.shop.ru/k247/hook", "events": [ "order.created", "order.line_cancelled", "import.held" ], "env": "live", "enabled": true, "failures": 0, "disabled_reason": null, "description": "1С УТ", "last_delivery": { "at": "2026-09-15T09:40:00.000Z", "status": "delivered", "code": 200 }, "created_at": "2026-09-15T09:30:00.000Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/webhooks -H \"Authorization: Bearer $K247_TOKEN\"" } ], "description": "Подписки компании в окружении ключа (test-ключ видит только тестовые, live — только боевые), без секрета. failures — неудачных доставок подряд, last_delivery — итог последней попытки." }, "post": { "security": [ { "bearer": [] } ], "tags": [ "webhooks" ], "operationId": "createWebhook", "summary": "Создать подписку (секрет показывается один раз)", "x-scope": "offers | orders | exchange", "x-idempotency": "recommended", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" }, "example": { "url": "https://erp.shop.ru/k247/hook", "events": [ "order.created", "order.line_cancelled", "import.held" ], "description": "1С УТ" } } } }, "responses": { "201": { "description": "Подписка создана", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" }, "example": { "webhook_id": "wh_4b2a1c0d9e", "url": "https://erp.shop.ru/k247/hook", "events": [ "order.created", "order.line_cancelled", "import.held" ], "env": "live", "enabled": true, "failures": 0, "disabled_reason": null, "description": "1С УТ", "last_delivery": null, "created_at": "2026-09-15T09:30:00.000Z", "secret": "whsec_Qm9hY2hlbGxvV2ViaG9va1NlY3JldDI0" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/webhooks -H \"Authorization: Bearer $K247_TOKEN\" -H \"Content-Type: application/json\" -H \"Idempotency-Key: hook-erp-1\" -d '{\"url\":\"https://erp.shop.ru/k247/hook\",\"events\":[\"order.created\",\"order.line_cancelled\",\"import.held\"],\"description\":\"1С УТ\"}'" }, { "lang": "javascript", "label": "Node.js", "source": "const r = await fetch('https://k-247.ru/api/v1/webhooks', {\n method: 'POST',\n headers: { Authorization: 'Bearer ' + process.env.K247_TOKEN, 'Content-Type': 'application/json', 'Idempotency-Key': 'hook-erp-1' },\n body: JSON.stringify({ url: 'https://erp.shop.ru/k247/hook', events: ['order.created', 'order.line_cancelled', 'import.held'], description: '1С УТ' })\n});\nconst hook = await r.json();\n// hook.secret показывается один раз — сохраните его в настройках приёмника\nconsole.log(r.status, hook.webhook_id);" } ], "description": "Подписка на события компании. Окружение подписки = окружение ключа: test-подписка получает события песочницы (тестовые заказы, проверочные загрузки), live — боевые. Проверки: адрес https (порты 80, 443, 8080, 8443, без логина в адресе; имя сервера не должно вести во внутреннюю сеть), события из WebhookEvent или [\"*\"], не больше webhooksMaxPerEnv (5) подписок на компанию и окружение — иначе 409 LIMIT_EXCEEDED. Секрет подписи whsec_… возвращается один раз: сохраните его, посмотреть снова нельзя (повтор с тем же Idempotency-Key возвращает тот же ответ). О новой подписке узнают сотрудники компании. Продавцу приходят order.* по его заказам, import.* и price.stale по его прайсам; покупателю — order.* по его заказам." } }, "/webhooks/{id}": { "delete": { "security": [ { "bearer": [] } ], "tags": [ "webhooks" ], "operationId": "deleteWebhook", "summary": "Удалить подписку", "x-scope": "offers | orders | exchange", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "204": { "description": "Удалено", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X DELETE https://k-247.ru/api/v1/webhooks/wh_4b2a1c0d9e -H \"Authorization: Bearer $K247_TOKEN\"" } ], "description": "Удалить подписку окружения ключа. Недоставленные события подписки больше не отправляются. Чужая подписка или подписка другого окружения — 404." } }, "/webhooks/{id}/test": { "post": { "security": [ { "bearer": [] } ], "tags": [ "webhooks" ], "operationId": "testWebhook", "summary": "Отправить событие ping", "x-scope": "offers | orders | exchange", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "202": { "description": "Поставлено в очередь", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "event_id" ], "properties": { "event_id": { "type": "string", "description": "id конверта и заголовок X-K247-Event-Id" } } }, "example": { "event_id": "evt_01J8Z6A1B2C3" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/webhooks/wh_4b2a1c0d9e/test -H \"Authorization: Bearer $K247_TOKEN\"" } ], "description": "Поставить в очередь проверочное событие ping (в data — {\"type\":\"ping\",\"webhook_id\":\"…\"}): оно подписано и доставляется как обычное событие, в том числе выключенной подписке. Итог доставки — в GET /webhooks (last_delivery) и в журнале кабинета. Не больше 10 проверочных событий в час на подписку (выключенную — 3), сверх — 429 RATE_LIMITED с Retry-After. Если прежний ping подписки ещё ждёт доставки, новый не создаётся: прежний отправляется сейчас, в ответе — его event_id." } }, "/sandbox/orders": { "post": { "security": [ { "bearer": [] } ], "tags": [ "sandbox" ], "operationId": "sandboxCreateOrder", "summary": "Тестовый заказ на собственный товар (только test-ключ продавца)", "x-scope": "orders", "x-rate-limit-class": "default", "x-idempotency": "required", "description": "В заказе — не больше 20 строк. Тестовых заказов компании — не больше 50 действующих (409 LIMIT_EXCEEDED): отгрузите или отклоните прежние; и не больше 200 за сутки (429 RATE_LIMITED с Retry-After). Тестовые заказы удаляются через exchangeTestRetentionDays (7 дней) после создания.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxOrderRequest" }, "example": { "lines": [ { "external_id": "A-779", "qty": 1 } ], "delivery": { "type": "основной", "address": "Тестовый адрес, 1" } } } } }, "responses": { "201": { "description": "Тестовый заказ", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerOrder" }, "example": { "order_id": "ord_5e1a2b3c4d", "number": "2609-1190", "status": "awaiting_confirmation", "status_name": "Ожидает подтверждения", "test": true, "created_at": "2026-09-15T09:05:00.000Z", "updated_at": "2026-09-15T09:05:00.000Z", "change_seq": 184230, "confirm_deadline_at": "2026-09-15T11:05:00.000Z", "auto_cancel_at": "2026-09-15T13:05:00.000Z", "buyer": { "code": "Покупатель", "city": "Санкт-Петербург" }, "delivery": { "type": "основной", "address": "ул. Салова, 27", "express": false }, "payment": "с баланса", "comment": "", "currency": "RUB", "total_kop": 246900, "delivery_kop": 0, "accounting_total_rub": 2469, "lines": [ { "line_id": "l_9a8b7c6d5e", "offer_id": "p_3c1f9e2a7b", "external_id": "A-778", "brand": "FEBI BILSTEIN", "article": "01-089", "name": "Термостат", "qty": 2, "confirmed_qty": null, "shipped_qty": 0, "price_kop": 123450, "sum_kop": 246900, "status": "awaiting_confirmation", "reject_reason_code": null, "term_days_min": 1, "term_days_max": 3, "term_days_confirmed": null, "warehouse": "СПб-1", "external_order_ref": null, "plate": "" } ], "documents": { "invoice": "", "upd": "", "ksf": "" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "Только test-ключ продавца (live → 403 FORBIDDEN_ENV). Заказ test=true от служебного покупателя c_sandbox, requires_confirmation; остатки, резервы, деньги и уведомления в общую ленту не затрагиваются. Заказ оформляется на собственную позицию продавца (без lines — на любую свою с остатком), поэтому нужна хотя бы одна опубликованная позиция: test-ключ позиций не создаёт (offers/batch и pricelists — dry_run), загрузите прайс в кабинете (файл, ссылка, почта) или боевым ключом. Позиций нет — 422 BUSINESS_RULE.", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/sandbox/orders -H \"Authorization: Bearer $K247_TOKEN\" -H \"Idempotency-Key: sbx-1\" -H \"Content-Type: application/json\" -d '{}'" } ] } }, "/sandbox/exchange/requests": { "post": { "security": [ { "bearer": [] } ], "tags": [ "sandbox" ], "operationId": "sandboxCreateExchangeRequest", "summary": "Тестовая заявка робота-покупателя для своей компании (только test-ключ продавца)", "x-scope": "exchange", "x-rate-limit-class": "default", "x-idempotency": "required", "description": "Live-ключ — 403 FORBIDDEN_ENV. Заявка test = true от служебного покупателя: биржа — по типу продавца, регион и город — продавца, машина MAN TGX 2016. Сценарий робот выполняет через sandboxAutoConfirmSec (30 с) после первого КП: accept — принять КП целиком (test-заказ из КП), accept_partial — купить первую позицию, reject — отклонять КП, close — снять заявку, expire — закрыть по сроку, compete — ответить КП робота ТЕСТ-000 на 10 % дешевле и купить у него. Действующих тестовых заявок — не больше 20 (409 LIMIT_EXCEEDED), за сутки — не больше 100 (429 RATE_LIMITED с Retry-After). Событие exchange.request.created уходит только на test-подписку этой компании.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxExchangeRequestInput" }, "example": { "scenario": "accept", "items": [ { "name": "Фильтр масляный", "qty": 2 }, { "name": "Ремень приводной", "qty": 1 } ], "deadline": "week" } } } }, "responses": { "201": { "description": "Тестовая заявка в формате GET /seller/exchange/requests/{id}", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerExchangeRequest" }, "example": { "exchange_request_id": "r_8c1d2e3f4a", "number": "ТЕСТ-З-2609-7", "status": "active", "exchange": "new", "test": true, "created_at": "2026-09-22T07:10:00.000Z", "updated_at": "2026-09-22T07:42:11.000Z", "revision": 0, "revised_at": null, "expires_at": "2026-09-22T20:59:59.000Z", "deadline": "week", "deadline_name": "неделя", "priority": "any", "priority_name": "все", "vehicle": { "vgroup": "truck", "market": "eu", "category": "Грузовые / Европа", "brand": "MAN", "model": "TGX", "year": "2016", "vin": "WMA06XZZ0FP000001" }, "buyer": { "ref": "П-7F3A9C", "city": "Санкт-Петербург" }, "city": "Санкт-Петербург", "region": "Санкт-Петербург", "delivery": "main", "delivery_name": "основной", "pickup": "delivery", "pickup_name": "доставка", "payment": "invoice", "payment_name": "счёт", "comment": "Тестовая заявка робота-покупателя песочницы", "items": [ { "item_id": "i_1a2b3c4d5e", "position": 1, "name": "Фильтр масляный", "qty": 2, "comment": "по VIN", "open": true }, { "item_id": "i_2b3c4d5e6f", "position": 2, "name": "Ремень приводной", "qty": 1, "comment": "", "open": true } ], "max_proposals": 0, "competition": { "proposals": 0, "sellers": 0, "limit": 0, "slots_left": null, "my_rank": 0, "my_value_kop": 0, "basis": "accept_plan" }, "my_proposals": [], "current_proposal_id": null, "can_propose": true, "cannot_propose_reason": null, "replace_available_at": null, "unread_messages": 0, "change_seq": 184300 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/sandbox/exchange/requests -H \"Authorization: Bearer $K247_TOKEN\" -H \"Content-Type: application/json\" -H \"Idempotency-Key: sbx-ex-1\" -d '{\"scenario\":\"accept\"}'" } ] } }, "/buyer/exchange/requests": { "post": { "security": [ { "bearer": [] } ], "tags": [ "exchange-buyer" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "buyerCreateExchangeRequest", "summary": "Создать заявку на бирже", "x-idempotency": "required", "description": "Только организация (у автовладельца — 403 FORBIDDEN_ROLE). Боевому ключу компании без принятых документов площадки — 403 LEGAL_NEEDS. Пределы: не больше exchangeApiRequestsPerHour заявок в час и exchangeApiActiveMax действующих заявок из программы на компанию; тестовым ключом — пятая часть часового предела, не больше 20 действующих и 100 за сутки (429 RATE_LIMITED).", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerExchangeRequestInput" }, "example": { "reference": "ТК-Север-4471", "exchange": "new", "vehicle": { "vgroup": "truck", "market": "eu", "brand": "MAN", "model": "TGX", "year": "2016", "vin": "WMA06XZZ0FP000001", "plate": "А123ВС78" }, "items": [ { "name": "Фильтр масляный", "qty": 2, "comment": "по VIN" }, { "name": "Ремень приводной", "qty": 1 } ], "deadline": "today", "priority": "fast", "max_proposals": 5, "delivery": "main", "pickup": "delivery", "pickup_address": "ул. Салова, 27", "payment": "invoice", "city": "Санкт-Петербург", "region": "Санкт-Петербург", "comment": "Машина на линии" } } } }, "responses": { "201": { "description": "Заявка создана", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerExchangeRequest" }, "example": { "exchange_request_id": "r_9d2e3f4a5b", "number": "2609-412", "status": "active", "exchange": "new", "test": false, "via": "api", "reference": "ТК-Север-4471", "created_at": "2026-09-22T07:10:00.000Z", "updated_at": "2026-09-22T07:10:00.000Z", "revision": 0, "revised_at": null, "expires_at": "2026-09-22T20:59:59.000Z", "deadline": "today", "deadline_name": "сегодня", "priority": "fast", "priority_name": "быстрее", "vehicle": { "vgroup": "truck", "market": "eu", "category": "Грузовые / Европа", "brand": "MAN", "model": "TGX", "year": "2016", "vin": "WMA06XZZ0FP000001", "plate": "А123ВС78" }, "city": "Санкт-Петербург", "region": "Санкт-Петербург", "delivery": "main", "delivery_name": "основной", "pickup": "delivery", "pickup_name": "доставка", "pickup_address": "ул. Салова, 27", "payment": "invoice", "payment_name": "счёт", "comment": "Машина на линии", "max_proposals": 5, "items": [ { "item_id": "i_3c4d5e6f7a", "position": 1, "name": "Фильтр масляный", "qty": 2, "comment": "по VIN", "bought_qty": 0, "need_qty": 2, "open": true }, { "item_id": "i_4d5e6f7a8b", "position": 2, "name": "Ремень приводной", "qty": 1, "comment": "", "bought_qty": 0, "need_qty": 1, "open": true } ], "proposals_summary": { "active": 0, "sellers": 0, "total": 0, "best_value_kop": null }, "unread_messages": 0, "change_seq": 184290 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/buyer/exchange/requests -H \"Authorization: Bearer $K247_TOKEN\" -H \"Idempotency-Key: REQ-4471\" -H \"Content-Type: application/json\" -d '{\"reference\":\"ТК-Север-4471\",\"vehicle\":{\"vgroup\":\"truck\",\"market\":\"eu\",\"brand\":\"MAN\",\"model\":\"TGX\"},\"items\":[{\"name\":\"Фильтр масляный\",\"qty\":2},{\"name\":\"Ремень приводной\",\"qty\":1}],\"deadline\":\"week\",\"payment\":\"invoice\"}'" } ] }, "get": { "security": [ { "bearer": [] } ], "tags": [ "exchange-buyer" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "buyerListExchangeRequests", "summary": "Заявки компании: status, reference, since_seq", "description": "Заявки компании своего окружения, в том числе созданные сотрудниками в кабинете. Номер изменения заявки растёт и при новом КП — один опрос показывает, где появились КП.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Список через запятую: active, done, closed, expired или all" }, { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Свой номер заявки покупателя" }, { "$ref": "#/components/parameters/SinceSeq" }, { "$ref": "#/components/parameters/Since" }, { "$ref": "#/components/parameters/Limit100" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Страница", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerExchangeRequestList" }, "example": { "items": [ { "exchange_request_id": "r_9d2e3f4a5b", "number": "2609-412", "status": "active", "exchange": "new", "test": false, "via": "api", "reference": "ТК-Север-4471", "created_at": "2026-09-22T07:10:00.000Z", "updated_at": "2026-09-22T07:10:00.000Z", "revision": 0, "revised_at": null, "expires_at": "2026-09-22T20:59:59.000Z", "deadline": "today", "deadline_name": "сегодня", "priority": "fast", "priority_name": "быстрее", "vehicle": { "vgroup": "truck", "market": "eu", "category": "Грузовые / Европа", "brand": "MAN", "model": "TGX", "year": "2016", "vin": "WMA06XZZ0FP000001", "plate": "А123ВС78" }, "city": "Санкт-Петербург", "region": "Санкт-Петербург", "delivery": "main", "delivery_name": "основной", "pickup": "delivery", "pickup_name": "доставка", "pickup_address": "ул. Салова, 27", "payment": "invoice", "payment_name": "счёт", "comment": "Машина на линии", "max_proposals": 5, "items": [ { "item_id": "i_3c4d5e6f7a", "position": 1, "name": "Фильтр масляный", "qty": 2, "comment": "по VIN", "bought_qty": 0, "need_qty": 2, "open": true }, { "item_id": "i_4d5e6f7a8b", "position": 2, "name": "Ремень приводной", "qty": 1, "comment": "", "bought_qty": 0, "need_qty": 1, "open": true } ], "proposals_summary": { "active": 0, "sellers": 0, "total": 0, "best_value_kop": null }, "unread_messages": 0, "change_seq": 184290 } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s \"https://k-247.ru/api/v1/buyer/exchange/requests?status=active&limit=50\" -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/buyer/exchange/requests/{id}": { "get": { "security": [ { "bearer": [] } ], "tags": [ "exchange-buyer" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "buyerGetExchangeRequest", "summary": "Заявка компании", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Заявка", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerExchangeRequest" }, "example": { "exchange_request_id": "r_9d2e3f4a5b", "number": "2609-412", "status": "active", "exchange": "new", "test": false, "via": "api", "reference": "ТК-Север-4471", "created_at": "2026-09-22T07:10:00.000Z", "updated_at": "2026-09-22T07:10:00.000Z", "revision": 0, "revised_at": null, "expires_at": "2026-09-22T20:59:59.000Z", "deadline": "today", "deadline_name": "сегодня", "priority": "fast", "priority_name": "быстрее", "vehicle": { "vgroup": "truck", "market": "eu", "category": "Грузовые / Европа", "brand": "MAN", "model": "TGX", "year": "2016", "vin": "WMA06XZZ0FP000001", "plate": "А123ВС78" }, "city": "Санкт-Петербург", "region": "Санкт-Петербург", "delivery": "main", "delivery_name": "основной", "pickup": "delivery", "pickup_name": "доставка", "pickup_address": "ул. Салова, 27", "payment": "invoice", "payment_name": "счёт", "comment": "Машина на линии", "max_proposals": 5, "items": [ { "item_id": "i_3c4d5e6f7a", "position": 1, "name": "Фильтр масляный", "qty": 2, "comment": "по VIN", "bought_qty": 0, "need_qty": 2, "open": true }, { "item_id": "i_4d5e6f7a8b", "position": 2, "name": "Ремень приводной", "qty": 1, "comment": "", "bought_qty": 0, "need_qty": 1, "open": true } ], "proposals_summary": { "active": 0, "sellers": 0, "total": 0, "best_value_kop": null }, "unread_messages": 0, "change_seq": 184290 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/buyer/exchange/requests/r_9d2e3f4a5b -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/buyer/exchange/requests/{id}/update": { "post": { "security": [ { "bearer": [] } ], "tags": [ "exchange-buyer" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "buyerUpdateExchangeRequest", "summary": "Изменить заявку", "x-idempotency": "recommended", "description": "Юридические ворота не действуют: правка — не новое обязательство. Купленную позицию нельзя удалить, переименовать или уменьшить ниже купленного (409 INVALID_STATE). Переименование или удаление позиции закрывает строки КП по ней. Биржу (exchange) можно расширить всегда; сузить — нельзя, пока продавцы, которые потеряют доступ к заявке, держат действующие КП (409 INVALID_STATE, details[0].field = exchange).", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerExchangeRequestUpdate" }, "example": { "deadline": "week", "max_proposals": 5, "comment": "Машина на линии, нужен счёт на оплату" } } } }, "responses": { "200": { "description": "Заявка после правки", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerExchangeRequest" }, "example": { "exchange_request_id": "r_9d2e3f4a5b", "number": "2609-412", "status": "active", "exchange": "new", "test": false, "via": "api", "reference": "ТК-Север-4471", "created_at": "2026-09-22T07:10:00.000Z", "updated_at": "2026-09-22T07:10:00.000Z", "revision": 0, "revised_at": null, "expires_at": "2026-09-22T20:59:59.000Z", "deadline": "today", "deadline_name": "сегодня", "priority": "fast", "priority_name": "быстрее", "vehicle": { "vgroup": "truck", "market": "eu", "category": "Грузовые / Европа", "brand": "MAN", "model": "TGX", "year": "2016", "vin": "WMA06XZZ0FP000001", "plate": "А123ВС78" }, "city": "Санкт-Петербург", "region": "Санкт-Петербург", "delivery": "main", "delivery_name": "основной", "pickup": "delivery", "pickup_name": "доставка", "pickup_address": "ул. Салова, 27", "payment": "invoice", "payment_name": "счёт", "comment": "Машина на линии", "max_proposals": 5, "items": [ { "item_id": "i_3c4d5e6f7a", "position": 1, "name": "Фильтр масляный", "qty": 2, "comment": "по VIN", "bought_qty": 0, "need_qty": 2, "open": true }, { "item_id": "i_4d5e6f7a8b", "position": 2, "name": "Ремень приводной", "qty": 1, "comment": "", "bought_qty": 0, "need_qty": 1, "open": true } ], "proposals_summary": { "active": 0, "sellers": 0, "total": 0, "best_value_kop": null }, "unread_messages": 0, "change_seq": 184290 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/buyer/exchange/requests/r_9d2e3f4a5b/update -H \"Authorization: Bearer $K247_TOKEN\" -H \"Content-Type: application/json\" -d '{\"deadline\":\"week\",\"max_proposals\":5}'" } ] } }, "/buyer/exchange/requests/{id}/close": { "post": { "security": [ { "bearer": [] } ], "tags": [ "exchange-buyer" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "buyerCloseExchangeRequest", "summary": "Снять заявку", "x-idempotency": "recommended", "description": "Заявка → closed, её КП sent и draft → closed, строки корзин по заявке уходят. Уже снятая заявка — 200 и Idempotent-Replayed: state; выкупленную или истёкшую закрыть нельзя (409 REQUEST_CLOSED).", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "responses": { "200": { "description": "Заявка снята", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerExchangeRequest" }, "example": { "exchange_request_id": "r_9d2e3f4a5b", "number": "2609-412", "status": "closed", "exchange": "new", "test": false, "via": "api", "reference": "ТК-Север-4471", "created_at": "2026-09-22T07:10:00.000Z", "updated_at": "2026-09-22T07:10:00.000Z", "revision": 0, "revised_at": null, "expires_at": "2026-09-22T20:59:59.000Z", "deadline": "today", "deadline_name": "сегодня", "priority": "fast", "priority_name": "быстрее", "vehicle": { "vgroup": "truck", "market": "eu", "category": "Грузовые / Европа", "brand": "MAN", "model": "TGX", "year": "2016", "vin": "WMA06XZZ0FP000001", "plate": "А123ВС78" }, "city": "Санкт-Петербург", "region": "Санкт-Петербург", "delivery": "main", "delivery_name": "основной", "pickup": "delivery", "pickup_name": "доставка", "pickup_address": "ул. Салова, 27", "payment": "invoice", "payment_name": "счёт", "comment": "Машина на линии", "max_proposals": 5, "items": [ { "item_id": "i_3c4d5e6f7a", "position": 1, "name": "Фильтр масляный", "qty": 2, "comment": "по VIN", "bought_qty": 0, "need_qty": 2, "open": true }, { "item_id": "i_4d5e6f7a8b", "position": 2, "name": "Ремень приводной", "qty": 1, "comment": "", "bought_qty": 0, "need_qty": 1, "open": true } ], "proposals_summary": { "active": 0, "sellers": 0, "total": 0, "best_value_kop": null }, "unread_messages": 0, "change_seq": 184290 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/buyer/exchange/requests/r_9d2e3f4a5b/close -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/buyer/exchange/proposals": { "get": { "security": [ { "bearer": [] } ], "tags": [ "exchange-buyer" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "buyerListProposals", "summary": "КП по заявкам компании", "description": "Черновики продавцов сюда не попадают. Без status и since_seq — действующие КП (sent, partial, accepted); с since_seq — все статусы. sort=value — по стоимости КП, только вместе с exchange_request_id и без курсора.", "parameters": [ { "name": "exchange_request_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Список через запятую или all" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "value" ] }, "description": "value — все КП заявки по стоимости (value_kop) по возрастанию, в ответе первые limit; курсора нет, has_more: true — КП больше limit. Только с exchange_request_id, без since_seq, since и cursor" }, { "$ref": "#/components/parameters/SinceSeq" }, { "$ref": "#/components/parameters/Since" }, { "$ref": "#/components/parameters/Limit100" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Страница", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerProposalList" }, "example": { "items": [ { "proposal_id": "o_7b8c9d0e1f", "number": "ТТ-014-00132", "exchange_request_id": "r_9d2e3f4a5b", "status": "sent", "test": false, "replaces_proposal_id": null, "seller": { "code": "ТТ-014", "city": "Санкт-Петербург", "region": "Санкт-Петербург", "rating": 4.8, "refusal_pct": null }, "created_at": "2026-09-22T07:45:02.000Z", "updated_at": "2026-09-22T07:45:02.000Z", "comment": "Отгрузка со склада СПб в день оплаты", "value_kop": 406000, "lines_sum_kop": 652900, "coverage": { "items_open": 2, "items_offered": 2, "items_full": 2 }, "lines": [ { "proposal_line_id": "ol_a1b2c3d4e5", "item_id": "i_3c4d5e6f7a", "brand": "MANN", "article": "", "oem": "", "price_kop": 123450, "qty": 2, "sum_kop": 246900, "vat": "vat22", "vat_name": "НДС 22%", "term": "in_stock", "term_name": "В наличии", "term_days": 0, "availability": "in_stock", "stock": 12, "comment": "оригинальная упаковка", "photo_url": null, "status": "pending", "bought_qty": 0, "left_qty": 2, "counter_price_kop": null } ], "orders": [], "actions": [ "accept", "reject" ], "counter": null, "change_seq": 184311 } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s \"https://k-247.ru/api/v1/buyer/exchange/proposals?exchange_request_id=r_9d2e3f4a5b&sort=value\" -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/buyer/exchange/proposals/{id}": { "get": { "security": [ { "bearer": [] } ], "tags": [ "exchange-buyer" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "buyerGetProposal", "summary": "КП по заявке компании", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "КП", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerProposal" }, "example": { "proposal_id": "o_7b8c9d0e1f", "number": "ТТ-014-00132", "exchange_request_id": "r_9d2e3f4a5b", "status": "sent", "test": false, "replaces_proposal_id": null, "seller": { "code": "ТТ-014", "city": "Санкт-Петербург", "region": "Санкт-Петербург", "rating": 4.8, "refusal_pct": null }, "created_at": "2026-09-22T07:45:02.000Z", "updated_at": "2026-09-22T07:45:02.000Z", "comment": "Отгрузка со склада СПб в день оплаты", "value_kop": 406000, "lines_sum_kop": 652900, "coverage": { "items_open": 2, "items_offered": 2, "items_full": 2 }, "lines": [ { "proposal_line_id": "ol_a1b2c3d4e5", "item_id": "i_3c4d5e6f7a", "brand": "MANN", "article": "", "oem": "", "price_kop": 123450, "qty": 2, "sum_kop": 246900, "vat": "vat22", "vat_name": "НДС 22%", "term": "in_stock", "term_name": "В наличии", "term_days": 0, "availability": "in_stock", "stock": 12, "comment": "оригинальная упаковка", "photo_url": null, "status": "pending", "bought_qty": 0, "left_qty": 2, "counter_price_kop": null } ], "orders": [], "actions": [ "accept", "reject" ], "counter": null, "change_seq": 184311 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s https://k-247.ru/api/v1/buyer/exchange/proposals/o_7b8c9d0e1f -H \"Authorization: Bearer $K247_TOKEN\"" } ] } }, "/buyer/exchange/proposals/{id}/accept": { "post": { "security": [ { "bearer": [] } ], "tags": [ "exchange-buyer" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "buyerAcceptProposal", "summary": "Принять КП целиком или по строкам", "x-idempotency": "required", "description": "Оформление идёт тем же путём, что корзина сайта: одно «Принять» — один заказ на КП. Без lines берётся план «Принять» (по одному самому дешёвому варианту на позицию в пределах потребности). accept_terms обязателен и в песочнице. Адрес доставки заказа — delivery.address, без него — адрес получения заявки (pickup_address), при самовывозе — пункт самовывоза площадки «самовывоз, <адрес площадки>» (если адрес площадки не указан — адрес компании). Повтор с тем же Idempotency-Key отдаёт те же заказы.", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptProposalInput" }, "example": { "lines": [ { "proposal_line_id": "ol_a1b2c3d4e5", "qty": 2 } ], "payment": "invoice", "delivery": { "type": "main", "address": "ул. Салова, 27" }, "plate": "А123ВС78", "reference": "ТК-Север-4471", "accept_terms": true } } } }, "responses": { "201": { "description": "Заказ оформлен", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptProposalResult" }, "example": { "exchange_request_id": "r_9d2e3f4a5b", "proposal_id": "o_7b8c9d0e1f", "proposal_status": "partial", "request_status": "active", "orders": [ { "order_id": "ord_5e1a2b3c4d", "number": "2609-1195", "source": "exchange", "seller_code": "ТТ-014", "status": "awaiting_payment", "total_kop": 246900, "accounting_total_rub": 2469, "lines": [ { "line_id": "l_7c8d9e0f1a", "proposal_line_id": "ol_a1b2c3d4e5", "item_id": "i_3c4d5e6f7a", "brand": "MANN", "article": "W 950/26", "oem": "51.05504-0108", "qty": 2, "price_kop": 123450, "status": null } ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/buyer/exchange/proposals/o_7b8c9d0e1f/accept -H \"Authorization: Bearer $K247_TOKEN\" -H \"Idempotency-Key: ACC-4471\" -H \"Content-Type: application/json\" -d '{\"lines\":[{\"proposal_line_id\":\"ol_a1b2c3d4e5\"}],\"accept_terms\":true}'" } ] } }, "/buyer/exchange/proposals/{id}/reject": { "post": { "security": [ { "bearer": [] } ], "tags": [ "exchange-buyer" ], "x-scope": "exchange", "x-rate-limit-class": "default", "operationId": "buyerRejectProposal", "summary": "Отклонить КП", "x-idempotency": "recommended", "description": "Строки pending → rejected, продавец получает уведомление и событие exchange.proposal.rejected. Повтор, когда отклонять уже нечего, — 200 и Idempotent-Replayed: state, без второго уведомления. Тело пустое: причины и встречной цены в v1 нет.", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "responses": { "200": { "description": "КП отклонено", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Client-Request-Id": { "$ref": "#/components/headers/X-Client-Request-Id" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerProposal" }, "example": { "proposal_id": "o_8c9d0e1f2a", "number": "ТТ-014-00132", "exchange_request_id": "r_9d2e3f4a5b", "status": "rejected", "test": false, "replaces_proposal_id": null, "seller": { "code": "ТТ-014", "city": "Санкт-Петербург", "region": "Санкт-Петербург", "rating": 4.8, "refusal_pct": null }, "created_at": "2026-09-22T07:45:02.000Z", "updated_at": "2026-09-22T07:45:02.000Z", "comment": "Отгрузка со склада СПб в день оплаты", "value_kop": 406000, "lines_sum_kop": 652900, "coverage": { "items_open": 2, "items_offered": 2, "items_full": 2 }, "lines": [ { "proposal_line_id": "ol_a1b2c3d4e5", "item_id": "i_3c4d5e6f7a", "brand": "MANN", "article": "", "oem": "", "price_kop": 123450, "qty": 2, "sum_kop": 246900, "vat": "vat22", "vat_name": "НДС 22%", "term": "in_stock", "term_name": "В наличии", "term_days": 0, "availability": "in_stock", "stock": 12, "comment": "оригинальная упаковка", "photo_url": null, "status": "pending", "bought_qty": 0, "left_qty": 2, "counter_price_kop": null } ], "orders": [], "actions": [], "counter": null, "change_seq": 184311 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST https://k-247.ru/api/v1/buyer/exchange/proposals/o_8c9d0e1f2a/reject -H \"Authorization: Bearer $K247_TOKEN\"" } ] } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "k247_{test|live}_{id8}_{secret43}", "description": "Ключ выпускается в кабинете «API и интеграции». Live — только проверенной компании." } }, "headers": { "X-Request-Id": { "description": "Идентификатор запроса для поддержки", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Пополнение ведра класса, запросов в минуту", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Осталось токенов", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Секунд до полного ведра", "schema": { "type": "integer" } }, "Retry-After": { "description": "Секунд до повтора", "schema": { "type": "integer" } }, "Idempotent-Replayed": { "description": "`true` — ответ из сохранённого по Idempotency-Key; `state` — операция уже была выполнена с теми же параметрами (идемпотентность по состоянию)", "schema": { "type": "string", "enum": [ "true", "state" ] } }, "X-Client-Request-Id": { "description": "Эхо входящего X-Request-Id клиента (≤ 64 символа), в журнал не пишется", "schema": { "type": "string" } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_\\-:.]+$" }, "description": "Повтор с тем же телом возвращает сохранённый ответ (заголовок Idempotent-Replayed: true), с другим телом — 409\n\nКлюч хранится idempotencyTtlHours (24 ч). Позже тот же ключ — новый запрос: создаётся новая заявка, КП или заказ, прежний объект не возвращается. Ключ, которым уже выполнена другая операция в пределах срока, — 409 IDEMPOTENCY_CONFLICT." }, "IdempotencyKeyOptional": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_\\-:.]+$" } }, "PathId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, "Since": { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Объекты с updated_at строго больше (для людей и отладки; для синхронизации используйте since_seq — время ставится до коммита и не гарантирует полноты)" }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Непрозрачный курсор из next_cursor" }, "Limit100": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "Limit200": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "SinceSeq": { "name": "since_seq", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Объекты с change_seq строго больше; сортировка change_seq ASC. Опрос без потерь: сохранить change_seq последнего элемента." } }, "responses": { "BadRequest": { "description": "Неверный запрос: VALIDATION_FAILED, BAD_REQUEST, IDEMPOTENCY_KEY_REQUIRED\n\nBAD_REQUEST — ещё и тело не в кодировке UTF-8.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "UNAUTHORIZED, KEY_REVOKED, KEY_OWNER_INACTIVE", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "FORBIDDEN_SCOPE, FORBIDDEN_ROLE, FORBIDDEN_ENV, COMPANY_NOT_VERIFIED, IP_NOT_ALLOWED, LEGAL_NEEDS", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "NOT_FOUND", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS, INVALID_STATE, IMPORT_SUPERSEDED, OFFER_CHANGED, OFFER_KEY_EXPIRED, LIMIT_EXCEEDED, REQUEST_CLOSED, PROPOSAL_NOT_ACTIVE, PROPOSAL_LIMIT, PROPOSAL_REPLACE_LIMIT, ALREADY_BOUGHT, NEED_EXCEEDED, EXCHANGE_ORDER", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PayloadTooLarge": { "description": "PAYLOAD_TOO_LARGE", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UnsupportedMediaType": { "description": "UNSUPPORTED_MEDIA_TYPE", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unprocessable": { "description": "OUT_OF_STOCK, INSUFFICIENT_FUNDS, OWN_OFFER, BUSINESS_RULE, CONTACTS_FORBIDDEN", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "RATE_LIMITED, IMPORT_QUEUE_FULL", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Internal": { "description": "INTERNAL", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "UNAVAILABLE — сервер останавливается или база занята (ожидание блокировки дольше busy_timeout главного потока, 100 мс); повторите через Retry-After", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_FAILED", "IDEMPOTENCY_KEY_REQUIRED", "UNAUTHORIZED", "KEY_REVOKED", "FORBIDDEN_SCOPE", "FORBIDDEN_ROLE", "FORBIDDEN_ENV", "COMPANY_NOT_VERIFIED", "IP_NOT_ALLOWED", "NOT_FOUND", "METHOD_NOT_ALLOWED", "IDEMPOTENCY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "INVALID_STATE", "AMBIGUOUS_OFFER", "IMPORT_SUPERSEDED", "OFFER_CHANGED", "OFFER_KEY_EXPIRED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "OUT_OF_STOCK", "INSUFFICIENT_FUNDS", "OWN_OFFER", "BUSINESS_RULE", "RATE_LIMITED", "IMPORT_QUEUE_FULL", "INTERNAL", "UNAVAILABLE", "LIMIT_EXCEEDED", "KEY_OWNER_INACTIVE", "LEGAL_NEEDS", "REQUEST_CLOSED", "PROPOSAL_NOT_ACTIVE", "PROPOSAL_LIMIT", "PROPOSAL_REPLACE_LIMIT", "ALREADY_BOUGHT", "NEED_EXCEEDED", "EXCHANGE_ORDER", "CONTACTS_FORBIDDEN" ], "x-extensible-enum": true }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer", "nullable": true, "description": "Номер позиции или строки с 0; у полей заявки, КП и заказа целиком — null (M.3.8)" }, "index": { "type": "integer" }, "line_id": { "type": "string" }, "field": { "type": "string", "nullable": true, "description": "Поле входа; null — ошибка строки целиком" }, "code": { "type": "string" }, "message": { "type": "string" }, "kind": { "type": "string", "nullable": true, "description": "У CONTACTS_FOUND — вид найденного: phone, email, link, login, contact; в текстах КП ещё requisites (ИНН, ОГРН, КПП, БИК, счёт, номер карты), company (форма собственности с названием, название или адрес своей компании и складов), person (фамилия своего сотрудника), bypass (просьба рассчитаться мимо площадки: «платите напрямую продавцу», «минуя площадку», «переведите на карту»)" } }, "additionalProperties": true } } } } }, "example": { "error": { "code": "VALIDATION_FAILED", "message": "В 2 строках есть ошибки", "request_id": "req_01J8Z5Q0M2AB", "details": [ { "row": 3, "field": "price_kop", "code": "PRICE_INVALID", "message": "Цена — целое число копеек больше 0" } ] } } }, "Ping": { "type": "object", "required": [ "ok", "env", "company", "key" ], "properties": { "ok": { "type": "boolean" }, "env": { "type": "string", "enum": [ "test", "live" ] }, "company": { "type": "object", "properties": { "seller_code": { "type": "string", "nullable": true }, "type": { "type": "string" }, "verified": { "type": "boolean" }, "city": { "type": "string" }, "confirm_orders": { "type": "boolean" } } }, "key": { "type": "object", "properties": { "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "offers", "orders", "finance", "exchange" ], "x-extensible-enum": true } }, "created_at": { "type": "string", "format": "date-time" }, "exchange_region": { "type": "string", "enum": [ "own", "all" ], "description": "Регион заявок биржи ключа: own — свой регион (как в кабинете), all — вся Россия" } } }, "rate_limit": { "type": "object", "additionalProperties": { "type": "object", "properties": { "limit": { "type": "integer" }, "remaining": { "type": "integer" } } } }, "server_time": { "type": "string", "format": "date-time" }, "api_version": { "type": "string" }, "capabilities": { "type": "object", "properties": { "exchange": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Биржа через API включена площадкой; false — методы биржи отвечают 503 UNAVAILABLE, seller и buyer — false" }, "seller": { "type": "boolean", "description": "Ключ работает продавцом биржи (/seller/exchange/*)" }, "buyer": { "type": "boolean", "description": "Ключ работает покупателем-организацией биржи" }, "orders": { "type": "string", "nullable": true, "enum": [ "all", "exchange_only", null ], "description": "Какие заказы видит ключ: all — право orders, exchange_only — только заказы из КП" }, "counter_offer": { "type": "boolean", "description": "Встречная цена (зарезервировано, сейчас false)" } } } } }, "legal_needs": { "type": "array", "description": "Документы площадки, без которых методы, создающие обязательства, отвечают 403 LEGAL_NEEDS; пусто — всё принято", "items": { "type": "object", "properties": { "doc": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "who": { "type": "string", "enum": [ "company_admin" ] } } } } } }, "Field": { "type": "object", "required": [ "key", "required", "type" ], "properties": { "key": { "type": "string" }, "required": { "type": "boolean" }, "type": { "type": "string" }, "max_length": { "type": "integer" }, "min": { "type": "number" }, "max": { "type": "number" }, "headers": { "type": "array", "items": { "type": "string" } }, "file_key": { "type": "string" }, "file_type": { "type": "string" }, "description": { "type": "string" } } }, "FieldsDictionary": { "type": "object", "properties": { "version": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } }, "file": { "type": "object", "properties": { "formats": { "type": "array", "items": { "type": "string" } }, "encodings": { "type": "array", "items": { "type": "string" } }, "delimiters": { "type": "array", "items": { "type": "string" } }, "max_file_mb": { "type": "integer" }, "max_rows": { "type": "integer" }, "docpart_five_columns": { "type": "array", "items": { "type": "string" } } } } } }, "Brand": { "type": "object", "required": [ "brand_id", "name" ], "properties": { "brand_id": { "type": "integer" }, "name": { "type": "string" }, "group": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "oem", "aftermarket" ] }, "aliases": { "type": "array", "items": { "type": "string" } } } }, "CodeName": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "name": { "type": "string" } } }, "StatusesDictionary": { "type": "object", "properties": { "order_statuses": { "type": "array", "items": { "$ref": "#/components/schemas/CodeName" } }, "line_statuses": { "type": "array", "items": { "$ref": "#/components/schemas/CodeName" } }, "reject_reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "counts_as_refusal": { "type": "boolean" } } } }, "import_statuses": { "type": "array", "items": { "type": "string" } }, "webhook_events": { "type": "array", "items": { "type": "string" } } } }, "ImportAccepted": { "type": "object", "required": [ "import_id", "status" ], "properties": { "import_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued" ] }, "env": { "type": "string", "enum": [ "test", "live" ] }, "mode": { "type": "string", "enum": [ "replace", "upsert" ] }, "source_id": { "type": "string" }, "status_url": { "type": "string" } } }, "ImportCounters": { "type": "object", "properties": { "added": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" }, "adopted": { "type": "integer" }, "zeroed": { "type": "integer" }, "skipped": { "type": "integer" }, "unknown_brands": { "type": "integer" }, "skipped_newer": { "type": "integer", "description": "approve held: строки пропущены, т.к. позиция изменена другим источником после разбора" }, "warranty_ignored": { "type": "integer", "description": "Строки, принятые без срока гарантии: значение колонки «Гарантия» в файле не разобрано (предупреждение WARRANTY_IGNORED). В errors отчёта — первые 200 таких строк" } } }, "HeldReason": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VANISHED", "PRICE_JUMP", "UNKNOWN_BRANDS", "EMAIL_TRIAL", "EMAIL_SENDER_UNVERIFIED" ] }, "value": { "type": "number", "nullable": true, "description": "Показатель причины; у EMAIL_SENDER_UNVERIFIED — null (итог проверки отправителя — в message)" }, "limit": { "type": "number", "nullable": true, "description": "Порог причины; у EMAIL_SENDER_UNVERIFIED — null" }, "message": { "type": "string" } } }, "ImportSummary": { "type": "object", "required": [ "import_id", "status" ], "properties": { "import_id": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_mapping", "queued", "running", "held", "publishing", "published", "failed", "rejected" ] }, "phase": { "type": "string", "nullable": true }, "env": { "type": "string" }, "channel": { "type": "string", "enum": [ "cabinet", "api", "url", "email", "manager" ] }, "mode": { "type": "string" }, "source_id": { "type": "string" }, "filename": { "type": "string", "nullable": true }, "rows_total": { "type": "integer" }, "counters": { "$ref": "#/components/schemas/ImportCounters" }, "held_reason": { "type": "array", "items": { "$ref": "#/components/schemas/HeldReason" } }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ImportReport": { "allOf": [ { "$ref": "#/components/schemas/ImportSummary" }, { "type": "object", "properties": { "format": { "type": "string", "nullable": true }, "encoding": { "type": "string", "nullable": true }, "delimiter": { "type": "string", "nullable": true }, "rows_valid": { "type": "integer" }, "progress": { "type": "integer" }, "checks": { "type": "object", "properties": { "vanished_pct": { "type": "number", "nullable": true }, "price_change_share": { "type": "number", "nullable": true } } }, "errors_total": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer" }, "field": { "type": "string", "nullable": true }, "code": { "type": "string" }, "message": { "type": "string" }, "raw": { "type": "string", "nullable": true } } } }, "unknown_brands": { "type": "array", "items": { "type": "object", "properties": { "sample": { "type": "string" }, "rows": { "type": "integer" } } } }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "held_expires_at": { "type": "string", "format": "date-time", "nullable": true }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } ] }, "DecisionComment": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 500 } } }, "OfferInput": { "type": "object", "description": "Новая позиция требует brand, article, name, price_kop, qty; существующая — любые поля", "properties": { "brand": { "type": "string", "maxLength": 60 }, "article": { "type": "string", "maxLength": 60 }, "name": { "type": "string", "maxLength": 200 }, "price_kop": { "type": "integer", "format": "int64", "minimum": 100, "maximum": 10000000000, "description": "Копейки; минимум — настройка minPriceKop (100 = 1 ₽), меньше — PRICE_BELOW_MIN" }, "qty": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "Физический остаток продавца (пишет catalog.stock; резерв под заказы площадка ведёт сама). Любое qty снимает отметку withdrawn." }, "multiplicity": { "type": "integer", "minimum": 1 }, "min_order": { "type": "integer", "minimum": 1 }, "term_days_min": { "type": "integer", "minimum": 0, "maximum": 365 }, "term_days_max": { "type": "integer", "minimum": 0, "maximum": 365 }, "warranty_months": { "type": "integer", "minimum": 1, "maximum": 120, "nullable": true, "description": "Срок гарантии на позицию, месяцев. null — снять срок: действует гарантия по условиям площадки (документ «Условия возврата и гарантии»). Поля нет — срок позиции не меняется. Значение не из 1–120 — строка WARRANTY_INVALID" }, "warranty_manufacturer": { "type": "boolean", "nullable": true, "description": "true — гарантия изготовителя детали, false — гарантия продавца. true принимается только вместе со сроком (в этой строке или уже записанным у позиции), иначе строка WARRANTY_INVALID; при снятии срока признак сбрасывается" }, "probability": { "type": "integer", "minimum": 0, "maximum": 100 }, "warehouse": { "type": "string", "maxLength": 20, "description": "Код склада строки; иначе warehouse пакета; иначе склад по умолчанию" }, "external_id": { "type": "string", "maxLength": 64, "description": "Код позиции у продавца; уникален в пределах склада (один SKU может быть на нескольких складах)" }, "oem": { "type": "string", "maxLength": 200 }, "group": { "type": "string", "maxLength": 60 }, "apply": { "type": "string", "maxLength": 200 }, "condition": { "type": "string", "enum": [ "new", "used" ] }, "vat": { "type": "string", "enum": [ "НДС 22%", "НДС 5%", "Без НДС" ] }, "returnable": { "type": "boolean" }, "photo": { "type": "string", "format": "uri" }, "updated_at": { "type": "string", "format": "date-time", "description": "Время строки по часам клиента; сравнивается только с source_updated_at позиции (STALE_UPDATED_AT)" } } }, "OffersBatchRequest": { "type": "object", "required": [ "offers" ], "properties": { "warehouse": { "type": "string", "maxLength": 20 }, "offers": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/OfferInput" } } } }, "OffersBatchResponse": { "type": "object", "required": [ "received", "results" ], "properties": { "dry_run": { "type": "boolean" }, "received": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" }, "skipped": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "updated", "unchanged", "skipped" ] }, "offer_id": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "code": { "$ref": "#/components/schemas/BatchRowCode" }, "field": { "type": "string" }, "message": { "type": "string" } } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "field": { "type": "string" }, "code": { "$ref": "#/components/schemas/BatchRowCode" }, "message": { "type": "string" } } } } } }, "SellerOffer": { "type": "object", "properties": { "offer_id": { "type": "string" }, "external_id": { "type": "string", "nullable": true }, "brand": { "type": "string" }, "brand_id": { "type": "integer" }, "article": { "type": "string" }, "article_norm": { "type": "string" }, "name": { "type": "string" }, "price_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "currency": { "type": "string", "enum": [ "RUB" ] }, "qty": { "type": "integer", "description": "Физический остаток продавца" }, "multiplicity": { "type": "integer" }, "min_order": { "type": "integer" }, "term_days_min": { "type": "integer", "nullable": true }, "term_days_max": { "type": "integer", "nullable": true }, "probability": { "type": "integer", "nullable": true }, "warehouse": { "type": "string" }, "condition": { "type": "string" }, "vat": { "type": "string" }, "warranty_months": { "type": "integer", "minimum": 1, "maximum": 120, "nullable": true, "description": "Срок гарантии на позицию, месяцев; null — срок не указан: гарантия по условиям площадки (документ «Условия возврата и гарантии»)" }, "warranty_manufacturer": { "type": "boolean", "description": "Гарантия изготовителя детали (false — гарантия продавца); без срока — false" }, "returnable": { "type": "boolean" }, "source_id": { "type": "string" }, "source_kind": { "type": "string" }, "visible": { "type": "boolean" }, "stale": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" }, "qty_reserved": { "type": "integer", "description": "В резерве под заказы" }, "qty_available": { "type": "integer", "description": "Доступно покупателям = qty − qty_reserved" }, "withdrawn": { "type": "boolean", "description": "Снята через DELETE /seller/offers/{external_id}" }, "change_seq": { "type": "integer", "format": "int64" }, "source_updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "Warehouse": { "type": "object", "required": [ "code", "name" ], "properties": { "code": { "type": "string", "maxLength": 20 }, "name": { "type": "string" }, "city": { "type": "string" }, "city_id": { "type": "integer" }, "region": { "type": "string" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "address": { "type": "string" }, "is_default": { "type": "boolean" }, "active": { "type": "boolean" }, "delivery_terms": { "type": "object", "properties": { "extra_days": { "type": "integer" }, "note": { "type": "string" } } }, "offers": { "type": "integer" } } }, "WarehouseList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Warehouse" } } } }, "WarehouseListInput": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Warehouse" } } } }, "OrderLine": { "type": "object", "properties": { "line_id": { "type": "string" }, "offer_id": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "brand": { "type": "string" }, "article": { "type": "string" }, "name": { "type": "string" }, "qty": { "type": "integer" }, "confirmed_qty": { "type": "integer", "nullable": true }, "shipped_qty": { "type": "integer" }, "price_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "sum_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "status": { "type": "string", "nullable": true, "enum": [ "awaiting_confirmation", "confirmed", "rejected", "cancelled", "shipped", null ] }, "reject_reason_code": { "type": "string", "nullable": true }, "term_days_min": { "type": "integer", "nullable": true }, "term_days_max": { "type": "integer", "nullable": true }, "term_days_confirmed": { "type": "integer", "nullable": true }, "warehouse": { "type": "string", "nullable": true }, "external_order_ref": { "type": "string", "nullable": true }, "warranty_months": { "type": "integer", "minimum": 1, "maximum": 120, "nullable": true, "description": "Срок гарантии на позицию на момент заказа, месяцев; null — срок не указан: гарантия по условиям площадки (документ «Условия возврата и гарантии»). Позднейшая правка позиции или КП строку заказа не меняет" }, "warranty_manufacturer": { "type": "boolean", "description": "Гарантия изготовителя детали (false — гарантия продавца); без срока — false" }, "plate": { "type": "string" }, "exchange": { "type": "object", "nullable": true, "description": "Строка заказа из КП: строка КП и позиция заявки (срок — код справочника)", "properties": { "proposal_line_id": { "type": "string" }, "item_id": { "type": "string", "nullable": true }, "term": { "type": "string" }, "term_name": { "type": "string" } } } } }, "OrderBase": { "type": "object", "required": [ "order_id", "number", "status", "lines" ], "properties": { "order_id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_confirmation", "awaiting_payment", "assembling", "shipped", "closed", "return", "cancelled" ] }, "status_name": { "type": "string" }, "test": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "confirm_deadline_at": { "type": "string", "format": "date-time", "nullable": true }, "auto_cancel_at": { "type": "string", "format": "date-time", "nullable": true }, "delivery": { "type": "object", "properties": { "type": { "type": "string" }, "address": { "type": "string" }, "express": { "type": "boolean" } } }, "payment": { "type": "string" }, "comment": { "type": "string" }, "currency": { "type": "string", "enum": [ "RUB" ] }, "total_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "delivery_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "accounting_total_rub": { "type": "number", "description": "total_kop / 100 — сумма учёта в рублях; при неполных рублях дробная (2469.5). Для расчётов берите total_kop" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLine" } }, "documents": { "type": "object", "description": "Номера документов заказа, как их записал продавец. Пустая строка — документа нет. Самих документов в API нет.", "properties": { "invoice": { "type": "string", "description": "Номер счёта." }, "upd": { "type": "string", "description": "Номер УПД. Продавец может выписать УПД до отгрузки; при отгрузке сюда записывается upd_number. Покупателю номер виден только после отгрузки." }, "ksf": { "type": "string", "description": "Номер корректировочного счёта-фактуры заказа. Записывается при согласовании возврата (одобренный возврат товара или возврат денег по претензии): «КСФ-<номер заказа>-1» после первого согласованного возврата, сводный «КСФ-<номер заказа>» — когда их несколько. Без согласованного возврата, у заказа без НДС и у покупателя-физлица КСФ не выставляется." } } }, "change_seq": { "type": "integer", "format": "int64", "description": "Номер последнего изменения заказа (строки, статус, возврат, документ, сообщение)" } } }, "SellerOrder": { "allOf": [ { "$ref": "#/components/schemas/OrderBase" }, { "type": "object", "properties": { "buyer": { "type": "object", "properties": { "code": { "type": "string" }, "city": { "type": "string" }, "ref": { "type": "string", "nullable": true, "description": "Псевдоним пары «продавец — покупатель» (П-XXXXXX), тот же, что в заявках биржи" } } }, "source": { "type": "string", "enum": [ "shop", "exchange" ], "x-extensible-enum": true, "description": "shop — заказ магазина, exchange — заказ из КП биржи" }, "exchange": { "type": "object", "nullable": true, "description": "Заказ из КП: заявка и КП; у заказа магазина — null", "properties": { "exchange_request_id": { "type": "string" }, "request_number": { "type": "string", "nullable": true }, "proposal_id": { "type": "string", "nullable": true }, "proposal_number": { "type": "string", "nullable": true } } }, "requires_confirmation": { "type": "boolean" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "confirm", "reject", "ship" ] }, "description": "Что сейчас можно сделать через API; у заказа из КП — только ship" } } } ] }, "BuyerOrderLine": { "type": "object", "description": "Строка заказа покупателя: внутренних кодов программы продавца (external_id, external_order_ref) в ней нет", "properties": { "line_id": { "type": "string" }, "offer_id": { "type": "string", "nullable": true, "description": "Позиция витрины, по которой оформлена строка; у строк из КП и у заказов песочницы — null" }, "brand": { "type": "string" }, "article": { "type": "string" }, "oem": { "type": "string", "description": "Оригинальный номер продавца у строки заказа из КП (source = exchange): до покупки покупатель его не видит (в ProposalLine — пустая строка), после заказа — здесь, в ответе accept и в УПД. У строк витрины — пустая строка (с 1.5.0)" }, "name": { "type": "string", "description": "Название позиции; контакты и реквизиты продавца в нём заменены на «[скрыто]»" }, "qty": { "type": "integer" }, "confirmed_qty": { "type": "integer", "nullable": true }, "shipped_qty": { "type": "integer" }, "price_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "sum_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "status": { "type": "string", "nullable": true, "enum": [ "awaiting_confirmation", "confirmed", "rejected", "cancelled", "shipped", null ] }, "reject_reason_code": { "type": "string", "nullable": true }, "term_days_min": { "type": "integer", "nullable": true }, "term_days_max": { "type": "integer", "nullable": true }, "term_days_confirmed": { "type": "integer", "nullable": true }, "warehouse": { "type": "string", "nullable": true, "description": "Город склада (не название и не адрес склада продавца)" }, "warehouse_code": { "type": "string", "nullable": true, "description": "Обезличенный код склада «ТТ-014-2», как в поиске; у строк из КП и в песочнице — null" }, "warranty_months": { "type": "integer", "minimum": 1, "maximum": 120, "nullable": true, "description": "Срок гарантии на позицию на момент заказа, месяцев; null — срок не указан: гарантия по условиям площадки (документ «Условия возврата и гарантии»). Позднейшая правка позиции или КП строку заказа не меняет" }, "warranty_manufacturer": { "type": "boolean", "description": "Гарантия изготовителя детали (false — гарантия продавца); без срока — false" }, "plate": { "type": "string" }, "exchange": { "type": "object", "nullable": true, "description": "Строка заказа из КП: строка КП и позиция заявки", "properties": { "proposal_line_id": { "type": "string" }, "item_id": { "type": "string", "nullable": true }, "term": { "type": "string" }, "term_name": { "type": "string" } } }, "alternatives": { "type": "array", "description": "Замена отказанной или отменённой позиции: до трёх предложений с offer_key", "items": { "$ref": "#/components/schemas/Offer" } } } }, "BuyerOrder": { "type": "object", "description": "Заказ покупателя: поля заказа — как у заказа продавца (OrderBase), вместо buyer — seller, строки — BuyerOrderLine: без external_id и external_order_ref (внутренние коды программы продавца, M.6 п.6)", "required": [ "order_id", "number", "status", "lines" ], "properties": { "order_id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_confirmation", "awaiting_payment", "assembling", "shipped", "closed", "return", "cancelled" ] }, "status_name": { "type": "string" }, "test": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "confirm_deadline_at": { "type": "string", "format": "date-time", "nullable": true }, "auto_cancel_at": { "type": "string", "format": "date-time", "nullable": true }, "delivery": { "type": "object", "properties": { "type": { "type": "string" }, "address": { "type": "string" }, "express": { "type": "boolean" } } }, "payment": { "type": "string" }, "comment": { "type": "string" }, "currency": { "type": "string", "enum": [ "RUB" ] }, "total_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "delivery_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "accounting_total_rub": { "type": "number", "description": "total_kop / 100 — сумма учёта в рублях; при неполных рублях дробная (2469.5). Для расчётов берите total_kop" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/BuyerOrderLine" } }, "documents": { "type": "object", "description": "Номера документов заказа — как в кабинете покупателя. Пустая строка — документа пока нет. Самих документов в API нет.", "properties": { "invoice": { "type": "string", "description": "Номер счёта." }, "upd": { "type": "string", "description": "Номер УПД. Пустая строка, пока заказ не отгружен (статус shipped, closed или return), — даже если продавец выписал УПД заранее. Номер вписывает продавец — отдаётся без его контактов и реквизитов." }, "ksf": { "type": "string", "description": "Номер корректировочного счёта-фактуры заказа. Пустая строка, пока по заказу нет согласованного возврата (одобренный возврат товара или возврат денег по претензии), а также у заказа без НДС и у покупателя-физлица. «КСФ-<номер заказа>-1» при одном согласованном возврате, сводный «КСФ-<номер заказа>» — при нескольких." } } }, "change_seq": { "type": "integer", "format": "int64", "description": "Номер последнего изменения заказа (строки, статус, возврат, документ, сообщение)" }, "reference": { "type": "string", "nullable": true }, "seller": { "type": "object", "properties": { "code": { "type": "string" }, "city": { "type": "string" }, "rating": { "type": "number" } } }, "source": { "type": "string", "enum": [ "shop", "exchange" ], "x-extensible-enum": true, "description": "shop — заказ магазина, exchange — заказ из КП биржи" }, "exchange": { "type": "object", "nullable": true, "description": "Заказ из КП: заявка и КП; у заказа магазина — null", "properties": { "exchange_request_id": { "type": "string" }, "request_number": { "type": "string", "nullable": true }, "proposal_id": { "type": "string", "nullable": true }, "proposal_number": { "type": "string", "nullable": true } } }, "requires_confirmation": { "type": "boolean" } } }, "ConfirmRequest": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "required": [ "line_id" ], "properties": { "line_id": { "type": "string" }, "qty": { "type": "integer", "minimum": 1 }, "term_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "external_order_ref": { "type": "string", "maxLength": 64 } } } } } }, "RejectReason": { "type": "string", "enum": [ "out_of_stock", "price_changed", "discontinued", "wrong_item", "cannot_deliver", "duplicate", "other" ] }, "RejectRequest": { "type": "object", "properties": { "reason": { "$ref": "#/components/schemas/RejectReason" }, "comment": { "type": "string", "maxLength": 500 }, "lines": { "type": "array", "items": { "type": "object", "required": [ "line_id", "reason" ], "properties": { "line_id": { "type": "string" }, "reason": { "$ref": "#/components/schemas/RejectReason" }, "comment": { "type": "string", "maxLength": 500 } } } } } }, "ShipRequest": { "type": "object", "properties": { "lines": { "description": "Строки для частичной отгрузки. У заказа из КП биржи (source exchange) на отгрузку не влияют — отгружается весь заказ, но каждый line_id должен быть из этого заказа, иначе 400 VALIDATION_FAILED.", "type": "array", "items": { "type": "string" } }, "track": { "type": "string", "maxLength": 100 }, "upd_number": { "type": "string", "maxLength": 64 } } }, "Offer": { "type": "object", "required": [ "offer_key", "seller_code", "price_kop", "qty" ], "properties": { "offer_key": { "type": "string" }, "name": { "type": "string" }, "seller_code": { "type": "string" }, "seller_rating": { "type": "number", "nullable": true }, "refusal_pct": { "type": "number", "nullable": true }, "city": { "type": "string", "nullable": true }, "country": { "type": "string" }, "warehouse_code": { "type": "string", "nullable": true, "description": "Обезличенный код склада: код продавца + порядковый номер склада, например ТТ-014-1" }, "price_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "currency": { "type": "string", "enum": [ "RUB" ] }, "qty": { "type": "integer", "description": "Доступно к заказу (остаток минус резерв)" }, "multiplicity": { "type": "integer" }, "min_order": { "type": "integer" }, "term_days_min": { "type": "integer", "nullable": true }, "term_days_max": { "type": "integer", "nullable": true }, "probability": { "type": "integer", "nullable": true }, "condition": { "type": "string", "enum": [ "new", "used" ] }, "warranty_months": { "type": "integer", "minimum": 1, "maximum": 120, "nullable": true, "description": "Срок гарантии на позицию, месяцев; null — срок не указан: гарантия по условиям площадки (документ «Условия возврата и гарантии»)" }, "warranty_manufacturer": { "type": "boolean", "description": "Гарантия изготовителя детали (false — гарантия продавца); без срока — false" }, "returnable": { "type": "boolean" }, "vat": { "type": "string" }, "availability": { "type": "string", "enum": [ "in_stock", "on_order", "out" ] }, "stale": { "type": "boolean" }, "price_age_hours": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "region": { "type": "string", "nullable": true }, "photo": { "type": "string", "nullable": true, "description": "Только с разрешённых хостов площадки, иначе null" } } }, "OfferGroup": { "type": "object", "required": [ "kind", "brand_id", "article_norm", "offers" ], "properties": { "kind": { "type": "string", "enum": [ "requested", "analog" ] }, "cross_kind": { "type": "string", "nullable": true, "enum": [ "oem", "analog", null ] }, "brand_id": { "type": "integer" }, "brand": { "type": "string" }, "article": { "type": "string" }, "article_norm": { "type": "string" }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } } } }, "SearchBrands": { "type": "object", "required": [ "mode", "brands" ], "properties": { "mode": { "type": "string", "enum": [ "brands" ] }, "article_norm": { "type": "string" }, "brands": { "type": "array", "items": { "$ref": "#/components/schemas/SearchBrandPair" } }, "similar": { "type": "array", "description": "Только с similar=1: похожие номера — пары «бренд + номер», номер которых начинается с введённого (после нормализации), по номеру и бренду, до 30", "items": { "$ref": "#/components/schemas/SearchBrandPair" } }, "warnings": { "type": "array", "description": "Только с similar=1: SIMILAR_TRUNCATED — похожих номеров больше 30, показаны первые", "items": { "type": "string" } } } }, "SearchBrandPair": { "type": "object", "description": "Пара «бренд + номер» первого шага поиска; второй шаг — ?article=&brand_id=", "properties": { "brand_id": { "type": "integer" }, "brand": { "type": "string" }, "article": { "type": "string", "description": "Номер, как его пишут продавцы (с 1.7.0)" }, "article_norm": { "type": "string", "description": "Нормализованный номер пары (с 1.7.0)" }, "name_sample": { "type": "string" }, "offers": { "type": "integer", "description": "Предложений; 0 — номер известен (кросс), в наличии нет" }, "min_price_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "min_term_days": { "type": "integer", "nullable": true } } }, "SearchOffers": { "type": "object", "required": [ "mode", "groups" ], "properties": { "mode": { "type": "string", "enum": [ "offers" ] }, "query": { "type": "object", "additionalProperties": true }, "total": { "type": "integer" }, "total_exact": { "type": "boolean" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/OfferGroup" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "QuotesRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "offer_key" ], "properties": { "offer_key": { "type": "string" }, "qty": { "type": "integer", "minimum": 1 } } } } } }, "QuotesResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "offer_key": { "type": "string", "nullable": true }, "requested_offer_key": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "price_changed", "insufficient_qty", "multiplicity_violation", "unavailable", "invalid_key" ] }, "price_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "previous_price_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "qty_available": { "type": "integer" }, "qty_requested": { "type": "integer" }, "multiplicity": { "type": "integer" }, "min_order": { "type": "integer" }, "term_days_min": { "type": "integer", "nullable": true }, "term_days_max": { "type": "integer", "nullable": true }, "availability": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "BuyerOrderRequest": { "type": "object", "required": [ "items", "accept_terms" ], "properties": { "reference": { "type": "string", "maxLength": 120 }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "offer_key", "qty" ], "properties": { "offer_key": { "type": "string" }, "qty": { "type": "integer", "minimum": 1, "maximum": 100000 }, "comment": { "type": "string", "maxLength": 500 }, "plate": { "type": "string", "maxLength": 20 } } } }, "delivery": { "type": "object", "properties": { "type": { "type": "string", "description": "Код справочника deliveries (main, pickup, express) или подпись. express — экспресс с ценой и порогом суммы, как delivery.express: true" }, "address": { "type": "string", "maxLength": 300 }, "express": { "type": "boolean", "description": "Экспресс-доставка: цена экспресса и порог суммы заказа; то же даёт type: express" } } }, "payment": { "type": "string", "enum": [ "balance", "invoice", "card_on_delivery", "с баланса", "счёт", "картой при получении" ], "description": "Код справочника payments (GET /dictionary/exchange) или подпись, как у методов биржи. Без поля — с баланса, если тип компании её допускает (balancePaymentTypes), иначе счёт. Явная оплата с баланса у другого типа — 422 BUSINESS_RULE" }, "accept_terms": { "type": "boolean", "enum": [ true ], "description": "Ознакомление с условиями возврата; обязательно true, иначе 422 BUSINESS_RULE (как у корзины сайта)" }, "price_policy": { "type": "string", "enum": [ "strict", "accept_lower" ], "default": "strict" }, "comment": { "type": "string", "maxLength": 500, "description": "Комментарий к заказу, как в корзине сайта: продавец видит его в заказе" } } }, "BuyerOrderCreated": { "type": "object", "required": [ "orders" ], "properties": { "reference": { "type": "string", "nullable": true }, "orders": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "number": { "type": "string" }, "seller_code": { "type": "string" }, "status": { "type": "string" }, "total_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "accounting_total_rub": { "type": "number", "description": "total_kop / 100 — сумма учёта в рублях; при неполных рублях дробная (2469.5). Для расчётов берите total_kop" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "line_id": { "type": "string" }, "brand": { "type": "string" }, "article": { "type": "string" }, "qty": { "type": "integer" }, "price_kop": { "type": "integer", "format": "int64", "minimum": 0, "description": "Копейки" }, "status": { "type": "string", "nullable": true } } } } } } } } }, "WebhookEvent": { "type": "string", "enum": [ "order.created", "order.line_confirmed", "order.line_rejected", "order.line_cancelled", "order.shipped", "import.finished", "import.held", "price.stale", "exchange.request.created", "exchange.request.updated", "exchange.request.closed", "exchange.proposal.received", "exchange.proposal.replaced", "exchange.proposal.withdrawn", "exchange.proposal.accepted", "exchange.proposal.rejected", "*", "order.*", "import.*", "exchange.*" ], "x-extensible-enum": true, "description": "Событие или шаблон: «*» — все события без префикса exchange.; «order.*», «import.*», «exchange.*» — по префиксу. События биржи — только ключу с правом exchange." }, "WebhookInput": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "description": { "type": "string", "maxLength": 100 }, "options": { "$ref": "#/components/schemas/WebhookOptions" } } }, "Webhook": { "type": "object", "properties": { "webhook_id": { "type": "string" }, "url": { "type": "string", "description": "Адрес приёмника: только https, порты 80, 443, 8080, 8443, без логина и пароля в адресе, не во внутреннюю сеть" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "env": { "type": "string", "enum": [ "test", "live" ] }, "enabled": { "type": "boolean", "description": "false — выключен в кабинете или автоматически после webhookDisableAfterFailures (100) неудачных доставок подряд" }, "failures": { "type": "integer", "description": "Неудачных попыток доставки подряд; обнуляется успешной доставкой" }, "disabled_reason": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true, "maxLength": 100 }, "last_delivery": { "type": "object", "nullable": true, "properties": { "at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "delivered", "failed" ] }, "code": { "type": "integer", "nullable": true, "description": "HTTP-код ответа приёмника; null — ответа не было (таймаут, соединение)" } } }, "created_at": { "type": "string", "format": "date-time" }, "options": { "$ref": "#/components/schemas/WebhookOptions" } }, "required": [ "webhook_id", "url", "events", "env", "enabled", "failures", "created_at" ] }, "WebhookCreated": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "Показывается один раз" } } } ] }, "WebhookEnvelope": { "type": "object", "description": "Тело POST на адрес подписки. Заголовки: X-K247-Event, X-K247-Event-Id, X-K247-Delivery-Attempt, X-K247-Signature: t=,v1=", "required": [ "id", "type", "created_at", "env", "data" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "description": "Тип события (WebhookEvent без шаблонов) или ping — проверочное событие POST /webhooks/{id}/test. Перечисление открытое: новые события добавляются без смены версии, неизвестный тип клиент пропускает", "enum": [ "order.created", "order.line_confirmed", "order.line_rejected", "order.line_cancelled", "order.shipped", "import.finished", "import.held", "price.stale", "exchange.request.created", "exchange.request.updated", "exchange.request.closed", "exchange.proposal.received", "exchange.proposal.replaced", "exchange.proposal.withdrawn", "exchange.proposal.accepted", "exchange.proposal.rejected", "ping" ], "x-extensible-enum": true }, "created_at": { "type": "string", "format": "date-time" }, "env": { "type": "string", "enum": [ "test", "live" ] }, "api_version": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "description": "Минимум: order.* — {order_id, number, status, line_ids?, reason?, source, exchange?}; import.* — {import_id, status, counters, held_reason, error_code}; price.stale — {source_id, source_name, fresh_at, ttl_hours}; exchange.* — {role, change_seq и идентификаторы заявки или КП}, состав каждого события — в x-webhooks; ping — {type, webhook_id}. Полные данные — через GET" } }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "order.line_rejected", "created_at": "2026-09-15T09:40:00.000Z", "env": "live", "api_version": "1", "data": { "order_id": "ord_5e1a2b3c4d", "number": "2609-1190", "status": "awaiting_confirmation", "line_ids": [ "l_9a8b7c6d5e" ], "reason": "out_of_stock" } } }, "SandboxOrderRequest": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "offer_id": { "type": "string" }, "external_id": { "type": "string" }, "qty": { "type": "integer", "minimum": 1 } } } }, "delivery": { "type": "object", "properties": { "type": { "type": "string" }, "address": { "type": "string" } } } } }, "BatchRowCode": { "type": "string", "description": "Построчные коды (results[].code в offers/batch, errors[].code импорта, details[].code ошибок). Спецификация F.3, D.9.", "enum": [ "NOT_FOUND", "KEY_CONFLICT", "STALE_UPDATED_AT", "BRAND_EMPTY", "BRAND_UNKNOWN", "ARTICLE_EMPTY", "NAME_EMPTY", "PRICE_INVALID", "PRICE_BELOW_MIN", "PRICE_TOO_BIG", "QTY_INVALID", "TERM_UNPARSED", "WAREHOUSE_UNKNOWN", "DUPLICATE_ROW", "DUPLICATE_EXTERNAL_ID", "ROW_TOO_LONG", "VALUE_TOO_LONG", "PHOTO_URL_INVALID", "MULTIPLICITY_VIOLATION", "MIN_ORDER_VIOLATION", "QTY_TOO_BIG", "SUM_TOO_BIG", "ROW_INVALID", "UPDATED_AT_INVALID", "ITEM_UNKNOWN", "VAT_INVALID", "EXTERNAL_ID_INVALID", "CONTACTS_FOUND", "WARRANTY_INVALID", "WARRANTY_IGNORED" ] }, "WebhookOptions": { "type": "object", "description": "Фильтр exchange.request.created (M.8.3): регион заявок (all — ключу с регионом all и подписке из кабинета), группы и рынки техники", "properties": { "exchange_region": { "type": "string", "enum": [ "own", "all" ], "default": "own" }, "groups": { "type": "array", "description": "Группы техники; пустой список — все. «Иное» (other) не указывается (400 VALIDATION_FAILED): заявки группы «Иное» приходят при любом фильтре групп и рынков, легковые и грузовые без рынка — при любом фильтре рынков", "items": { "type": "string", "enum": [ "car", "truck", "special", "equip" ] } }, "markets": { "type": "array", "items": { "type": "string", "enum": [ "eu", "cn", "jp", "kr", "us", "ru" ] } } } }, "ExchangeCompetition": { "type": "object", "description": "Конкуренция по заявке для продавца: суммы соперников не раскрываются; место — по стоимости плана «Принять»", "properties": { "proposals": { "type": "integer" }, "sellers": { "type": "integer" }, "limit": { "type": "integer", "description": "0 — без лимита" }, "slots_left": { "type": "integer", "nullable": true }, "my_rank": { "type": "integer", "description": "0 — действующего КП нет" }, "my_value_kop": { "type": "integer", "format": "int64" }, "basis": { "type": "string", "enum": [ "accept_plan" ] } } }, "SellerExchangeRequest": { "type": "object", "required": [ "exchange_request_id", "number", "status", "exchange", "test", "items", "buyer", "competition", "can_propose", "change_seq" ], "properties": { "exchange_request_id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "done", "closed", "expired" ], "x-extensible-enum": true }, "exchange": { "type": "string", "enum": [ "new", "used", "all" ] }, "test": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "revision": { "type": "integer", "description": "Правок заявки покупателем" }, "revised_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "deadline": { "type": "string", "nullable": true, "enum": [ "today", "days_2_3", "week", null ], "x-extensible-enum": true }, "deadline_name": { "type": "string" }, "priority": { "type": "string", "nullable": true, "enum": [ "fast", "cheap", "any", null ], "x-extensible-enum": true }, "priority_name": { "type": "string" }, "vehicle": { "type": "object", "properties": { "vgroup": { "type": "string", "nullable": true, "description": "Группа техники: car, truck, special, equip или other («Иное», без рынка). Список открытый — новые группы приходят в справочнике /dictionary/exchange" }, "market": { "type": "string", "nullable": true, "description": "Рынок легковых и грузовых; null — рынок «Иное» (не указан) или группа без рынков" }, "category": { "type": "string" }, "brand": { "type": "string" }, "model": { "type": "string" }, "year": { "type": "string" }, "vin": { "type": "string" } }, "description": "Без госномера (Р3); свободный текст очищен от контактов" }, "buyer": { "type": "object", "properties": { "ref": { "type": "string", "description": "Постоянный псевдоним пары «продавец — покупатель»" }, "city": { "type": "string" } } }, "city": { "type": "string" }, "region": { "type": "string" }, "delivery": { "type": "string", "nullable": true, "enum": [ "main", "pickup", "express", null ], "x-extensible-enum": true, "description": "Способ доставки из справочника. Значение вне справочника (до версии 1.5.0 так попадал адрес покупателя из классической формы кабинета) не отдаётся — null" }, "delivery_name": { "type": "string", "description": "Подпись способа доставки из справочника; при delivery = null — пустая строка. Адреса покупателя в заявке нет: продавец видит его только в заказе" }, "pickup": { "type": "string", "nullable": true, "enum": [ "delivery", "pickup", null ], "x-extensible-enum": true }, "pickup_name": { "type": "string" }, "payment": { "type": "string", "nullable": true, "enum": [ "balance", "invoice", "card_on_delivery", null ], "x-extensible-enum": true }, "payment_name": { "type": "string" }, "comment": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "item_id": { "type": "string" }, "position": { "type": "integer" }, "name": { "type": "string" }, "qty": { "type": "integer" }, "comment": { "type": "string" }, "open": { "type": "boolean", "description": "Позиция ещё не выкуплена" } } } }, "max_proposals": { "type": "integer", "description": "0 — без лимита" }, "competition": { "$ref": "#/components/schemas/ExchangeCompetition" }, "my_proposals": { "type": "array", "items": { "type": "object", "properties": { "proposal_id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string" }, "value_kop": { "type": "integer", "format": "int64" } } } }, "current_proposal_id": { "type": "string", "nullable": true, "description": "КП компании в статусе sent — его заменит следующая отправка" }, "can_propose": { "type": "boolean" }, "cannot_propose_reason": { "type": "string", "nullable": true, "enum": [ "closed", "expired", "limit", "region", "bought", "replace_limit", null ], "x-extensible-enum": true }, "replace_available_at": { "type": "string", "format": "date-time", "nullable": true }, "unread_messages": { "type": "integer", "description": "Непрочитанные сообщения покупателя в ветке заявки (текст — в кабинете)" }, "change_seq": { "type": "integer", "format": "int64" } } }, "SellerExchangeRequestList": { "type": "object", "required": [ "items", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SellerExchangeRequest" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "ProposalLine": { "type": "object", "properties": { "proposal_line_id": { "type": "string" }, "item_id": { "type": "string" }, "brand": { "type": "string" }, "article": { "type": "string", "description": "Артикул продавца. Программе продавца — как записан; покупателю — пустая строка и до, и после покупки: до покупки артикул продавца не раскрывается, после заказа он есть в строках заказа (BuyerOrderLine.article, ответ accept) и в УПД (с 1.5.0)" }, "oem": { "type": "string", "description": "Оригинальный номер. Программе продавца — как записан; покупателю — пустая строка, как article: до покупки не раскрывается, после заказа он есть в строках заказа (BuyerOrderLine.oem, ответ accept) и в УПД (с 1.5.0)" }, "price_kop": { "type": "integer", "format": "int64" }, "qty": { "type": "integer" }, "sum_kop": { "type": "integer", "format": "int64" }, "vat": { "type": "string", "nullable": true, "enum": [ "vat22", "vat5", "no_vat", null ], "x-extensible-enum": true }, "vat_name": { "type": "string" }, "term": { "type": "string", "description": "Код справочника terms (dictionary/exchange); other — текст вне справочника (старые строки, «Подбор со склада»), он — в term_name. hours_3, tomorrow_am, week — с 1.5.0", "enum": [ "in_stock", "hours_3", "tomorrow_am", "days_2_3", "days_4_5", "week", "on_order", "other" ], "x-extensible-enum": true }, "term_name": { "type": "string" }, "term_days": { "type": "integer", "nullable": true }, "availability": { "type": "string", "description": "in_stock — только у term = in_stock (у other — при term_days = 0), иначе on_order. «Через 3 часа» (hours_3, 0 дней) — on_order. До 1.5.0 in_stock давал и term_days = 0 при любом коде", "enum": [ "in_stock", "on_order" ] }, "stock": { "type": "integer" }, "comment": { "type": "string" }, "warranty_months": { "type": "integer", "minimum": 1, "maximum": 120, "nullable": true, "description": "Срок гарантии по строке КП, месяцев; null — срок не указан: гарантия по условиям площадки (документ «Условия возврата и гарантии»)" }, "warranty_manufacturer": { "type": "boolean", "description": "Гарантия изготовителя детали (false — гарантия продавца); без срока — false" }, "photo_url": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true, "description": "Код позиции в программе продавца — только продавцу" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected", "closed" ], "x-extensible-enum": true }, "bought_qty": { "type": "integer" }, "left_qty": { "type": "integer" }, "counter_price_kop": { "type": "integer", "nullable": true, "description": "Зарезервировано, всегда null" } } }, "SellerProposal": { "type": "object", "required": [ "proposal_id", "number", "exchange_request_id", "status", "lines", "value_kop", "actions", "change_seq" ], "properties": { "proposal_id": { "type": "string" }, "number": { "type": "string" }, "exchange_request_id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "partial", "accepted", "rejected", "superseded", "withdrawn", "closed", "done", "returned" ], "x-extensible-enum": true }, "test": { "type": "boolean" }, "via": { "type": "string", "enum": [ "cabinet", "api", "sandbox" ], "x-extensible-enum": true }, "replaces_proposal_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "comment": { "type": "string" }, "value_kop": { "type": "integer", "format": "int64", "description": "Стоимость по плану «Принять»: по позиции — самый дешёвый за штуку вариант, не больше потребности" }, "lines_sum_kop": { "type": "integer", "format": "int64", "description": "Сумма всех живых строк, как прислал продавец" }, "coverage": { "type": "object", "properties": { "items_open": { "type": "integer" }, "items_offered": { "type": "integer" }, "items_full": { "type": "integer" } } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalLine" } }, "orders": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "number": { "type": "string" } } } }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "withdraw" ] } }, "counter": { "type": "object", "nullable": true, "description": "Зарезервировано, всегда null" }, "competition": { "$ref": "#/components/schemas/ExchangeCompetition" }, "change_seq": { "type": "integer", "format": "int64" } } }, "SellerProposalList": { "type": "object", "required": [ "items", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SellerProposal" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "ProposalLineInput": { "type": "object", "required": [ "price_kop" ], "properties": { "item_id": { "type": "string", "description": "Обязателен, если позиций в заявке больше одной" }, "brand": { "type": "string", "maxLength": 60, "description": "Для mode send обязателен" }, "article": { "type": "string", "maxLength": 60 }, "oem": { "type": "string", "maxLength": 60 }, "price_kop": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 10000000000 }, "qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "vat": { "type": "string", "description": "vat22 (по умолчанию), vat5, no_vat или подпись" }, "term": { "type": "string", "description": "Код справочника terms (dictionary/exchange); hours_3, tomorrow_am, week — с 1.5.0. Без term код выводится из term_days: 0 → in_stock, 1–3 → days_2_3, 4–5 → days_4_5, больше → on_order; без обоих — in_stock. Неизвестный код — 400 VALIDATION_FAILED, в details — TERM_UNPARSED", "enum": [ "in_stock", "hours_3", "tomorrow_am", "days_2_3", "days_4_5", "week", "on_order" ] }, "term_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "stock": { "type": "integer", "minimum": 0 }, "comment": { "type": "string", "maxLength": 500 }, "warranty_months": { "type": "integer", "minimum": 1, "maximum": 120, "nullable": true, "description": "Срок гарантии по строке КП, месяцев. null или без поля — срок не указан: гарантия по условиям площадки (документ «Условия возврата и гарантии»). Значение не из 1–120 — VALIDATION_FAILED, details[].code WARRANTY_INVALID" }, "warranty_manufacturer": { "type": "boolean", "nullable": true, "description": "true — гарантия изготовителя детали, false или без поля — гарантия продавца. true без warranty_months — VALIDATION_FAILED, details[].code WARRANTY_INVALID" }, "photo_url": { "type": "string", "maxLength": 500, "description": "https со списка фотохостингов площадки (dictionary/exchange photo_hosts)" }, "external_id": { "type": "string", "pattern": "^[A-Za-z0-9._/-]{1,64}$" } } }, "ProposalInput": { "type": "object", "required": [ "lines" ], "properties": { "mode": { "type": "string", "enum": [ "send", "draft" ], "default": "send" }, "replaces_proposal_id": { "type": "string", "nullable": true, "description": "Защита от гонок: должен совпасть с current_proposal_id заявки" }, "comment": { "type": "string", "maxLength": 1000 }, "lines": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/components/schemas/ProposalLineInput" }, "description": "Не больше 20 вариантов на позицию" } } }, "SandboxExchangeRequestInput": { "type": "object", "properties": { "scenario": { "type": "string", "enum": [ "accept", "accept_partial", "reject", "close", "expire", "compete" ], "default": "accept" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "qty": { "type": "integer", "minimum": 1 }, "comment": { "type": "string", "maxLength": 500 } } } }, "deadline": { "type": "string", "enum": [ "today", "days_2_3", "week" ], "default": "week" } } }, "ExchangeDictionary": { "type": "object", "required": [ "version", "exchanges", "deadlines", "vats", "terms", "regions", "limits" ], "properties": { "version": { "type": "string" }, "exchanges": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } }, "vgroups": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "markets": { "type": "boolean" } } } }, "markets": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } }, "deadlines": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "hours": { "type": "integer" }, "expires": { "type": "string", "description": "end_of_day_msk — до конца дня по Москве; с 1.5.2 заявка со сроком today, созданная или сохранённая правкой меньше чем за час до конца суток, открыта до конца следующего дня" } } } }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } }, "pickups": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } }, "vats": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } }, "terms": { "type": "array", "description": "Сроки строки КП в порядке списка формы: in_stock, hours_3 (через 3 часа), tomorrow_am (завтра с утра), days_2_3, days_4_5, week (через неделю), on_order; days — дни для term_days (у on_order — null). hours_3, tomorrow_am, week — с 1.5.0", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "days": { "type": "integer", "nullable": true } } } }, "regions": { "type": "array", "items": { "type": "string" } }, "request_statuses": { "type": "array", "items": { "type": "string" } }, "proposal_statuses": { "type": "array", "items": { "type": "string" } }, "line_statuses": { "type": "array", "items": { "type": "string" } }, "max_proposals": { "type": "object", "description": "Лимит числа КП на заявку: min и max — что принимает API (0 — без лимита); cabinet — значения, которые ставит форма кабинета. С 1.5.2 — только [0]: форма кабинета лимит не задаёт (до 1.5.2 — [0, 3, 5, 10])" }, "photo_hosts": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object" } } }, "BuyerExchangeRequestInput": { "type": "object", "required": [ "vehicle", "items" ], "properties": { "reference": { "type": "string", "maxLength": 120, "description": "Свой номер заявки покупателя: по нему ищет GET …?reference=" }, "exchange": { "type": "string", "enum": [ "new", "used", "all" ], "default": "new" }, "vehicle": { "type": "object", "required": [ "brand" ], "properties": { "vgroup": { "type": "string", "description": "other — «Иное»: заявку видят продавцы с любым фильтром группы и рынка", "enum": [ "car", "truck", "special", "equip", "other" ], "default": "truck" }, "market": { "type": "string", "enum": [ "eu", "cn", "jp", "kr", "us", "ru" ], "description": "Только для car и truck; не передан или пустой — рынок «Иное» (заявку видят продавцы с любым фильтром рынка). У других групп не сохраняется" }, "brand": { "type": "string", "maxLength": 60 }, "model": { "type": "string", "maxLength": 60 }, "year": { "type": "string", "description": "Четыре цифры от 1950 до следующего года или пусто" }, "vin": { "type": "string", "maxLength": 20, "description": "VIN, номер шасси или кузова: латинские буквы, цифры и дефис" }, "plate": { "type": "string", "maxLength": 12 } } }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "comment": { "type": "string", "maxLength": 500 } } } }, "deadline": { "type": "string", "enum": [ "today", "days_2_3", "week" ], "default": "today" }, "priority": { "type": "string", "enum": [ "fast", "cheap", "any" ], "default": "any" }, "max_proposals": { "type": "integer", "minimum": 0, "maximum": 50, "default": 0 }, "delivery": { "type": "string", "enum": [ "main", "pickup", "express" ], "default": "main" }, "pickup": { "type": "string", "enum": [ "delivery", "pickup" ], "default": "delivery" }, "pickup_address": { "type": "string", "maxLength": 300, "description": "Адрес получения (адрес доставки по этой заявке); без поля — адрес компании. Продавцу не отдаётся ни в API, ни в кабинете: адрес он видит только в заказе. При «Принять» без delivery.address становится адресом доставки заказа (кроме самовывоза)" }, "payment": { "type": "string", "enum": [ "balance", "invoice", "card_on_delivery" ], "description": "По умолчанию — balance разрешённым типам компаний, иначе invoice" }, "city": { "type": "string", "maxLength": 60 }, "region": { "type": "string", "description": "Регион из справочника GET /dictionary/exchange" }, "comment": { "type": "string", "maxLength": 1000 }, "sandbox": { "type": "object", "description": "Только тестовый ключ: сценарий роботов-продавцов песочницы (M.9.1)", "properties": { "scenario": { "type": "string", "enum": [ "standard", "two_sellers", "withdraw", "no_answer", "expire" ], "default": "standard" } } } } }, "BuyerExchangeRequestUpdate": { "type": "object", "description": "Передаются только изменяемые поля: непереданное поле не меняется, null или \"\" у необязательного текста (model, year, vin, plate, comment, pickup_address) — очистить. items — полный новый список: у сохраняемой позиции указывается item_id. exchange — смена биржи: расширить можно всегда, сузить — если продавцы с действующими КП не потеряют доступ. reference правкой не меняется (400).", "properties": { "vehicle": { "type": "object", "properties": { "vgroup": { "type": "string", "description": "other — «Иное»: заявку видят продавцы с любым фильтром группы и рынка", "enum": [ "car", "truck", "special", "equip", "other" ] }, "market": { "type": "string", "enum": [ "eu", "cn", "jp", "kr", "us", "ru" ], "description": "Только для car и truck; не передан или пустой — рынок «Иное» (заявку видят продавцы с любым фильтром рынка). У других групп не сохраняется" }, "brand": { "type": "string", "maxLength": 60 }, "model": { "type": "string", "maxLength": 60 }, "year": { "type": "string", "description": "Четыре цифры от 1950 до следующего года или пусто" }, "vin": { "type": "string", "maxLength": 20, "description": "VIN, номер шасси или кузова: латинские буквы, цифры и дефис" }, "plate": { "type": "string", "maxLength": 12 } } }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "comment": { "type": "string", "maxLength": 500 }, "item_id": { "type": "string", "description": "Позиция этой заявки; без него позиция считается новой" } } } }, "exchange": { "type": "string", "enum": [ "new", "used", "all" ], "description": "Биржа заявки. Расширить (new или used → all) можно всегда: продавцам, которым заявка стала видна, уходит exchange.request.created. Сузить (all → new или used, new ↔ used) нельзя, пока у продавцов, которые потеряют доступ к заявке, есть действующие КП (sent, partial): 409 INVALID_STATE, details[0].field = exchange; каких продавцов это касается, ответ не говорит. Черновики таких продавцов закрываются. Номер заявки не меняется. null или \"\" — 400" }, "deadline": { "type": "string", "enum": [ "today", "days_2_3", "week" ] }, "priority": { "type": "string", "enum": [ "fast", "cheap", "any" ] }, "max_proposals": { "type": "integer", "minimum": 0, "maximum": 50 }, "delivery": { "type": "string", "enum": [ "main", "pickup", "express" ] }, "pickup": { "type": "string", "enum": [ "delivery", "pickup" ] }, "pickup_address": { "type": "string", "maxLength": 300 }, "payment": { "type": "string", "enum": [ "balance", "invoice", "card_on_delivery" ], "description": "По умолчанию — balance разрешённым типам компаний, иначе invoice" }, "city": { "type": "string", "maxLength": 60 }, "region": { "type": "string", "description": "Регион из справочника GET /dictionary/exchange" }, "comment": { "type": "string", "maxLength": 1000 } } }, "BuyerExchangeRequest": { "type": "object", "required": [ "exchange_request_id", "number", "status", "items" ], "properties": { "exchange_request_id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "done", "closed", "expired" ], "x-extensible-enum": true }, "exchange": { "type": "string", "enum": [ "new", "used", "all" ], "x-extensible-enum": true }, "test": { "type": "boolean" }, "via": { "type": "string", "description": "cabinet, api или sandbox" }, "reference": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "revision": { "type": "integer" }, "revised_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "deadline": { "type": "string", "nullable": true }, "deadline_name": { "type": "string" }, "priority": { "type": "string", "nullable": true }, "priority_name": { "type": "string" }, "vehicle": { "type": "object", "properties": { "vgroup": { "type": "string", "nullable": true, "description": "Группа техники: car, truck, special, equip или other («Иное», без рынка). Список открытый — новые группы приходят в справочнике /dictionary/exchange" }, "market": { "type": "string", "nullable": true, "description": "Рынок легковых и грузовых; null — рынок «Иное» (не указан) или группа без рынков" }, "category": { "type": "string" }, "brand": { "type": "string" }, "model": { "type": "string" }, "year": { "type": "string" }, "vin": { "type": "string" }, "plate": { "type": "string" } } }, "city": { "type": "string" }, "region": { "type": "string" }, "delivery": { "type": "string", "nullable": true }, "delivery_name": { "type": "string" }, "pickup": { "type": "string", "nullable": true }, "pickup_name": { "type": "string" }, "pickup_address": { "type": "string" }, "payment": { "type": "string", "nullable": true }, "payment_name": { "type": "string" }, "comment": { "type": "string" }, "max_proposals": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "item_id": { "type": "string" }, "position": { "type": "integer" }, "name": { "type": "string" }, "qty": { "type": "integer" }, "comment": { "type": "string" }, "bought_qty": { "type": "integer" }, "need_qty": { "type": "integer" }, "open": { "type": "boolean" } } } }, "proposals_summary": { "type": "object", "description": "Действующие КП, продавцы, всего КП и самая дешёвая стоимость КП по плану «Принять»", "properties": { "active": { "type": "integer" }, "sellers": { "type": "integer" }, "total": { "type": "integer" }, "best_value_kop": { "type": "integer", "format": "int64", "nullable": true } } }, "unread_messages": { "type": "integer" }, "change_seq": { "type": "integer", "format": "int64" } } }, "BuyerExchangeRequestList": { "type": "object", "required": [ "items", "next_cursor", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BuyerExchangeRequest" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "BuyerProposal": { "type": "object", "required": [ "proposal_id", "number", "exchange_request_id", "status", "lines" ], "description": "КП покупателю: продавец обезличен (код, город, регион, рейтинг), внутренних кодов его программы (external_id) и канала нет", "properties": { "proposal_id": { "type": "string" }, "number": { "type": "string" }, "exchange_request_id": { "type": "string" }, "status": { "type": "string", "x-extensible-enum": true }, "test": { "type": "boolean" }, "replaces_proposal_id": { "type": "string", "nullable": true }, "seller": { "type": "object", "properties": { "code": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "rating": { "type": "number", "nullable": true }, "refusal_pct": { "type": "number", "nullable": true } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "comment": { "type": "string" }, "value_kop": { "type": "integer", "format": "int64", "description": "Стоимость КП по плану «Принять» на сейчас, копейки" }, "lines_sum_kop": { "type": "integer", "format": "int64", "description": "Копейки" }, "coverage": { "type": "object", "properties": { "items_open": { "type": "integer" }, "items_offered": { "type": "integer" }, "items_full": { "type": "integer" } } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalLine" } }, "orders": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "number": { "type": "string" } } } }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "accept", "reject" ], "x-extensible-enum": true } }, "counter": { "type": "object", "nullable": true, "description": "Зарезервировано: встречной цены в v1 нет" }, "change_seq": { "type": "integer", "format": "int64" } } }, "BuyerProposalList": { "type": "object", "required": [ "items", "next_cursor", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BuyerProposal" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "AcceptProposalInput": { "type": "object", "required": [ "accept_terms" ], "properties": { "lines": { "type": "array", "minItems": 1, "maxItems": 200, "description": "Строки этого КП; без поля — план «Принять»: по одному самому дешёвому варианту на каждую открытую позицию", "items": { "type": "object", "required": [ "proposal_line_id" ], "properties": { "proposal_line_id": { "type": "string" }, "qty": { "type": "integer", "minimum": 1, "description": "По умолчанию — остаток строки в пределах потребности позиции" } } } }, "payment": { "type": "string", "enum": [ "balance", "invoice", "card_on_delivery" ], "description": "Без поля — способ из заявки" }, "delivery": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "main", "pickup", "express" ], "description": "Без поля — способ доставки из заявки" }, "address": { "type": "string", "maxLength": 300, "description": "Адрес доставки заказа. Без поля — адрес получения заявки (pickup_address), при пустом адресе заявки — адрес компании покупателя из кабинета; при самовывозе (pickup: pickup или delivery.type: pickup) — пункт самовывоза площадки строкой «самовывоз, <адрес площадки>», а если адрес площадки не указан — адрес компании (с 1.5.2; раньше при самовывозе — всегда адрес компании)" } } }, "plate": { "type": "string", "maxLength": 12 }, "reference": { "type": "string", "maxLength": 120 }, "accept_terms": { "type": "boolean", "enum": [ true ], "description": "Согласие с условиями возврата обязательно и в песочнице" } } }, "AcceptProposalResult": { "type": "object", "required": [ "exchange_request_id", "proposal_id", "orders" ], "properties": { "exchange_request_id": { "type": "string" }, "proposal_id": { "type": "string" }, "proposal_status": { "type": "string" }, "request_status": { "type": "string" }, "orders": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "number": { "type": "string" }, "source": { "type": "string" }, "seller_code": { "type": "string" }, "status": { "type": "string" }, "total_kop": { "type": "integer", "format": "int64", "description": "Копейки" }, "accounting_total_rub": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "line_id": { "type": "string" }, "proposal_line_id": { "type": "string", "nullable": true }, "item_id": { "type": "string", "nullable": true }, "brand": { "type": "string" }, "article": { "type": "string" }, "oem": { "type": "string", "description": "Оригинальный номер продавца строки КП: после покупки покупатель его видит, как и article (с 1.5.0)" }, "qty": { "type": "integer" }, "price_kop": { "type": "integer", "format": "int64", "description": "Копейки" }, "status": { "type": "string", "nullable": true } } } } } } } } } } }, "x-webhooks": { "event": { "post": { "summary": "Доставка события на адрес подписки", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "order.line_rejected", "created_at": "2026-09-15T09:40:00.000Z", "env": "live", "api_version": "1", "data": { "order_id": "ord_5e1a2b3c4d", "number": "2609-1190", "status": "awaiting_confirmation", "line_ids": [ "l_9a8b7c6d5e" ], "reason": "out_of_stock" } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч, 24 ч (7 попыток всего), затем событие не доставлено" } }, "description": "POST JSON-конверта на адрес подписки. Заголовки: Content-Type: application/json, User-Agent: K247-Webhooks/1, X-K247-Event, X-K247-Event-Id (= id конверта), X-K247-Delivery-Attempt (с 1), X-K247-Signature: t=,v1=. Проверка у получателя: пересчитать HMAC по сырому телу, сравнить за постоянное время, |now − t| ≤ 300 с, хранить обработанные id не меньше 72 ч (дубли возможны). Порядок событий не гарантируется. Редиректы не выполняются (3xx — неуспех), тело ответа читается до 4 КБ и отбрасывается. На подписку — не больше 2 одновременных доставок. После 100 неудачных попыток подряд подписка выключается, компании приходит уведомление." } }, "ping": { "post": { "summary": "Проверочное событие подписки (ping)", "description": "Ставится методом POST /webhooks/{id}/test и кнопкой «Проверить подключение» в кабинете. Отвечайте 2xx — этого достаточно, чтобы убедиться в адресе и подписи. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "ping", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "type": "ping", "webhook_id": "wh_4b2a1c0d9e" } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "order.created": { "post": { "summary": "Новый заказ (order.created)", "description": "Продавцу — по его позициям, покупателю — по его заказу. У заказа из КП биржи source = exchange и блок exchange (M.7.4). Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "order.created", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "order_id": "ord_5e1a2b3c4d", "number": "2609-1190", "status": "awaiting_confirmation", "source": "shop" } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "order.line_confirmed": { "post": { "summary": "Продавец подтвердил позиции (order.line_confirmed)", "description": "В data.line_ids — подтверждённые строки. Полные данные — GET /buyer/orders/{id} или /seller/orders/{id}. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "order.line_confirmed", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "order_id": "ord_5e1a2b3c4d", "number": "2609-1190", "status": "assembling", "line_ids": [ "l_9a8b7c6d5e" ], "source": "shop" } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "order.line_rejected": { "post": { "summary": "Отказ по позициям (order.line_rejected)", "description": "Причина — data.reason из справочника отказов (GET /dictionary/statuses). Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "order.line_rejected", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "order_id": "ord_5e1a2b3c4d", "number": "2609-1190", "status": "awaiting_confirmation", "line_ids": [ "l_9a8b7c6d5e" ], "reason": "out_of_stock", "source": "shop" } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "order.line_cancelled": { "post": { "summary": "Позиции отменены (order.line_cancelled)", "description": "Покупателем, менеджером или по сроку подтверждения (reason: sla_timeout). Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "order.line_cancelled", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "order_id": "ord_5e1a2b3c4d", "number": "2609-1190", "status": "cancelled", "line_ids": [ "l_9a8b7c6d5e" ], "reason": "buyer_cancel", "source": "shop" } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "order.shipped": { "post": { "summary": "Заказ отгружен (order.shipped)", "description": "Приходит обеим сторонам; статус заказа — data.status. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "order.shipped", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "order_id": "ord_5e1a2b3c4d", "number": "2609-1195", "status": "shipped", "source": "exchange", "exchange": { "exchange_request_id": "r_8c1d2e3f4a", "proposal_id": "o_6a7b8c9d0e" } } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "import.finished": { "post": { "summary": "Загрузка прайса завершена (import.finished)", "description": "data.status: published, failed или rejected; в counters — строки загрузки. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "import.finished", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "import_id": "imp_7d2f1c9a0b", "status": "published", "counters": { "rows_total": 48210, "rows_valid": 48100, "published": 48100 } } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "import.held": { "post": { "summary": "Загрузка остановлена для проверки (import.held)", "description": "Подтвердите или отклоните загрузку: POST /seller/imports/{id}/approve или /reject. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "import.held", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "import_id": "imp_7d2f1c9a0b", "status": "held", "held_reason": "vanished_pct" } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "price.stale": { "post": { "summary": "Прайс устарел (price.stale)", "description": "Источник не обновлялся дольше срока — позиции показываются «под заказ». Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "price.stale", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "source_id": "src_91ab", "source_name": "Прайс по ссылке", "fresh_at": "2026-09-19T05:00:00.000Z", "ttl_hours": 72 } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "exchange.request.created": { "post": { "summary": "Новая заявка на бирже (exchange.request.created)", "description": "Продавцу, которому заявка видна по правилам ленты (регион ключа, биржа по типу компании) и фильтру подписки options. Приходит и при смене биржи правкой заявки (exchange в POST /buyer/exchange/requests/{id}/update) — продавцам, которым заявка стала видна; revision у такой заявки больше 0. Заявки группы «Иное» (vgroup other) приходят при любом фильтре групп и рынков, легковые и грузовые без рынка — при любом фильтре рынков. Шаблон «*» это событие не включает — подписывайтесь точным именем или exchange.*. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "exchange.request.created", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "role": "seller", "exchange_request_id": "r_8c1d2e3f4a", "number": "2609-412", "exchange": "new", "vgroup": "truck", "market": "eu", "region": "Санкт-Петербург", "city": "Санкт-Петербург", "items_count": 2, "expires_at": "2026-09-22T20:59:59.000Z", "change_seq": 184290 } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "exchange.request.updated": { "post": { "summary": "Заявка изменена (exchange.request.updated)", "description": "Продавцу с черновиком или действующим КП. reason: edited — покупатель изменил заявку; items_closed — позиции выкуплены (у другого продавца или другим вариантом вашего же КП), и строки вашего КП по ним закрыты: невыбранный вариант своей строки тоже приходит в closed_proposal_line_ids. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "exchange.request.updated", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "role": "seller", "exchange_request_id": "r_8c1d2e3f4a", "number": "2609-412", "revision": 1, "reason": "edited", "closed_proposal_line_ids": [ "ol_91a2b3c4d5" ], "your_proposal_ids": [ "o_6a7b8c9d0e" ], "change_seq": 184301 } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "exchange.request.closed": { "post": { "summary": "Заявка закрыта (exchange.request.closed)", "description": "Покупателю — по его заявке, продавцам — по заявке с их КП. reason: bought (выкуплена), buyer_closed (снята), expired (срок), manager_closed. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "exchange.request.closed", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "role": "seller", "exchange_request_id": "r_8c1d2e3f4a", "number": "2609-412", "status": "expired", "reason": "expired", "your_proposal_ids": [ "o_6a7b8c9d0e" ], "change_seq": 184340 } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "exchange.proposal.received": { "post": { "summary": "Пришло КП (exchange.proposal.received)", "description": "Покупателю: продавец прислал КП, которое ничего не заменило. Данные — GET /buyer/exchange/proposals/{id}. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "exchange.proposal.received", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "role": "buyer", "proposal_id": "o_6a7b8c9d0e", "exchange_request_id": "r_8c1d2e3f4a", "number": "ТТ-014-00132", "seller_code": "ТТ-014", "change_seq": 184311 } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "exchange.proposal.replaced": { "post": { "summary": "КП заменено (exchange.proposal.replaced)", "description": "Покупателю: продавец прислал новое КП вместо прежнего. Прежнее переходит в статус superseded. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "exchange.proposal.replaced", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "role": "buyer", "proposal_id": "o_7b8c9d0e1f", "replaced_proposal_id": "o_6a7b8c9d0e", "exchange_request_id": "r_8c1d2e3f4a", "number": "ТТ-014-00133", "seller_code": "ТТ-014", "change_seq": 184352 } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "exchange.proposal.withdrawn": { "post": { "summary": "КП снято продавцом (exchange.proposal.withdrawn)", "description": "Покупателю: КП больше не действует, «Принять» по нему ответит 409 PROPOSAL_NOT_ACTIVE. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "exchange.proposal.withdrawn", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "role": "buyer", "proposal_id": "o_6a7b8c9d0e", "exchange_request_id": "r_8c1d2e3f4a", "number": "ТТ-014-00132", "seller_code": "ТТ-014", "change_seq": 184360 } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "exchange.proposal.accepted": { "post": { "summary": "КП принято покупателем (exchange.proposal.accepted)", "description": "Продавцу: по КП оформлены заказы. scope: full — КП принято целиком (accepted): живых строк не осталось — купленные и закрытые невыбранные варианты; partial — часть. proposal_line_ids — только купленные строки. Заказы — GET /seller/orders?source=exchange. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "exchange.proposal.accepted", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "role": "seller", "proposal_id": "o_6a7b8c9d0e", "exchange_request_id": "r_8c1d2e3f4a", "number": "ТТ-014-00132", "scope": "full", "proposal_status": "accepted", "proposal_line_ids": [ "ol_92b3c4d5e6", "ol_93c4d5e6f7" ], "order_ids": [ "ord_5e1a2b3c4d" ], "change_seq": 184329 } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } }, "exchange.proposal.rejected": { "post": { "summary": "КП отклонено покупателем (exchange.proposal.rejected)", "description": "Продавцу: итоговый статус КП — rejected или partial, если часть уже куплена. После отклонения можно прислать новое КП, если проходит лимит. Конверт, заголовки, подпись и повторы — как у доставки события выше.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "id": "evt_01J8Z6A1B2C3", "type": "exchange.proposal.rejected", "created_at": "2026-09-22T08:02:10.000Z", "env": "live", "api_version": "1", "data": { "role": "seller", "proposal_id": "o_6a7b8c9d0e", "exchange_request_id": "r_8c1d2e3f4a", "number": "ТТ-014-00132", "proposal_status": "rejected", "change_seq": 184335 } } } } }, "responses": { "200": { "description": "Любой 2xx за 10 с — доставлено; иначе повтор по расписанию F.10" } } } } }, "x-changelog": [ { "version": "1.7.0", "date": "2026-10-16", "changes": [ "Поиск покупателя (GET /buyer/search) в два шага: сначала «что нашлось по номеру», затем предложения выбранной пары и аналоги.", "Ответ mode: brands: у каждой пары новые поля article (номер, как его пишут продавцы) и article_norm (нормализованный номер пары); второй шаг — ?article=&brand_id=.", "Новый необязательный параметр similar=1: в ответе mode: brands ещё список similar — похожие номера (начинаются с введённого после нормализации), до 30 пар; больше — предупреждение SIMILAR_TRUNCATED в warnings. С mode=auto список приходит и при одном бренде, если похожие номера есть.", "Второй шаг (brand_id одного бренда): в группах analog — и аналоги, которые прислали поставщики площадки (продавец — К-247, город склада, срок; поставщик не называется).", "Прежние запросы и ответы не меняются: без similar ответы те же, новые поля — дополнительные." ] }, { "version": "1.6.0", "date": "2026-10-13", "changes": [ "Гарантия на позицию: два новых необязательных поля — warranty_months (срок в месяцах, 1–120; null — срок не указан, действует гарантия по условиям площадки) и warranty_manufacturer (true — гарантия изготовителя детали, false — гарантия продавца). Свободного текста гарантии нет.", "Продавец: поля принимает POST /seller/offers/batch (null в warranty_months снимает срок, поля нет — срок не меняется) и отдаёт GET /seller/offers; правка гарантии меняет change_seq позиции. В файлах прайса — колонки «Гарантия» (число месяцев или текст: «24 мес.», «2 года») и «Гарантия изготовителя» (да / нет); поля есть в GET /dictionary/fields. Неверное значение в offers/batch — код строки WARRANTY_INVALID, строка не записывается. В файле прайса гарантия — необязательное сведение: неразобранное значение («есть», «нет», «0», «14 дней») строку не отклоняет — она принимается без срока гарантии с предупреждением WARRANTY_IGNORED в errors отчёта импорта, число таких строк — counters.warranty_ignored (оба кода — новые в перечне BatchRowCode).", "Биржа: поля принимают строки КП (POST /seller/exchange/requests/{id}/proposals — отправка и черновик) и отдают строки КП продавцу и покупателю (lines[].warranty_months, lines[].warranty_manufacturer).", "Покупатель: поля есть в предложениях GET /buyer/search и в заменах отказанной позиции заказа.", "Строки заказа продавца и покупателя (lines[]) несут warranty_months и warranty_manufacturer — гарантию позиции на момент заказа.", "Прежние запросы и ответы не меняются: поля необязательные, у позиций без срока — null и false." ] }, { "version": "1.5.2", "date": "2026-10-12", "changes": [ "Справочник биржи (GET /dictionary/exchange): max_proposals.cabinet — [0] (было [0, 3, 5, 10]). Форма заявки в кабинете лимит числа КП больше не задаёт — новая заявка кабинета идёт без лимита. API принимает max_proposals 0–50, как раньше; лимит прежних заявок сохраняется.", "Срок заявки today: если заявка создана (или сохранена правкой с deadline) меньше чем за час до конца суток по Москве, expires_at — 23:59:59 следующего дня. Раньше такая заявка закрывалась через минуты, а созданная в последнюю секунду суток сразу была просроченной. В остальное время today — до конца текущего дня, как раньше; days_2_3 и week не менялись. Форма кабинета теперь создаёт заявки со сроком days_2_3.", "«Принять» (POST /buyer/exchange/proposals/{id}/accept) без delivery.address по заявке с самовывозом (pickup: pickup или delivery.type: pickup): адрес заказа — пункт самовывоза площадки строкой «самовывоз, <адрес площадки>», как при оформлении корзины на сайте. Раньше в заказ записывался адрес компании покупателя; он остаётся, если адрес площадки не указан. Заказ продавцу отдаётся с тем же адресом.", "Покупателю в кабинете — уведомление, когда срок заявки истёк, а по ней были действующие КП или строки в корзине. Вебхук exchange.request.closed (reason expired) не менялся." ] }, { "version": "1.5.1", "date": "2026-10-10", "changes": [ "Заказ покупателя (GET /buyer/orders и GET /buyer/orders/{id}): documents.upd — пустая строка, пока заказ не отгружен (статус shipped, closed или return), даже если продавец выписал УПД заранее. Раньше номер УПД, выписанного до отгрузки, покупатель видел сразу. В кабинете покупателя правило то же: УПД появляется после отгрузки.", "Заказ покупателя: documents.ksf — пустая строка, пока по заказу нет согласованного возврата (одобренный возврат товара или возврат денег по претензии), а также у заказа без НДС и у покупателя-физлица. После согласования — номер корректировочного счёта-фактуры заказа: «КСФ-<номер заказа>-1» при одном согласованном возврате, сводный «КСФ-<номер заказа>» при нескольких. Раньше поле показывало номер, который можно было «выписать» по любому заказу.", "Заказ продавца (GET /seller/orders, GET /seller/orders/{id}): documents.upd — как раньше (продавец выписывает УПД и до отгрузки); documents.ksf записывается при согласовании возврата тем же номером, что видит покупатель. Формат полей не менялся." ] }, { "version": "1.5.0", "date": "2026-10-06", "changes": [ "«Принять» (POST /buyer/exchange/proposals/{id}/accept) без delivery.address: адрес доставки заказа — адрес получения заявки pickup_address; при самовывозе и пустом адресе заявки — адрес компании, как раньше. Раньше pickup_address в заказ не переносился.", "Программе продавца способ доставки заявки — только из справочника: значение вне справочника (так попадал адрес покупателя из классической формы кабинета) отдаётся как delivery = null и пустой delivery_name. Адрес покупателя продавец видит только в заказе — и в API, и в кабинете.", "Группа техники «Иное»: новое значение vehicle.vgroup = other (в справочнике /dictionary/exchange — последней, markets: false) — во входе и выдаче заявки, в параметре vgroup ленты продавца и в данных exchange.request.created. Программы с жёсткой проверкой перечисления должны принять новое значение. У other рынок не сохраняется.", "Заявка группы «Иное» проходит любой фильтр продавца: параметры vgroup и market ленты GET /seller/exchange/requests и фильтр подписки options.groups / options.markets. Легковые и грузовые без рынка (рынок «Иное», market = null) проходят любой фильтр market. options.groups = [\"other\"] — 400 VALIDATION_FAILED.", "Смена биржи заявки: POST /buyer/exchange/requests/{id}/update принимает exchange (new, used, all; раньше — 400). Расширить можно всегда — продавцам, которым заявка стала видна, уходит exchange.request.created. Сузить нельзя, пока у продавцов, которые потеряют доступ, есть действующие КП: 409 INVALID_STATE с details[0].field = exchange; черновики таких продавцов закрываются.", "Новые сроки строки КП: term = hours_3 (через 3 часа, term_days 0), tomorrow_am (завтра с утра, 1), week (через неделю, 7) — во входе POST /seller/exchange/requests/{id}/proposals, в ProposalLine у продавца и покупателя, в справочнике /dictionary/exchange (terms, по порядку списка формы). Прежние коды и подписи (in_stock, days_2_3 «2-3 дня», days_4_5 «4-5 дней», on_order) не изменились; без term код из term_days выводится, как раньше. Программы с жёсткой проверкой перечисления должны принять новые значения.", "availability строки КП: in_stock — только у term = in_stock (у other — при term_days = 0). Раньше in_stock давал и term_days = 0 при любом коде; hours_3 (0 дней) — on_order.", "Артикул и оригинальный номер продавца покупателю до покупки не раскрываются: в КП программе покупателя (GET /buyer/exchange/proposals и /proposals/{id}, ответ reject) article и oem — пустые строки, тип полей прежний. После заказа оба есть в строках заказа (ответ accept, GET /buyer/orders) и в УПД: новое поле oem в строке заказа покупателя (BuyerOrderLine и строки заказа ответа accept) — оригинальный номер строки КП, у строк витрины — пустая строка. Программе продавца его КП — как раньше." ] }, { "version": "1.4.2", "date": "2026-09-28", "changes": [ "Пределы песочницы на компанию: в тестовом заказе покупателя — не больше 20 позиций (400 VALIDATION_FAILED); тестовых заказов — не больше 50 действующих (409 LIMIT_EXCEEDED) и 200 за сутки (429 RATE_LIMITED с Retry-After); тестовых заявок биржи — не больше 100 за сутки (429 RATE_LIMITED). Тестовые заказы удаляются через exchangeTestRetentionDays (7 дней) после создания.", "Новая причина остановки загрузки held_reason: EMAIL_SENDER_UNVERIFIED — письмо в источник «почта» без указанного отправителя, отправитель не подтверждён (DMARC не pass); value и limit — null. Загрузка ждёт утверждения, как при других причинах." ] }, { "version": "1.4.1", "date": "2026-09-23", "changes": [ "Склад в строках заказа покупателя — город и обезличенный код warehouse_code («ТТ-014-2»); текст склада продавца покупателю не отдаётся.", "В текстах КП нельзя передавать и сведения о продавце: реквизиты, название, адрес, фамилии сотрудников — 422 CONTACTS_FORBIDDEN, в details[].kind — requisites, company или person; в старых записях — «[скрыто]».", "В текстах КП нельзя предлагать расчёты мимо площадки («платите напрямую продавцу», «минуя площадку», «переведите на карту») — 422 CONTACTS_FORBIDDEN, в details[].kind — bypass; в старых записях покупателю всё предложение показывается как «[скрыто]». Тексты КП покупателю очищаются с профилем продавца КП: его название, адрес складов и фамилии сотрудников скрыты и в старых записях.", "Заказы покупателя: экспресс через delivery.type: express, комментарий заказа comment до 500 символов, payment — код или подпись; accounting_total_rub — число (total_kop / 100).", "Idempotency-Key: прежний объект возвращается повтором, только пока он моложе срока хранения ключа (24 ч) и создан той же операцией; позже тот же ключ — новый запрос.", "ping: capabilities.exchange.enabled — включена ли биржа; заголовки X-RateLimit-* и в ответах 403, 404 и 405 с ключом; тело не в UTF-8 — 400 BAD_REQUEST.", "Вебхуки автовладельцу недоступны (403 FORBIDDEN_ROLE); в WebhookEnvelope.type перечислены события биржи.", "POST /buyer/orders тестовым ключом считается по классу лимита default (x-rate-limit-class-test): второй тестовый заказ подряд больше не получает 429; боевой ключ — bulk, как раньше.", "Описаны: mode поиска при одном бренде, адрес доставки заказа при «Принять» (delivery.address, без него — адрес компании; pickup_address заявки в заказ не переносится)." ] }, { "version": "1.4.0", "date": "2026-09-23", "changes": [ "Биржа для программы покупателя-организации: создание, правка и снятие заявки, список и одна заявка, КП по заявкам, «Принять» целиком и по строкам, отклонение КП.", "Заказы покупателя: перепроверка условий POST /buyer/quotes, оформление POST /buyer/orders, список и один заказ (заказы магазина и из КП, фильтр source).", "Вебхуки покупателю: exchange.proposal.received, exchange.proposal.replaced, exchange.proposal.withdrawn, exchange.request.closed и order.* по его заказам.", "Песочница покупателя: sandbox.scenario в заявке (standard, two_sellers, withdraw, no_answer, expire) — роботы-продавцы отвечают КП; робот 5B подтверждает, отклоняет строку с qty = 13 и отгружает тестовые заказы.", "Каждое событие доставки описано отдельной записью в x-webhooks: назначение, кому приходит и пример конверта с data.", "Страница подключения public/api.html: разделы «Биржа: программа продавца», «Биржа: программа покупателя», «Заказы покупателя» и «Песочница биржи» с пошаговыми сценариями." ] }, { "version": "1.3.0", "date": "2026-09-22", "changes": [ "Биржа для программы продавца: лента заявок, КП и черновики, снятие КП, синхронизация по since_seq; справочник /dictionary/exchange.", "Право ключа exchange и регион заявок ключа (own, all); ключ отключённого сотрудника — 401 KEY_OWNER_INACTIVE.", "Заказы из КП в /seller/orders: source, exchange, actions, buyer.ref; confirm и reject — 409 EXCHANGE_ORDER; ship — как раньше.", "Вебхуки биржи exchange.request.* и exchange.proposal.*, шаблоны order.*, import.*, exchange.*, фильтр заявок options; «*» событий биржи не включает.", "Песочница биржи: POST /sandbox/exchange/requests — тестовая заявка робота-покупателя со сценарием.", "Юридические ворота: прайс, пакет предложений, утверждение загрузки и КП боевым ключом — после принятия документов площадки (403 LEGAL_NEEDS)." ] }, { "version": "1.2.0", "date": "2026-09-17", "changes": [ "Вебхуки: подписка методами /webhooks и в кабинете, подпись HMAC, повторы 7 раз за сутки, проверочное событие ping.", "Код ошибки LIMIT_EXCEEDED (409) — предел подписок.", "В следующем обновлении: перепроверка цен и заказы покупателя через API." ] }, { "version": "1.1.0", "date": "2026-09-16", "changes": [ "Первая публикация API v1: прайсы файлом, пакет предложений, склады, загрузки и их проверка.", "Заказы продавца с подтверждением по строкам, отказом и отгрузкой; синхронизация по since_seq.", "Поиск покупателя, песочница с тестовыми ключами.", "В следующем обновлении: вебхуки, перепроверка цен и заказы покупателя через API." ] } ] }