Tracepos Developer HubTracepos Developer Hub
Home
Guide
POS & Integrations
API Reference
Webhooks
Postman Collection
Home
Guide
POS & Integrations
API Reference
Webhooks
Postman Collection
  • Getting Started

    • Getting Started
    • Authentication & Security Scopes
    • Postman Collection
    • Architecture & Core Concepts
    • Security & Best Practices
    • Deployment & Hosting Guide

Postman Collection

Test and integrate the Tracepos Public REST API quickly using our official, pre-configured Postman Collection.

The collection covers all 19 public endpoints with pre-built request headers, parameter schemas, and realistic request body examples for retail, inventory, and accounting workflows.


Download Collection

📥 Download Tracepos Postman Collection (v2.1.0)
  • File: tracepos-public-api.json
  • Format: Postman Collection v2.1.0
  • Direct Raw Link: /tracepos-public-api.json

How to Import into Postman

Option A: Import Local JSON File

  1. Click the Download button above to save tracepos-public-api.json to your computer.
  2. Open the Postman desktop application or web app.
  3. Click the Import button in the top-left corner of your workspace.
  4. Drag and drop the downloaded tracepos-public-api.json file into the dialog, or click files to select it.
  5. Click Import. The collection Tracepos Public API (v1) will appear in your left sidebar.

Option B: Import via URL

  1. In Postman, click Import in the top-left sidebar.
  2. Select the Link or URL tab.
  3. Paste the direct URL:
    https://app.tracepos.net/docs/tracepos-public-api.json
    
  4. Click Continue → Import.

Configuring Collection Variables

The collection uses Postman variables to dynamically authenticate every request without having to re-enter headers manually.

  1. Click on the root Tracepos Public API (v1) collection in your left sidebar.
  2. Select the Variables tab.
  3. Update the Current Value column for your warehouse credentials:
VariableDescriptionDefault ValueExample Value
baseUrlPublic API endpoint roothttps://app.tracepos.net/api/v1/publichttps://app.tracepos.net/api/v1/public
publicKeyYour warehouse Public KeyYOUR_PUBLIC_KEYTrp-pk-9f8a12bc4d5e...
secretKeyYour warehouse Secret KeyYOUR_SECRET_KEYTrp-sk-7e2a91b4c3d2...

[!TIP] Authentication Inheritance Every request inside the collection automatically includes the required headers:

  • X-Tracepos-Public-Key: {{publicKey}}
  • X-Tracepos-Secret-Key: {{secretKey}}
  • Accept: application/json

Important Security & Scope Notice:

  • Ensure your test API key has been provisioned with the appropriate scopes: read (for GET requests), write (for customer/supplier/sale/purchase/payment/expense creation), and inventory (for stock and price adjustments). Lacking a required scope returns HTTP 403.
  • Any invalid, expired, or inactive key pair will return uniform HTTP 401 {"status": "error", "message": "Invalid API credentials."}.
  • Per-key rate limiting defaults to 60 requests per minute (HTTP 429).
  1. Click Save (Ctrl + S or Cmd + S).

Collection Contents & Organization

The collection is organized into 8 logical modules matching the API specification:

Tracepos Public API (v1)
├── 1. Catalog & Outlets
│   ├── List Products (supports limit & page)
│   ├── List Products by Category (category_id filter)
│   ├── Get Single Product
│   ├── List Categories (with child departments)
│   ├── Get Single Category
│   ├── List Brands
│   ├── Get Single Brand
│   ├── List Warehouses (company outlets)
│   └── Get Single Warehouse
├── 2. Inventory & Pricing
│   ├── List Stock Adjustments
│   ├── Get Single Stock Adjustment
│   ├── Record Stock Adjustment (add / subtract)
│   ├── List Price Adjustments
│   ├── Get Single Price Adjustment
│   └── Update Product Price (new_sales_price)
├── 3. Parties & CRM
│   ├── List Customers (with balance & credit limit)
│   ├── Get Single Customer
│   ├── Create Customer
│   ├── List Suppliers (with credit period)
│   ├── Get Single Supplier
│   └── Create Supplier
├── 4. Sales & Transactions
│   ├── List Sales Orders (date range & limit)
│   ├── Get Single Sale Order
│   └── Create Sale (POS Checkout with item array & payments)
├── 5. Purchases & Procurement
│   ├── List Purchases
│   ├── Get Single Purchase Order
│   └── Create Purchase (Stock Inward Intake)
├── 6. Payments & Settlements
│   ├── List Payment Modes (cash, bank, POS card)
│   ├── List Payments
│   ├── Discover Unpaid Invoices (user-invoices filter)
│   ├── List Customer & Supplier Directory
│   └── Record Payment & Settle Invoices (multi-invoice matching)
├── 7. Expense Management
│   ├── List Expense Categories
│   ├── List Expenses
│   ├── Record Expense
│   └── Pay Off Due Expense
└── 8. Returns & Reversals
    ├── List Sales Returns
    ├── Record Sales Return (customer return)
    ├── List Purchase Returns
    └── Record Purchase Return (vendor return)

Quick Testing Workflow

Follow this sequence to test end-to-end integration:

1. Test Authentication

Run 1. Catalog & Outlets → List Warehouses.

  • Expected Status: 200 OK
  • Verifies that both publicKey and secretKey are valid and authorized.

2. Discover Catalog & Payment Methods

  1. Run 1. Catalog & Outlets → List Products — copy a product's xid to your product_xid variable.
  2. Run 6. Payments & Settlements → List Payment Modes — copy a payment mode's xid to payment_mode_xid.
  3. Run 3. Parties & CRM → List Customers — copy a customer's xid to customer_xid.

3. Execute a Test Checkout

Run 4. Sales & Transactions → Create Sale (POS Checkout).

  • Expected Status: 200 OK
  • Response: Returns order_xid, invoice number, total amount, and confirmation of automated double-entry ledger posting and stock decrement.
Prev
Authentication & Security Scopes
Next
Architecture & Core Concepts