Tradera API Client

A fully-typed TypeScript client for the Tradera REST API v4. This package provides easy-to-use clients for Tradera's services, with auto-generated TypeScript types and client bindings.

Features

• 🔒 Fully typed - Complete TypeScript definitions for all API methods and responses
• ⚡ Async/await support - All API methods return Promises
• 🛠️ IntelliSense support - Full autocomplete in VS Code and other TypeScript-aware editors
• 🌳 Tree-shakeable - Import only what you need
• 🔄 Auto-generated - Client code is generated directly from Tradera's OpenAPI definition

Official Tradera API Documentation

• REST API Getting Started
• REST API Reference
• Developer Center

Looking for SOAP API v3?

Tradera's SOAP API remains at v3 and is intended for existing integrations. Tradera recommends that all new integrations should use the new REST-API. The previous SOAP client is still available as tradera-soap-api-client, and its source is preserved on the archive/v3 branch. New integrations should use this REST v4 client.

Installation

npm install tradera-api

or if you use yarn

yarn add tradera-api

Usage

Search Service

Use TraderaSearchClient for searching items on Tradera:

import { TraderaSearchClient } from 'tradera-api';

const searchClient = new TraderaSearchClient({
  appId: YOUR_APP_ID,
  appKey: "YOUR_APP_KEY"
});

// Basic search
const result = await searchClient.search({
  query: "vintage",
  categoryId: 0
});

console.log(result);

// Advanced search, category counts, zip code searches, and fixed criteria
// searches are also available as typed methods generated from Tradera's
// OpenAPI definition.
const advancedResult = await searchClient.searchAdvanced({});

Public Service

Use TraderaPublicClient for accessing item details, user information, categories, and more:

import { TraderaPublicClient } from 'tradera-api';

const publicClient = new TraderaPublicClient({
  appId: YOUR_APP_ID,
  appKey: "YOUR_APP_KEY"
});

// Get item details
const item = await publicClient.getItem({ itemId: 123456789 });
console.log(item?.id);
console.log(item?.shortDescription);

// Get all categories
const categories = await publicClient.getCategories({});
console.log(categories);

// Get user information
const user = await publicClient.getUserByAlias({ alias: "username" });
console.log(user?.totalRating);

// Get seller's items
const sellerItems = await publicClient.getSellerItems({ sellerId: 12345 });
console.log(sellerItems);

// Get user feedback
const feedback = await publicClient.getFeedback({ userId: 12345 });
console.log(feedback);

// Get official Tradera time (for auction endings)
const time = await publicClient.getOfficalTime({});
console.log(time);

Using the Raw REST Client

For more control, you can use the generated path client directly:

import { createTraderaClient } from 'tradera-api';

const client = createTraderaClient({
  appId: YOUR_APP_ID,
  appKey: "YOUR_APP_KEY"
});

const { data } = await client.raw.GET('/v4/items/{itemId}', {
  params: {
    path: { itemId: 123456789 }
  }
});

console.log(data);

Available API Methods

Search Service

Official Documentation

Method	Description	Documentation
search	Search for items	REST API Reference
searchAdvanced	Advanced search with filters	REST API Reference
searchCategoryCount	Get category counts for search	REST API Reference
searchByFixedCriteria	Search with fixed criteria lists	REST API Reference
searchByZipCode	Search items near a zip code	REST API Reference

Public Service

Official Documentation

Method	Description	Documentation
getItem	Get details for a specific item	REST API Reference
getSellerItems	Get items from a specific seller	REST API Reference
getSellerItemsQuickInfo	Get minimal item info (useful for new items)	REST API Reference
getUserByAlias	Get user information by alias	REST API Reference
fetchToken	Fetch authorization token	REST API Reference
getOfficalTime	Get official Tradera time	REST API Reference
getCategories	Get category hierarchy	REST API Reference
getAttributeDefinitions	Get attribute definitions for a category	REST API Reference
getAcceptedBidderTypes	Get accepted bidder types	REST API Reference
getExpoItemTypes	Get expo item types with prices	REST API Reference
getItemTypes	Get available item types	REST API Reference
getCounties	Get list of counties for search	REST API Reference
getItemFieldValues	Get available item field values	REST API Reference
getItemAddedDescriptions	Get added descriptions for an item	REST API Reference
getFeedback	Get user feedback	REST API Reference
getFeedbackSummary	Get user feedback summary	REST API Reference
getShippingOptions	Get shipping options for countries	REST API Reference

Scripts

Build

yarn build

Compiles TypeScript to JavaScript in the dist/ folder.

Regenerate Client

yarn generate

Regenerates src/generated/rest from the pinned Tradera OpenAPI definition in openapi/tradera-v4.json. Stable method names and service assignments are defined in openapi/client-operations.json because the upstream definition does not currently provide operation IDs. The generated files should not be edited directly; the authored generator is scripts/generate-client.ts.

To fetch the latest OpenAPI definition and regenerate the client:

yarn update-contract

Authentication

To use the Tradera API, you need to register for API credentials at Tradera's developer portal. You will receive:

• AppId - Your application ID (number)
• AppKey - Your application key (GUID string)

These are automatically included in the X-App-Id and X-App-Key HTTP headers when using the clients.

User Impersonation

Some services require user impersonation in addition to app credentials. This means you need to provide the Tradera user's ID and authorization token:

• TraderaRestrictedClient - For managing items, transactions, and shop settings
• TraderaOrderClient - For managing orders

const client = new TraderaRestrictedClient({
  appId: YOUR_APP_ID,
  appKey: "YOUR_APP_KEY",
  userId: 12345,          // Tradera user ID
  token: "USER_TOKEN"     // Authorization token
});

To obtain a user token, use the fetchToken method from TraderaPublicClient:

import { TraderaPublicClient } from 'tradera-api';

const publicClient = new TraderaPublicClient({
  appId: YOUR_APP_ID,
  appKey: "YOUR_APP_KEY"
});

const token = await publicClient.fetchToken({
  userId: 12345,
  secretKey: "USER_SECRET_KEY"
});

console.log(token);

Tree Shaking

This package supports tree shaking. You can import only what you need:

// Import only the search client
import { TraderaSearchClient } from 'tradera-api';

// Or import generated contract types
import type { components, paths } from 'tradera-api';

type Item = components['schemas']['Item'];
type GetItemPath = paths['/v4/items/{itemId}'];

Dependencies

• openapi-fetch - Typed Fetch client for OpenAPI schemas
• openapi-typescript - TypeScript type generator from OpenAPI

License

MIT