Russian Post API Library

Security Notice: Never publish your real API tokens or keys in public repositories, code examples, or documentation. Always use placeholders like YOUR_TOKEN and YOUR_KEY.

A TypeScript library for interacting with the Russian Post API (otpravka.pochta.ru). This library provides a simple and type-safe way to work with the Russian Post delivery service.

• Repository: github.com/barsbay/pochta-rossii-api-lib
• NPM: npmjs.com/package/pochta-rossii-api-lib
• Issues: github.com/barsbay/pochta-rossii-api-lib/issues
• License: MIT
• Author: barsbay

📋 Основные возможности

🔐 Авторизация

• Поддержка токенов доступа
• Базовая HTTP авторизация
• Автоматическая обработка заголовков

📮 Заказы

• Создание заказов
• Получение списка заказов
• Поиск заказа по ID
• Обновление заказов
• Удаление заказов
• Перевод в отложенные

📦 Партии

• Создание партий
• Получение списка партий
• Поиск партий по названию
• Обновление даты отправки
• Добавление/удаление заказов из партии

💰 Расчет тарифов

• Расчет стоимости доставки
• Учет веса, категории и типа отправления
• Поддержка объявленной ценности
• Расчет НДС

🏠 Нормализация адресов

• Проверка и нормализация адресов
• Нормализация ФИО
• Нормализация телефонных номеров

🏪 Поиск отделений

• Поиск по координатам
• Поиск по адресу
• Поиск по индексу
• Получение информации о режиме работы

📖 Подробное руководство

🔧 Настройка

Создайте файл .env в корне проекта:

AUTHORIZATION=your-access-token
X_USER_AUTHORIZATION=Basic your-base64-credentials

📮 Работа с заказами

Создание заказа

import { PochtaRossiiApi } from 'pochta-rossii-api-lib';

// Инициализация API клиента
const api = new PochtaRossiiApi({
  Authorization: 'your-access-token',
  'X-User-Authorization': 'Basic your-base64-credentials'
});

// Пример создания заказа
const order = {
  'address-type-to': 'DEFAULT',
  'given-name': 'Иван',
  'mail-category': 'ORDINARY',
  'mail-type': 'POSTAL_PARCEL',
  mass: 1000,
  'order-num': '12345',
  'recipient-name': 'Иванов Иван Иванович',
  'str-index-to': '101000',
  'tel-address': '+79001234567',
  'index-to': 101000,
  'region-to': 'Москва',
  'place-to': 'Москва',
  'street-to': 'Красная площадь',
  'house-to': '1'
};

const createdOrder = await api.createOrder(order);

Получение заказов

// Получить все заказы
const orders = await api.getOrders();

// Получить заказ по ID
const order = await api.getOrderById('12345');

Обновление заказа

const updatedOrder = await api.updateOrder('12345', {
  ...order,
  mass: 1500
});

Удаление заказа

await api.deleteOrder('12345');

📦 Работа с партиями

Создание партии

const batch = {
  'batch-name': 'Партия №1',
  'sending-date': '2024-01-15',
  'shipment-point-index': '101000'
};

const createdBatch = await api.createBatch(batch);

Получение партий

// Получить все партии
const batches = await api.getBatches();

// Поиск партии по названию
const foundBatches = await api.searchBatchByName('Партия');

Обновление даты отправки

await api.updateBatchSendingDate('batch-id', '2024-01-20');

💰 Расчет тарифов

const tariffRequest = {
  'index-from': 101000, // Москва
  'index-to': 190000,   // Санкт-Петербург
  'mail-category': 'ORDINARY',
  'mail-type': 'POSTAL_PARCEL',
  mass: 1000,
  fragile: false,
  'with-order-of-notice': false,
  'with-simple-notice': false,
  'with-declared-value': false,
  'declared-value': 0
};

const tariff = await api.calculateTariff(tariffRequest);
console.log(`Стоимость доставки: ${(tariff['total-rate'] / 100).toFixed(2)} ₽`);
console.log(`Срок доставки: ${tariff['delivery-time'].min}-${tariff['delivery-time'].max} дней`);

Примечание: API возвращает стоимость в копейках, поэтому для отображения в рублях нужно разделить на 100.

Типы отправлений (mail-type):

• POSTAL_PARCEL - Посылка (до 20 кг, размеры до 120 см)
• ONLINE_PARCEL - Посылка онлайн (до 2 кг, доставка до двери или ПВЗ)
• ONLINE_COURIER - Курьер онлайн (до 30 кг, доставка курьером)
• EMS - EMS (до 31.5 кг, экспресс-доставка)
• EMS_OPTIMAL - EMS оптимальный (до 31.5 кг, экономичная экспресс-доставка)
• LETTER - Письмо (до 100 г, размеры до 229x324 мм)
• BANDEROL - Бандероль (до 2 кг, печатные издания)

Категории отправлений (mail-category):

• SIMPLE - Простое отправление (без уведомления о вручении)
• ORDINARY - Обыкновенное отправление (с уведомлением о вручении)
• REGISTERED - Заказное отправление (с уведомлением о вручении и описью вложения)
• WITH_DECLARED_VALUE - Отправление с объявленной ценностью

🏠 Нормализация адресов

// Нормализация адреса
const addressRequest = {
  id: '1',
  'original-address': 'Москва, Красная площадь, 1'
};

