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