@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' }
};

logistics.shipment.create пока не реализована.