otapi-client

TypeScript client for the OTApi e-commerce REST API.

Installation

npm install otapi-client

Quick Start

import { OTClient } from "otapi-client";

const client = new OTClient("your-instance-key", {
  language: "en",
  secret: "your-secret", // optional, enables request signing
  debug: true,           // optional, logs responses
});

// Get an anonymous session
const session = await client.GetAnonymousSession();
console.log(session.Result);

Configuration

interface OTClientConfig {
  language?: string;  // Response language (default: "en")
  secret?: string;    // Secret key for HMAC request signing
  baseUrl?: string;   // API base URL (default: "https://otapi.net/service-json")
  debug?: boolean;    // Log API responses to console (default: false)
}

Methods

Session & Authentication

GetAnonymousSession()

Creates a new anonymous session.

const res = await client.GetAnonymousSession();
const sessionId = res.Result.Id;

Authenticate(params)

Authenticates a user with login and password.

await client.Authenticate({
  sessionId: "...",       // optional
  userLogin: "user",
  userPassword: "pass",
  rememberMe: true,       // optional
});

AuthenticateInstanceOperator(params)

Authenticates an instance operator.

await client.AuthenticateInstanceOperator({
  userLogin: "operator",
  userPassword: "pass",
});

AuthenticateAsUser(params)

Authenticates as a specific user (requires operator session).

await client.AuthenticateAsUser({
  sessionId: "operator-session-id",
  userLogin: "target-user",
});

RegisterUser(params)

Registers a new user.

await client.RegisterUser({
  sessionId: "...",          // optional
  userParameters: "<xml>",
});

Items & Search

BatchGetItemFullInfo(params)

Gets full information for an item.

await client.BatchGetItemFullInfo({
  sessionId: "...",          // optional
  itemId: "item-123",
  itemParameters: "...",     // optional
  blockList: ["Vendor", "Description"], // optional, exclude specific blocks
});

blockList values: "DeliveryCosts" | "Promotions" | "Vendor" | "RootPath" | "ProviderReviews" | "MostPopularVendorItems16" | "RecommendedItems" | "Description" | "OriginalDescription"

BatchSearchItemsFrame(params)

Searches for items with pagination.

await client.BatchSearchItemsFrame({
  sessionId: "...",          // optional
  xmlParameters: {
    ItemTitle: "phone case",
    MinPrice: 10,
    MaxPrice: 100,
    CategoryId: "cat-123",
    OrderBy: "Price",
    Configurators: [{ Pid: "1", Vid: "2" }],
    Features: [{ Name: "FreeShipping", value: true }],
  },
  framePosition: 0,
  frameSize: 20,
  blockList: ["SubCategories"], // optional
});

blockList values: "SubCategories" | "SearchProperties" | "RootPath" | "Vendor" | "Brand" | "Category" | "HintCategories" | "AvailableSearchMethods"

Full SearchItemsParameters fields:

| Field | Type | Description | |---|---|---| | Provider | string | Provider name | | SearchMethod | string | Search method to use | | CategoryId | string | Filter by category | | VendorName | string | Filter by vendor name | | VendorId | string | Filter by vendor ID | | VendorAreaId | string | Filter by vendor area | | ItemTitle | string | Search query text | | LanguageOfQuery | string | Language of the search query | | MinPrice / MaxPrice | number | Price range filter | | EnableDirectSearch | boolean | Enable direct search mode | | CurrencyCode | string | Currency for prices | | MinVolume / MaxVolume | number | Volume range filter | | MinVendorRating / MaxVendorRating | number | Vendor rating range | | BrandId | string | Filter by brand | | Configurators | SearchConfigurator[] | Product configurators ({ Pid, Vid }) | | OrderBy | string | Sort order | | OutputMode | string | Output mode | | CategoryMode | string | Category mode | | IsTmall | boolean | Tmall items only | | StuffStatus | string | Item condition | | Features | SearchFeature[] | Search features ({ Name, value }) | | UseOptimalFrameSize | boolean | Auto-optimize page size | | MinFirstLot / MaxFirstLot | number | First lot range | | MinUpdatedTime / MaxUpdatedTime | string | Updated time range | | MinCreatedTime / MaxCreatedTime | string | Created time range | | Module | string | Module name | | ImageUrl | string | Image search URL | | ImageFileId | string | Image file ID for search | | ImageItemId | string | Image item ID for search |

Catalog

GetRootCategoryInfoList()

Returns the root category list.

const categories = await client.GetRootCategoryInfoList();

GetBrandInfoList()

Returns the brand list.

const brands = await client.GetBrandInfoList();

Orders

AddOrder(params)

Creates a new order.

await client.AddOrder({
  sessionId: "...",          // optional
  xmlAddData: {
    DeliveryModeId: "dm-1",  // optional
    Comment: "Rush order",   // optional
    UserProfileId: "up-1",   // optional
    Items: [
      {
        Id: "item-123",
        Quantity: 2,
        ConfigurationId: "...", // optional
        Weight: 0.5,           // optional
        Comment: "...",        // optional
        PromotionId: "...",    // optional
        PriceType: "...",      // optional
      },
    ],
  },
});

SearchOrdersForUser(params)

Searches orders for the current user with pagination.

await client.SearchOrdersForUser({
  sessionId: "...",          // optional
  xmlSearchParameters: {
    StatusIdList: [1, 2],          // optional
    IsAwaitingUser: false,         // optional
    IsCancelled: false,            // optional
    IsCompleted: true,             // optional
    ProviderType: "...",           // optional
    IsAvailableForRecreation: false, // optional
  },
  framePosition: 0,
  frameSize: 10,
});

User Profiles

CreateUserProfile(params)

Creates a user delivery profile.

await client.CreateUserProfile({
  sessionId: "session-id",
  createData: {
    FirstName: "John",
    LastName: "Doe",
    CountryCode: "US",
    City: "New York",
    Address: "123 Main St",
    Phone: "+1234567890",
    PostalCode: "10001",
  },
});

Full UserProfileCreateData fields: FirstName, LastName, MiddleName, CountryCode, Region, City, CityCode, Address, Phone, PostalCode, ExternalDeliveryId, PickupPointCode, PassportNumber, ResetPassportIssueDate, PassportIssueDate, RegistrationAddress, INN, EnableValidation

Payments

SalesPaymentReserve(params)

Reserves a payment for a sales order.

await client.SalesPaymentReserve({
  sessionId: "session-id",
  salesId: "sales-123",
  amount: "100.00",
});

PostTransaction(params)

Posts a financial transaction.

await client.PostTransaction({
  sessionId: "...",            // optional
  customerId: "customer-123",
  amount: "50.00",
  isDebit: true,
  comment: "Refund",          // optional
  transactionDate: "2025-01-01", // optional
});

Error Handling

All methods throw OTApiError when the API returns a non-Ok error code.

import { OTApiError } from "otapi-client";

try {
  await client.Authenticate({ userLogin: "x", userPassword: "y" });
} catch (err) {
  if (err instanceof OTApiError) {
    console.log(err.code);    // e.g. "InvalidCredentials"
    console.log(err.message); // error description
  }
}

Response Format

All methods return OTApiResponse<T>:

interface OTApiResponse<T = unknown> {
  ErrorCode: string;
  ErrorDescription?: string;
  Result?: T;
}

License

ISC