0.3.1 • Published 3 months ago

saferoute-api v0.3.1

Weekly downloads
-
License
ISC
Repository
-
Last release
3 months ago

Пакет для работы с API SafeRoute.

Документация к API

Установка

NPM

npm i saferoute-api

Yarn

yarn add saferoute-api

Работа с API

Описание типов APIDataResponse и APIBoolResponse

APIDataResponse

Тип для запросов, в которых сервер возвращает какие-либо данные без постраничной навигации.

type APIDataResponse<D> =
  // Получен успешный ответ от сервера
  | {
      status: SuccessStatuses; // HTTP-статус ответа сервера
      data: D; // Полученные данные
      error: null;
    }
  // От сервера получены код и текстовое описание ошибки
  | {
      status: ErrorWithCodeStatuses;
      data: null;
      error: {
        code: ERROR_CODES;
        message: string;
      };
    }
  // Запрос завершился ошибкой, сервер не отдал код ошибки
  | {
      status: ErrorWithoutCodeStatuses;
      data: null;
      error: null;
    };

APIDataPaginatedResponse

Тип для запросов, в которых сервер возвращает список с постраничной навигацией.

type APIDataPaginatedResponse<D> =
  // Получен успешный ответ от сервера
  | {
      status: SuccessStatuses; // HTTP-статус ответа сервера
      data: D[]; // Полученный список
      pagination: {
        currentPage: number; // Текущая запрошенная страница
        pageCount: number; // Общее количество страниц в текущем списке
        perPage: number; // Количество выводимых на страницу результатов
        totalCount: number; // Общее количество результатов в списке
      };
      error: null;
    }
  // От сервера получены код и текстовое описание ошибки
  | {
      status: ErrorWithCodeStatuses;
      data: null;
      pagination: null;
      error: {
        code: ERROR_CODES;
        message: string;
      };
    }
  // Запрос завершился ошибкой, сервер не отдал код ошибки
  | {
      status: ErrorWithoutCodeStatuses;
      data: null;
      pagination: null;
      error: null;
    };

APIBoolResponse

Тип для запросов, в которых требуется вернуть результат выполнения запроса "успешно" / "не успешно".

type APIBoolResponse =
  // Успешное выполнение запроса
  | {
      status: SuccessStatuses;
      success: true;
      error: null;
    }
  // Неуспешное выполнение запроса с кодом ошибки
  | {
      status: ErrorWithCodeStatuses;
      success: false;
      error: {
        code: ERROR_CODES;
        message: string;
      };
    }
  // Неуспешное выполнение запроса без кода ошибки
  | {
      status: ErrorWithoutCodeStatuses;
      success: false;
      error: null;
    };

Авторизация, профиль и настройки

Авторизация по E-mail и паролю

В разработке

Получение данных и настроек пользователя по токену

В разработке

Калькулятор доставки

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

В разработке

Расчёт стоимости доставки для отдельной транспортной компании

В разработке

Получение списка ID транспортных компаний, доставка которыми доступна в выбранный населённый пункт

В разработке

Заказы

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

В разработке

Получение отдельного заказа

В разработке

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

В разработке

Редактирование заказа

В разработке

Частичное редактирование заказа

В разработке

Подтверждение заказов

В разработке

Отмена заказов

В разработке

Дублирование заказов

В разработке

Дублирование заказа для возврата

В разработке

Возврат заказов

В разработке

Продление хранения на ПВЗ

В разработке

Комплектация заказов

В разработке

Раскомплектация заказов

В разработке

Получение параметров забора для создания заказа без склада и магазина

В разработке

Заборы

Документация к API заборов

Получение списка заборов

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

import api, { APIDataPaginatedResponse, GetPickupsParams, Pickup } from 'saferoute-api';

const token = '******************';
const params: GetPickupsParams = { archive: true };

const res: APIDataPaginatedResponse<Pickup> = await api.pickups.getPickups(token, params);

Создание забора

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

import api, { APIDataResponse, PickupCreateParams, PICKUP_TYPES } from 'saferoute-api';

const token = '******************';
const params: PickupCreateParams = {
  date: '2024-02-01',
  type: PICKUP_TYPES.COURIER_MERGED,
  companyId: 1,
  warehouseId: 2,
  comment: null,
};

const res: APIDataResponse<{ id: number }> = await api.pickups.createPickup(token, params);

Отмена забора

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

import api, { APIBoolResponse } from 'saferoute-api';

const token = '******************';
const id = 15; // ID забора

const res: APIBoolResponse = await api.pickups.cancelPickup(token, id);

Получение списка компаний забора

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

import api, { APIDataResponse, GetPickupCompaniesParams, PickupCompany, PICKUP_TYPES } from 'saferoute-api';

const token = '******************';
const params: GetPickupCompaniesParams = {
  type: PICKUP_TYPES.COURIER_MERGED,
  warehouseId: 1,
};

const res: APIDataResponse<PickupCompany> = await api.pickups.getPickupCompanies(token, params);

Товары

Получение списка товаров

В разработке

