saferoute-api

v0.2.2

Published

8 months ago

Пакет для работы с API агрегатора служб доставки SafeRoute.

Downloads

145

0High
0Medium
0Low

dmitry_mezentsev

saferoute api widgets integration nodejs express nestjs backend

Пакет для работы с 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);

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

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

В разработке

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

В разработке

Другое

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

В разработке

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

В разработке

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

В разработке

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

В разработке

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

В разработке

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

В разработке

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

В разработке

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

В разработке

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

В разработке

Виджеты

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

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 - Типы аналитических отчётов

Виджеты

WIDGETS_RESPONSE_STATUS_CODES - Статусы ответа API виджета
WIDGETS_UPDATE_ORDER_ERRORS - Коды ошибок API обновления заказа из виджета
WIDGETS_CONFIRM_ORDER_ERRORS - Коды ошибок API подтверждения оформления заказа в виджете (при оплате через эквайринг виджета)

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

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

Установка

NPM

Yarn

Работа с API

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

APIDataResponse

APIDataPaginatedResponse

APIBoolResponse

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

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

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

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

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

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

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

Заказы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заборы

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

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

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

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

Товары

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

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

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

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

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

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

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

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

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

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

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

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

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

Склады

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

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

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

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

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

Магазины

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

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

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

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

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

Коробки

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

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

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

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

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

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

Документы

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

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

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

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

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

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