Skip to main content

API Testing with Postman

Test Staqr and Commerce APIs interactively using Postman's GUI interface - no coding required.

What are Postman Collections?​

Postman collections are pre-configured sets of API requests that you can import into Postman Desktop or Postman Web to test APIs visually.

Benefits:

  • 🎯 No command-line knowledge required
  • 🔄 Save and reuse API requests
  • 📊 View formatted JSON responses
  • ✅ Perfect for support engineers, sales demos, partner onboarding
  • 🧪 Test workflows interactively

Available Collections​

Staqr Platform API​

Download: Staqr-Platform-API.postman_collection.json

Coverage:

  • Flows API - Create, list, execute flows
  • Connections API - Manage integration credentials
  • Folders API - Organize flows and connections
  • Users API - User management
  • Platform API - System configuration

Size: ~15MB Endpoints: 100+ requests organized by category

Download: Commerce-API-v1.postman_collection.json

Coverage:

  • Customer Management - Create and manage customers
  • Subscription Management - Subscriptions, services, products
  • Billing - Invoices, payments, wallets
  • Orders - Create and track orders

Size: ~15MB Endpoints: 200+ business-focused requests Status: ✅ Recommended for new integrations

Commerce API v2 (Generic CRUD)​

Download: Commerce-API-v2.postman_collection.json

Coverage:

  • Generic entity CRUD operations
  • Simpler, more RESTful interface

Size: ~7MB Endpoints: 50+ generic operations Use for: Simple entity management

Commerce API v0 (Legacy)​

Download: Commerce-API-v0.postman_collection.json

Coverage: Complete legacy API (for migration support only)

Size: ~83MB Status: ⚠️ Legacy - use v1 or v2 for new work

Pre-configured Environments​

Download: Sandbox.postman_environment.json

Configuration:

{
  "baseUrl": "https://sandbox.api.staqr.com",
  "apiKey": "(set this yourself)",
  "sellerId": "demo-seller",
  "commerceBaseUrl": "https://sandbox-commerce.staqr.com/api"
}

Use for: API exploration, partner testing, sales demos

Development Environment (Local)​

Download: Development.postman_environment.json

Configuration:

{
  "baseUrl": "http://localhost:4600",
  "apiKey": "(from your .env file)",
  "sellerId": "local-seller",
  "commerceBaseUrl": "http://localhost:8080/api"
}

Requires: Local Staqr API running (npm run dev)

Use for: Local development, debugging

Quick Start Guide​

Step 1: Install Postman​

Download Postman Desktop: https://www.postman.com/downloads/

Or use Postman Web: https://www.postman.com/ (requires account)

Step 2: Import Collection​

  1. Open Postman
  2. Click Import button (top-left)
  3. Click Upload Files
  4. Select downloaded collection JSON file
  5. Click Import

The collection appears in the left sidebar.

Step 3: Import Environment​

  1. Click Environments tab (left sidebar)
  2. Click Import
  3. Select Sandbox.postman_environment.json
  4. Click Import

Step 4: Configure API Key​

  1. Click Environments → "Staqr Sandbox"
  2. Find the apiKey row
  3. Click in the Current Value field
  4. Paste your API key
  5. Click Save

Get your API key:

Step 5: Select Environment​

  1. Click the Environment dropdown (top-right)
  2. Select "Staqr Sandbox"

Step 6: Test an Endpoint​

  1. Expand the collection in the sidebar
  2. Click on a request (e.g., "List Flows")
  3. Click the Send button
  4. View the response in the bottom panel

Success! You just called the API without writing any code.

Example: Testing the Flows API​

List All Flows​

  1. Collection: Staqr Platform API
  2. Folder: Flows
  3. Request: List Flows (GET)
  4. Expected Response:
{
  "data": [
    {
      "id": "flow-uuid",
      "name": "My Flow",
      "status": "active",
      "trigger": { "type": "webhook" }
    }
  ]
}

Create a New Flow​

  1. Request: Create Flow (POST)
  2. Body: Already pre-populated with example
  3. Click Send
  4. Expected Response: 201 Created with flow details

Authentication​

All collections use Bearer token authentication:

Authorization: Bearer {{apiKey}}

The {{apiKey}} variable is automatically populated from your active environment.

Getting an API Key​

Sandbox:

  1. Visit https://sandbox.staqr.com
  2. Sign in or create account
  3. Navigate to Settings → API Keys
  4. Click Create New Key
  5. Copy the key
  6. Paste into Postman environment

Development:

  1. Open your .env file in the project root
  2. Find AP_API_KEY=...
  3. Copy the value
  4. Paste into Development environment

Common Issues​

"401 Unauthorized"​

Cause: API key not set or incorrect

Fix:

  1. Check environment is selected (top-right dropdown)
  2. Click Environments → Your environment
  3. Verify apiKey has a value in Current Value column
  4. Save environment
  5. Retry request

"404 Not Found"​

Cause: Incorrect base URL

Fix:

  1. Check baseUrl in your environment
  2. Verify it matches your deployment:
    • Sandbox: https://sandbox.api.staqr.com
    • Development: http://localhost:4600

"Connection Refused" (Development)​

Cause: Local API server not running

Fix:

# Start Staqr API locally
npm run dev

"CORS Error" (Postman Web)​

Cause: Browser security blocking request

Fix: Use Postman Desktop app instead (no CORS restrictions)

Advanced Features​

Running Collection Tests​

Postman can run entire collections automatically:

  1. Click collection name
  2. Click Run button (Collection Runner)
  3. Select environment
  4. Click Run [Collection Name]
  5. View pass/fail results

Variables and Scripting​

Collections use Postman variables:

  • {{baseUrl}} - API server
  • {{apiKey}} - Your token
  • {{sellerId}} - Tenant ID

You can add custom variables in environments.

Sharing Collections​

Safe to share:

  • ✅ Collection JSON files (no credentials)
  • ✅ Empty environment templates

Never share:

  • ❌ Environments with real API keys filled in
  • ❌ Production credentials

Regenerating Collections​

Collections are auto-generated from OpenAPI specs. To get the latest version:

From Repository:

# Generate locally
npm run generate:postman

# Collections updated in postman/ directory

From GitHub Releases: Collections are attached to each release:

  1. Visit https://github.com/staqr/staqr/releases/latest
  2. Download collection JSON files from Assets section
  3. Re-import into Postman (overwrites old version)

Integration with Other Tools​

Use with SDKs​

  1. Explore in Postman - Understand API behavior visually
  2. Copy request details - See exact parameters needed
  3. Generate code - Use SDK with copied parameters

Use with Documentation​

  1. Read endpoint docs - Understand what API does
  2. Test in Postman - Try it interactively
  3. Verify behavior - Confirm documentation is accurate

Programmatic Access with SDKs​

Prefer programmatic access? Our SDKs provide type-safe, language-native interfaces:

LanguageDocumentationStatus
TypeScriptTypeScript SDK GuideStable
PythonPython SDK GuideStable
PHP, Java, C#, GoSDK OverviewComing Soon

Why use SDKs?

  • Type safety and IDE autocomplete
  • Pre-built request/response models
  • Error handling built-in
  • Same OpenAPI specs as these Postman collections

See SDK Libraries Overview for the complete language support matrix.

Support​

Having issues?

Want to contribute? Collections are auto-generated from OpenAPI specs. To improve them:

  1. Improve OpenAPI spec documentation
  2. Run npm run generate:postman
  3. Submit PR with updated collections