cdek-simple-api

Node.js клиент для работы с API СДЭК v2.

• Города, регионы, пункты выдачи
• Расчёт стоимости и сроков доставки
• Заказы, курьерский забор, расписание доставки
• Документы (квитанции, штрихкоды)
• Вебхуки и финансы (реестр наложенных платежей)

Требования

Node.js >= 18

Установка

npm install cdek-simple-api

Инициализация

import { createClient } from "cdek-simple-api";

const cdek = createClient({
  clientId: "your_client_id",
  clientSecret: "your_client_secret",
});

Credentials выдаются СДЭК при подключении к API. Обычный логин/пароль не подходят.

Параметры createClient

Параметр	Тип	По умолчанию	Описание
clientId	string	—	Client ID из личного кабинета СДЭК
clientSecret	string	—	Client Secret из личного кабинета СДЭК
baseUrl	string	https://api.cdek.ru/v2	URL API. Для тестовой среды: https://api.edu.cdek.ru/v2
retries	number	3	Количество повторных попыток при сетевых ошибках и 5xx
retryDelay	number	500	Начальная задержка (мс) между попытками, удваивается
requestsPerSecond	number	без ограничений	Максимальное количество запросов в секунду

---

Локации

getCities(countryCode)

Возвращает все населённые пункты страны, где есть подразделения СДЭК. Автоматически обходит все страницы.

const cities = await cdek.getCities("RU");
// [{ code: 44, city: "Москва", region: "Москва", country_code: "RU", ... }, ...]

getRegions(query?)

Возвращает список регионов. Без параметров — все регионы из базы СДЭК.

const regions = await cdek.getRegions({ countryCode: "RU", regionCode: 66 });
// [{ region: "Свердловская", region_code: 66, country_code: "RU", ... }]

Параметр	Тип	Описание
query.countryCode	string	Код страны ISO 3166-1
query.regionCode	number	Код региона СДЭК
query.size	number	Размер страницы
query.page	number	Номер страницы

getPickupPoints(query, filters?)

Возвращает пункты выдачи и постаматы. Автоматически обходит все страницы.

const points = await cdek.getPickupPoints({ cityCode: 44 });

// Только постаматы с наложенным платежом
const postamats = await cdek.getPickupPoints(
  { cityCode: 44 },
  { type: "POSTAMAT", allowedCod: true }
);

Параметры запроса (query):

Параметр	Тип	Описание
cityCode	number	Код города СДЭК (поле code из getCities)
countryCode	string	Код страны ISO 3166-1
regionCode	number	Код региона
postalCode	string	Почтовый индекс

Фильтры (filters):

Параметр	Тип	Описание
type	"PVZ" | "POSTAMAT"	Тип пункта
allowedCod	boolean	Только с наложенным платежом
isDressingRoom	boolean	Только с примерочной
weightMax	number	Максимальный вес (граммы)

---

Расчёт доставки

calculateDelivery(params)

Рассчитывает стоимость и сроки по всем доступным тарифам.

const result = await cdek.calculateDelivery({
  fromCityCode: 44,  // Москва
  toCityCode: 270,   // Новосибирск
  packages: [{ weight: 2000, length: 30, width: 20, height: 10 }],
});

console.log(result.tariffs);  // все тарифы
console.log(result.cheapest); // самый дешёвый
console.log(result.fastest);  // самый быстрый
console.log(result.expensive);// самый дорогой
console.log(result.slowest);  // самый медленный

Параметр	Тип	Описание
fromCityCode	number	Код города отправления
toCityCode	number	Код города назначения
packages	Package[]	Массив посылок
packages[].weight	number	Вес в граммах
packages[].length	number	Длина в сантиметрах
packages[].width	number	Ширина в сантиметрах
packages[].height	number	Высота в сантиметрах
currency	number	Код валюты (по умолчанию 1 — RUB)

Каждый Tariff содержит:

Поле	Тип	Описание
tariffCode	number	Код тарифа
tariffName	string	Название тарифа
tariffDescription	string	Описание
deliverySum	number	Стоимость доставки
periodMin	number	Минимальный срок (дней)
periodMax	number	Максимальный срок (дней)

calculateDeliveryByTariff(params)

Рассчитывает стоимость для конкретного тарифа с учётом доп. услуг.

const result = await cdek.calculateDeliveryByTariff({
  tariffCode: 136,
  fromCityCode: 44,
  toCityCode: 270,
  packages: [{ weight: 2000, length: 30, width: 20, height: 10 }],
});
// { deliverySum, totalSum, periodMin, periodMax, weightCalc, services }

---

Заказы

createOrder(params)