const normalizedAddress = await api.normalizeAddress(addressRequest);

// Нормализация ФИО
const fioRequest = {
  id: '2',
  'original-fio': 'Иванов Иван Иванович'
};

const normalizedFio = await api.normalizeFio(fioRequest);

// Нормализация телефона
const phoneRequest = {
  id: '3',
  'original-phone': '+7 900 123 45 67'
};

const normalizedPhone = await api.normalizePhone(phoneRequest);

🏪 Поиск отделений

Поиск по координатам

const coordinatesRequest = {
  latitude: 55.7558,
  longitude: 37.6176,
  radius: 2000, // 2 км
  filter: 'ALL'
};

const offices = await api.searchPostOfficesByCoordinates(coordinatesRequest);

Поиск по адресу

const addressRequest = {
  address: 'Москва, Красная площадь',
  top: 10
};

const offices = await api.searchPostOfficesByAddress(addressRequest);

Поиск по индексу

const indexRequest = {
  index: '101000'
};

const offices = await api.searchPostOfficesByIndex(indexRequest);

Получение всех отделений

const offices = await api.getPostOffices(100); // ограничение 100

🔧 Типы данных

Order (Заказ)

interface Order {
  'address-type-to': string;
  'given-name': string;
  'mail-category': 'SIMPLE' | 'ORDINARY' | 'REGISTERED' | 'WITH_DECLARED_VALUE';
  'mail-type': 'POSTAL_PARCEL' | 'ONLINE_PARCEL' | 'ONLINE_COURIER' | 'EMS' | 'EMS_OPTIMAL' | 'LETTER' | 'BANDEROL';
  mass: number;
  'order-num': string;
  'recipient-name': string;
  'str-index-to': string;
  'tel-address': string;
  'index-to': number;
  'region-to': string;
  'place-to': string;
  'street-to': string;
  'house-to': string;
  // Опциональные поля...
}

Batch (Партия)

interface Batch {
  'batch-name': string;
  'sending-date': string;
  'shipment-point-index': string;
}

TariffRequest (Запрос на расчет тарифа)

interface TariffRequest {
  'index-from': number;
  'index-to': number;
  'mail-category': 'SIMPLE' | 'ORDINARY' | 'REGISTERED' | 'WITH_DECLARED_VALUE';
  'mail-type': 'POSTAL_PARCEL' | 'ONLINE_PARCEL' | 'ONLINE_COURIER' | 'EMS' | 'EMS_OPTIMAL' | 'LETTER' | 'BANDEROL';
  mass: number;
  fragile: boolean;
  'with-order-of-notice': boolean;
  'with-simple-notice': boolean;
  'with-declared-value': boolean;
  'declared-value': number;
}

PostOffice (Отделение почты)

interface PostOffice {
  'address-source'?: string;
  distance?: number;
  'is-closed'?: boolean;
  'is-private-category'?: boolean;
  'is-temporary-closed'?: boolean;
  latitude?: number;
  longitude?: number;
  'postal-code'?: string;
  region?: string;
  settlement?: string;
  'type-code'?: string;
  'type-id'?: number;
  'working-hours'?: Array<{
    day: number;
    hours: string;
  }>;
  'works-on-saturdays'?: boolean;
  'works-on-sundays'?: boolean;
  phones?: Array<{
    number: string;
    type: string;
  }>;
  'service-groups'?: Array<{
    name: string;
    code: string;
  }>;
}

📦 Установка

npm install pochta-rossii-api-lib

🚀 Быстрый старт

import { PochtaRossiiApi } from 'pochta-rossii-api-lib';

// Инициализация API клиента
const api = new PochtaRossiiApi({
  Authorization: 'your-access-token',
  'X-User-Authorization': 'Basic your-base64-credentials'
});

// Пример создания заказа
const order = {
  'address-type-to': 'DEFAULT',
  'given-name': 'Иван',
  'mail-category': 'ORDINARY',
  'mail-type': 'POSTAL_PARCEL',
  mass: 1000,
  'order-num': '12345',
  'recipient-name': 'Иванов Иван Иванович',
  'str-index-to': '101000',
  'tel-address': '+79001234567',
  'index-to': 101000,
  'region-to': 'Москва',
  'place-to': 'Москва',
  'street-to': 'Красная площадь',
  'house-to': '1'
};

const createdOrder = await api.createOrder(order);

📚 Примеры использования

Запуск примеров

# Основной пример с расчетом тарифа и нормализацией
npm run example

# Поиск отделений по координатам
npm run coordinates

# Поиск отделений по адресу и индексу
npm run postoffice

# Тестирование работы с заказами
npm run orders

# Подробный пример расчета тарифов
npm run tariff

Примеры кода

Смотрите папку examples/ для полных примеров:

• real-usage.ts - Основной пример с расчетом тарифа и нормализацией
• tariff-calculation.ts - Подробный пример расчета тарифов с комментариями
• coordinates-test.ts - Поиск отделений по координатам
• postoffice-search.ts - Поиск отделений по адресу и индексу
• orders-test.ts - Тестирование работы с заказами

Development

Prerequisites

• Node.js 14+
• npm or yarn

Setup

# Install dependencies
npm install

# Run tests
npm test

# Build the library
npm run build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

If you encounter any issues or have questions, please open an issue in the GitHub repository.