Получение отдельного товара

В разработке

Создание нового товара

В разработке

Редактирование товара

В разработке

Частичное редактирование товара

В разработке

Удаление товара

В разработке

Импорт товаров

В разработке

Комплекты товаров

Получение списка комплектов

В разработке

Получение отдельного комплекта

В разработке

Создание нового комплекта

В разработке

Редактирование комплекта

В разработке

Удаление комплекта

В разработке

Склады

Получение списка складов

В разработке

Получение отдельного склада

В разработке

Создание нового склада

В разработке

Редактирование склада

В разработке

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

В разработке

Магазины

Получение списка магазинов

В разработке

Получение отдельного магазина

В разработке

Создание нового магазина

В разработке

Редактирование магазина

В разработке

Удаление магазина

В разработке

Коробки

Получение списка коробок

В разработке

Получение отдельной коробки

В разработке

Создание новой коробки

В разработке

Редактирование коробки

В разработке

Частичное редактирование коробки

В разработке

Удаление коробки

В разработке

Документы

Список актов приёма товаров

В разработке

Формирование акта приёма товаров

В разработке

Список актов передачи заказов

В разработке

Создание актов передачи заказов

В разработке

Генерация сборочной ведомости

В разработке

Формирование отчёта по движению товаров

В разработке

Список стикеров

В разработке

Формирование стикеров

В разработке

Отчёты

Документация к API отчётов

Список счетов

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

import api, { APIDataPaginatedResponse, GetBillsParams, Bill } from 'saferoute-api';

const token = '******************';
const params: GetBillsParams = { from: '2023-01-01', to: '2023-03-01' };

const res: APIDataPaginatedResponse<Bill> = await api.reports.getBills(token, params);

Список отчётов агента/исполнителя

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

import api, { APIDataPaginatedResponse, GetAgentReportsParams, AgentReport, REPORTS_TYPES } from 'saferoute-api';

const token = '******************';
const params: GetAgentReportsParams = { from: '2023-01-01', to: '2023-03-01', type: REPORTS_TYPES.DAILY };

const res: APIDataPaginatedResponse<AgentReport> = await api.reports.getAgentReports(token, params);

Подтверждение отчёта агента

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

import api, { APIBoolResponse } from 'saferoute-api';

const token = '******************';
const id = 15; // ID отчёта

const res: APIBoolResponse = await api.reports.confirmAgentReport(token, id);

Список аналитических отчётов

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

import api, { APIDataPaginatedResponse, GetAnalyticalReportsParams, AnalyticalReport, ANALYTICAL_REPORTS_TYPES } from 'saferoute-api';

const token = '******************';
const params: GetAnalyticalReportsParams = { from: '2023-01-01', to: '2023-03-01', type: ANALYTICAL_REPORTS_TYPES.CONSOLIDATED };

const res: APIDataPaginatedResponse<AnalyticalReport> = await api.reports.getAnalyticalReports(token, params);

Генерация аналитических отчётов

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

import api, { APIDataResponse, AnalyticalReportGenerateParams, ANALYTICAL_REPORTS_TYPES } from 'saferoute-api';

const token = '******************';
const params: AnalyticalReportGenerateParams = {
  date: { from: '2023-01-01', to: '2023-03-01' },
  type: ANALYTICAL_REPORTS_TYPES.BY_ORDERS,
};

const res: APIDataResponse<{ file: string }> = await api.reports.generateAnalyticalReport(token, params);

Маркетплейсы

Список маркетплейсов

В разработке

Редактирование настроек маркетплейса

В разработке

Другое

Список дополнительных услуг

В разработке

Информация об интервалах курьерской доставки

import api, { APIDataResponse, GetCourierScheduleParams, CourierScheduleItem } from 'saferoute-api';

const token = '******************';
const params: GetCourierScheduleParams = {
  shopId: 777777,
  companyId: 1,
  deliveryDate: '2025-12-01',
  deliveryAddress: {
    city: {
      countryCode: 'RU',
      name: 'Москва',
      type: 'г',
      fias: '0c5b2444-70a0-4932-980c-b4dc0d3f02b5',
      region: null,
      area: null,
    },
    street: 'ул. Мира',
    house: 10,
    bulk: null,
    flat: 7,
    zipCode: null,
  },
};

const res: APIDataResponse<CourierScheduleItem[]> = await api.other.getCourierSchedule(token, params);

Список компаний доставки (кроме возвратных)

В разработке

Список компаний возврата

В разработке

Список всех ПВЗ

В разработке

Список маркетплейсов со складами

В разработке

Список статусов заказа

В разработке

Трекинг заказа

В разработке

Данные по доступным вариантам отгрузки

В разработке

Виджеты

Функции для помощи в интеграции виджетов.

apiScript

Реализация API-скрипта виджетов для nodejs.

Пример подключения с использованием NestJS.

import { Body, Controller, Get, Post, Query, HttpCode, HttpStatus, Ip } from '@nestjs/common';

import api, { WidgetsApiResponse } from 'saferoute-api';