const result = await cdek.createOrder({
  tariff_code: 136,
  shipment_point: "MSK1",   // код ПВЗ отправления (для тарифов склад-склад)
  delivery_point: "NSK1",   // код ПВЗ получения
  recipient: {
    name: "Иван Иванов",
    phones: [{ number: "+79991234567" }],
  },
  packages: [{
    number: "pkg-1",
    weight: 500,
    length: 20,
    width: 15,
    height: 10,
    items: [{
      name: "Товар",
      ware_key: "item-1",
      payment: { value: 0 },
      cost: 100,
      weight: 500,
      amount: 1,
    }],
  }],
});

console.log(result.entity.uuid); // UUID созданного заказа

getOrder(identifier, type?)

const order = await cdek.getOrder("uuid-заказа");
// type: "uuid" (по умолчанию) | "cdek_number" | "im_number"

updateOrder(params)

await cdek.updateOrder({ uuid: "uuid-заказа", comment: "Новый комментарий" });

deleteOrder(uuid)

const result = await cdek.deleteOrder("uuid-заказа");

---

Курьерский забор

createCourierPickup(params)

Создаёт заявку на вызов курьера.

const result = await cdek.createCourierPickup({
  intake_date: "2024-01-15",
  intake_time_from: "09:00",
  intake_time_to: "18:00",
  name: "Иван Иванов",
  weight: 2000,
  from_location: { city: "Москва", address: "ул. Ленина, 1" },
});

getCourierPickup(uuid)

const pickup = await cdek.getCourierPickup("uuid-заявки");

deleteCourierPickup(uuid)

await cdek.deleteCourierPickup("uuid-заявки");

---

Расписание доставки

getDeliveryIntervals(orderUuid)

Возвращает доступные интервалы доставки для согласования с получателем.

const intervals = await cdek.getDeliveryIntervals("uuid-заказа");
// [{ date: "2024-01-15", time_from: "09:00", time_to: "13:00" }, ...]

scheduleDelivery(params)

await cdek.scheduleDelivery({
  uuid: "uuid-заказа",
  date: "2024-01-15",
  time_from: "09:00",
  time_to: "13:00",
});

---

Документы

Формирование документов — асинхронный процесс. Сначала создаётся задание, затем проверяется статус, затем скачивается файл.

Квитанция

const { entity } = await cdek.createOrderReceipt({
  orders: [{ order_uuid: "uuid-заказа" }],
});

// Ждём готовности
const status = await cdek.getOrderReceiptStatus(entity.uuid);

// Скачиваем PDF
const buffer = await cdek.downloadOrderReceipt(entity.uuid);

Штрихкод

const { entity } = await cdek.createBarcode({
  orders: [{ order_uuid: "uuid-заказа" }],
  format: "A6",
});

const status = await cdek.getBarcodeStatus(entity.uuid);
const buffer = await cdek.downloadBarcode(entity.uuid);

---

Вебхуки

Регистрация и управление

// Зарегистрировать
const result = await cdek.addWebhook({
  url: "https://example.com/webhook",
  type: "ORDER_STATUS",
});

// Список
const webhooks = await cdek.getWebhooks();

// Удалить
await cdek.deleteWebhook("uuid-вебхука");

Доступные типы событий: ORDER_STATUS, PRINT_FORM, PREALERT_CLOSED, ACCOMPANYING_WAYBILL, OFFICE_AVAILABILITY, ORDER_MODIFIED, DELIV_AGREEMENT, DELIV_PROBLEM.

Обработчик входящих вебхуков

const handler = cdek.createWebhookHandler({
  ORDER_STATUS: (event) => console.log(event.attributes),
  PRINT_FORM: (event) => console.log(event),
});

// Express
app.post("/webhook", express.text(), (req, res) => {
  handler.handle(req.body).then(() => res.json({ result: "OK" }));
});

---

Финансы

getCodRegistry(params)

Реестр наложенных платежей за период.

const registry = await cdek.getCodRegistry({
  dateFirst: "2024-01-01",
  dateLast: "2024-01-31",
});

getCodTransfer(id)

Информация о конкретном перечислении.

const transfer = await cdek.getCodTransfer("id-перечисления");

---

Обработка ошибок

import { createClient, CdekApiError, CdekAuthError, CdekHttpError } from "cdek-simple-api";

try {
  await cdek.createOrder({ ... });
} catch (err) {
  if (err instanceof CdekApiError) {
    // Ошибка API: 4xx/5xx от СДЭК
    console.log(err.status, err.body);
  } else if (err instanceof CdekAuthError) {
    // Ошибка авторизации (неверные credentials)
    console.log(err.message);
  } else if (err instanceof CdekHttpError) {
    // Сетевая ошибка (нет соединения и т.п.)
    console.log(err.cause);
  }
}

---

Разработка

npm test                    # unit-тесты (vitest)
npm run test:integration    # интеграционные тесты (реальный тестовый API СДЭК)
npm run build               # сборка в dist/

Библиотека поставляется как dual CJS/ESM пакет без внешних зависимостей (использует встроенный fetch из Node.js ≥ 18).

Лицензия

MIT