@opsregistry/adapter-cdek

Адаптер СДЭК для универсальных логистических операций opsregistry.

Пакет принимает единый формат @opsregistry/contracts и преобразует его в запросы официального API СДЭК. Это позволяет приложению работать с расчетом доставки через одинаковый контракт, даже если у разных транспортных компаний отличаются названия полей, идентификаторы городов и формат ответа.

Возможности

• it.identity.authenticate - OAuth 2.0 Client Credentials, токен кешируется внутри адаптера.
• logistics.shipment.quote - расчет вариантов доставки через /v2/calculator/tarifflist.
• logistics.shipment.create - создание заказа через /v2/orders.
• logistics.shipment.track - статус и история движения через /v2/orders/{uuid} или /v2/orders?cdek_number=....
• Поиск кодов городов СДЭК по названию.
• Несколько грузовых мест в одном расчете.
• Фильтрация тарифов по deliveryMode и serviceCodes.

Источник Документации

Официальная документация СДЭК находится на https://apidoc.cdek.ru/.

Портал загружает OpenAPI-файл для клиентского протокола интеграции с логистикой:

https://gateway.cdek.ru/api-cdek-docs/web/docs/merged?sectionId=api_v2_integration

Локальная копия в репозитории: docs/openapi_api_v2_integration.json.

Сверенный файл:

• OpenAPI: 3.0.1
• title: Клиентский протокол интеграции с логистикой
• version: 1.0.0
• servers: https://api.cdek.ru, https://api.edu.cdek.ru
• paths: 40
• schemas: 188

Карта Операций СДЭК

Уже реализовано в адаптере:

• POST /v2/oauth/token -> it.identity.authenticate
• POST /v2/calculator/tarifflist -> logistics.shipment.quote
• GET /v2/location/cities -> внутренний поиск кода города для расчета
• POST /v2/orders -> logistics.shipment.create
• GET /v2/orders/{uuid} и GET /v2/orders?cdek_number=... -> logistics.shipment.track

Важно: GET /v2/orders в OpenAPI называется «Получение информации о заказе по номеру СДЭК/ИМ» и принимает cdek_number или im_number. Это не журнал заказов личного кабинета и не аналог logistics.shipment.list.

Следующие операции есть в официальном API и должны быть перенесены в универсальные opsregistry-операции:

• PATCH /v2/orders -> изменение отправления
• DELETE /v2/orders/{uuid} -> отмена/удаление отправления
• GET /v2/orders -> получение заказа по номеру СДЭК или номеру ИМ
• POST /v2/intakes -> создание заявки на вызов курьера
• PATCH /v2/intakes -> изменение статуса заявки на вызов курьера
• GET /v2/orders/{orderUuid}/intakes -> заявки на вызов курьера по заказу
• GET /v2/intakes/{uuid} -> получение заявки на вызов курьера
• DELETE /v2/intakes/{uuid} -> удаление заявки на вызов курьера
• POST /v2/delivery -> договоренность о доставке
• GET /v2/delivery/{uuid} -> получение договоренности о доставке
• GET /v2/delivery/intervals и POST /v2/delivery/estimatedIntervals -> интервалы доставки
• POST /v2/print/orders, GET /v2/print/orders/{uuid}, GET /v2/print/orders/{uuid}.pdf -> печать квитанции
• POST /v2/print/barcodes, GET /v2/print/barcodes/{uuid}, GET /v2/print/barcodes/{uuid}.pdf -> печать штрихкодов
• GET /v2/deliverypoints -> список офисов/ПВЗ
• GET /v2/calculator/alltariffs -> список доступных тарифов
• GET /v2/registries -> реестры НП
• POST /v2/orders/{uuid}/refusal -> отказ
• POST /v2/orders/{uuid}/clientReturn -> клиентский возврат
• POST /v2/reverse/availability -> проверка доступности реверса
• POST /v2/photoDocument, GET /v2/photoDocument/{uuid} -> фото документов
• GET /v2/webhooks, POST /v2/webhooks, GET /v2/webhooks/{uuid}, DELETE /v2/webhooks/{uuid} -> вебхуки

Доступ

Расчет СДЭК сейчас работает только через авторизованный API. Для вызовов нужны clientId и clientSecret.

import { createAdapter } from '@opsregistry/adapter-cdek';