const token = '******************';
const shopId = 777777;

@Controller('widgets')
export default class WidgetsController {
  @Get('api')
  getApiRequest(@Query() query, @Ip() ip: string): Promise<WidgetsApiResponse> {
    return api.widgets.widgetApi(query.url, 'GET', query.data, { token, shopId }, ip);
  }

  @Post('api')
  @HttpCode(HttpStatus.OK)
  postApiRequest(@Body('url') url: string, @Body('data') data, @Ip() ip: string): Promise<WidgetsApiResponse> {
    return api.widgets.widgetApi(url, 'POST', data, { token, shopId }, ip);
  }
}

widgets/update-order

Функция обновления данных заказа, созданного корзинным виджетом.

См. изменение параметров заказа после его создания.

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

import api, { WidgetsUpdateOrderResponse } from 'saferoute-api';

const token = '******************';
const shopId = 777777;

// ID заказа, полученный из виджета, либо возвращённый предыдущим вызовом api.widgets.updateOrder() в data.cabinetId
const orderId = '';

const res: Promise<WidgetsUpdateOrderResponse> = api.widgets.updateOrder(orderId, {
  status: 'confirmed',  // Код статуса заказа
  paymentMethod: 'cod', // Код способа оплаты заказа
  COD: true,            // Наличие наложенного платежа (nppOption из документации к виджету)
  cmsId: '656565',      // ID заказа в CMS
  payment: false,       // Флаг совершения оплаты
}, { token, shopId });

Описание ответа WidgetsUpdateOrderResponse.

type WidgetsUpdateOrderResponse =
  // Заказ обновлён успешно
  // Если заказ был отправлен в Личный кабинет, data.cabinetId будет содержать его ID в Личном кабинете
  | {
      status: WIDGETS_RESPONSE_STATUS_CODES.SUCCESS;
      data: {
        cabinetId: number | null;
      };
    }
  // Ошибка
  // data.code содержит код ошибки (см. документацию к виджету), data.message - текстовую расшифровку (опционально)
  | {
      status: WIDGETS_RESPONSE_STATUS_CODES.REQUEST_ERROR;
      data: {
        code: WIDGETS_UPDATE_ORDER_ERRORS;
        message: string;
      };
    }
  // Ошибка авторизации - передан некорректный токен
  | {
      status: WIDGETS_RESPONSE_STATUS_CODES.AUTH_ERROR;
    }
  // Ошибка сервера - обратитесь в техподдержку
  | {
      status: WIDGETS_RESPONSE_STATUS_CODES.SERVER_ERROR;
    };

widgets/confirm-order

Функция подтверждения оформления заказа на сайте при оплате через эквайринг корзинного виджета.

См. встроенный эквайринг.

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

import api, { WidgetsConfirmOrderResponse } from 'saferoute-api';

const token = '******************';
const shopId = 777777;

// ID сессии чекаута, полученный из виджета после оформления заказа
const checkoutSessId = '';

const res: Promise<WidgetsConfirmOrderResponse> = api.widgets.confirmOrder(checkoutSessId, { token, shopId });

Описание ответа WidgetsConfirmOrderResponse.

type WidgetsConfirmOrderResponse =
  // Заказ успешно подтверждён
  | {
      status: WIDGETS_RESPONSE_STATUS_CODES.SUCCESS;
    }
  // Ошибка, data.code содержит код ошибки (см. документацию к виджету)
  | {
      status: WIDGETS_RESPONSE_STATUS_CODES.REQUEST_ERROR;
      data: {
        code: WIDGETS_CONFIRM_ORDER_ERRORS;
      };
    }
  // Ошибка авторизации - передан некорректный токен
  | {
      status: WIDGETS_RESPONSE_STATUS_CODES.AUTH_ERROR;
    }
  // Ошибка сервера - обратитесь в техподдержку
  | {
      status: WIDGETS_RESPONSE_STATUS_CODES.SERVER_ERROR;
    };

Константы

Общие

  • ERROR_CODES - Коды ошибок API

Заборы

  • PICKUP_TYPES - Типы заборов
  • PICKUP_STATUSES - Статусы заборов

Отчёты

  • BILLS_STATUSES - Статусы счетов
  • REPORTS_TYPES - Типы отчётов
  • ANALYTICAL_REPORTS_TYPES - Типы аналитических отчётов
  • ANALYTICAL_REPORT_ORDERS_STAGES - Этапы выборки заказов для аналитических отчётов

Виджеты

saferouteapiwidgetsintegrationnodejsexpressnestjsbackend
is-localhost-ipnode-fetchurl-join
0.3.0

3 months ago

0.2.3

3 months ago

0.3.1

3 months ago

0.2.1

1 year ago

0.2.0

1 year ago

0.2.2

1 year ago

0.1.0

1 year ago

0.0.9

1 year ago

0.0.8

1 year ago

0.0.5

1 year ago

0.0.7

1 year ago

0.0.6

1 year ago

0.0.3

1 year ago

0.0.4

1 year ago

0.0.2

1 year ago

0.0.1

1 year ago