const cdek = createAdapter({
	clientId: process.env.CDEK_CLIENT_ID,
	clientSecret: process.env.CDEK_CLIENT_SECRET
});

const quote = await cdek.quoteShipment({
	origin: { city: 'Самара' },
	destination: { city: 'Москва' },
	deliveryMode: 'terminal_terminal',
	packages: [
		{ weightKg: 10, lengthCm: 100, widthCm: 20, heightCm: 20 },
		{ weightKg: 5, lengthCm: 20, widthCm: 20, heightCm: 50 }
	]
});

console.log(quote.options);

Создание ИМ-заказа:

const shipment = await cdek.createShipment({
	customerReference: 'IM-1001',
	origin: { city: 'Самара', facilityId: 'SAM1' },
	destination: { city: 'Москва', facilityId: 'MSK1' },
	sender: { name: 'ООО Отправитель', phone: '+79990000001' },
	recipient: { kind: 'person', name: 'Петр Петров', phone: '+79990000002' },
	deliveryMode: 'terminal_terminal',
	serviceCode: '136',
	packages: [{ weightKg: 10, lengthCm: 100, widthCm: 20, heightCm: 20 }]
});

console.log(shipment.shipmentId, shipment.trackingNumber);

Для терминальных отправлений код ПВЗ можно передавать в facilityId, externalIds.cdekPointCode, externalIds.cdekShipmentPoint или externalIds.cdekDeliveryPoint.

Отслеживание отправления:

const tracking = await cdek.trackShipment({
	shipmentId: 'provider-order-uuid'
});

console.log(tracking.status, tracking.events);

Если код города уже известен, его можно передать без дополнительного поиска:

const origin = {
	city: 'Самара',
	externalIds: { cdekCityCode: '430' }
};

Events / message to next agent — 08.10.2026

Implemented listEventSubscriptions, createEventSubscription, deleteEventSubscription for it.eventSubscription.* and ORDER_STATUS; normalizeCdekNotification maps it to logistics.shipment.statusChanged. Stable event hash uses order UUID + tracking number + status + timestamp + deletion flag, since webhook uuid identifies the ORDER, not the event. Only implemented event types are listed; unrelated subscriptions are never deleted. Create first checks exact type+callback; consumer must still serialize calls. HTTP 200 with INVALID is an error; ACCEPTED is pending. No retry of POST/DELETE after uncertain outcome.

Notification parsing does not authenticate. Consumer must protect callback and read the shipment through the same authenticated account before trusting any status/details. Do not use raw webhook status to mark ERP orders delivered/paid. Tracking returns normalized recipient, phones, destination and customerReference; picks latest timestamp independent of array order.

Official source: https://apidoc.cdek.ru/ and live OpenAPI download documented above, inspected 08.10.2026. Documentation says at most two webhook subscriptions per client; do not delete subscriptions belonging to other software to make room. No account-wide order history API. Tracing does not solve discovery of unknown waybill numbers. LK/office webhook coverage remains unverified. Next live check: receive a status change for a known office/LK waybill and verify identifiers via GET order. Old shipments can be imported by explicit waybill number.

Next: publish compatible contracts first, then adapter, update consumer locks; deploy receiver before registration. Real registration/deletion requires consumer authorization. Remaining operations are listed above (pickup, changes/cancellation, printing, etc.); implement only verified provider capabilities, preserving unknown outcomes and data ownership. No polling-list support should be advertised for CDEK. Telephony and other carriers remain separate subsequent tasks.

Terminal and pickup-point discovery

adapter.listFacilities({ city: 'Самара', purpose: 'delivery', pageSize: 20 }) implements logistics.facility.list from @opsregistry/contracts 0.26.0. The result contains compact items, warnings and an optional opaque nextPageToken. Continue with the same filters and page size. A changed catalog invalidates continuation. This is a read operation, not a booking or a quote. No raw provider response or authentication material is returned.

Uses GET /v2/location/cities and GET /v2/deliverypoints. Exact same-name cities are retained with their actual region/country; use region/countryCode/providerCityId to narrow the search. Uses office code as facilityId, respects closed points and reception/handout flags. Provider dimensions are already cm.

Capabilities can be null; never treat that as permission. Selection is explicit, and IDs must stay bound to this provider. Cargo/tariff eligibility requires a separate quote/booking check. serviceCode filters only explicitly reported per-service capabilities; it does not guess support when absent.

Official source: https://apidoc.cdek.ru/