Introduction to SRS Integration Partner Services

Welcome to the SRS Integration Partner System (SIPS)! This guide helps software partners integrate with SRS Distribution to place orders, manage inventory, and track deliveries through our API.

🎯 What You'll Learn

This documentation will guide you through:

✅ Setting up your API credentials and authentication

✅ Making your first calls to validate customers and explore data

✅ Implementing the complete order flow from product selection to submission

✅ Setting up webhooks for real-time order updates

✅ Best practices for production deployments

⏱️ Time to Complete: Most integrations are live within 2-3 weeks following this guide

🗺️ Integration Journey

The path to success:

🔐 Setup (Steps 1-2) - Get credentials and authenticate

🔍 Explore (Steps 3-4) - Validate and discover

🛒 Build (Steps 5-7) - Construct your order

✅ Execute (Step 8) - Submit and track

✅ Integration Checklist

Track your progress through the integration:

📋 Click to see your integration checklist

Phase 1: Setup (Week 1)

Request API credentials from SRS team

Receive Client ID and Secret

Set up development environment

Test authentication endpoint

Get first access token successfully

Phase 2: Development (Week 1-2)

Validate customer endpoint working

Retrieve branch locations

Get customer branch relationships

Query available products

Request and receive pricing

Submit first test order (Staging)

Verify order confirmation

Phase 3: Webhook Setup (Week 2)

Create webhook endpoint in your system

Test webhook notifications

Handle order status updates

Implement error handling

Phase 4: Production (Week 3)

Complete all Staging tests

Request Production credentials

Configure Production webhooks

Test in Production (low volume)

Monitor and optimize

Full production rollout

Optional Enhancements:

Implement token refresh automation

Add comprehensive error logging

Set up monitoring and alerts

Create customer-facing order tracking

Integrate with your ERP/CRM

Choose your path based on your experience level:

📚 New to SIPS? Click to see the complete learning path

Start here for a step-by-step guided experience:

Authentication Guide - Setup, authentication, and first API calls (Steps 1-4)

⏱️ Time: 30 minutes

🎯 Goal: Get your access token and make your first API call

Place Order Guide - Complete order implementation (Steps 5-8)

⏱️ Time: 2-3 hours

🎯 Goal: Submit your first test order successfully

Webhook Setup - Real-time order updates

⏱️ Time: 1 hour

🎯 Goal: Receive order status updates automatically

🔍 Looking for something specific? Click to see quick links

📊 Best Practices - Performance, security, and optimization tips

⚠️ Error Handling - Common errors and how to handle them

❓ FAQs - Frequently asked questions

📖 API Reference - Detailed endpoint documentation

📋 Integration Overview - 8 Steps

📚 Complete guide: Follow the Authentication Guide (Steps 1-4) then Place Order Guide (Steps 5-8) for full implementation.

🔐 Phase 1: Setup & Authentication (Steps 1-2)

💼 Step 1: Request Credentials - Click to expand

What you need to do:

Email APISupportTeam@srsdistribution.com

Include your company name and integration purpose

What you'll receive:

client_id - Your unique identifier

client_secret - Your authentication secret (keep secure!)

Response time: Usually within 1-2 business days

🔒 Security Tip: Never share your client_secret publicly or commit it to version control!

🔑 Step 2: Authenticate - Click to expand

Endpoint: POST /authentication/token

What you'll get:

access_token - Your session token (valid 24 hours)

expires_in - Token expiration time in seconds

Quick Example:

⏰ Token Management: Tokens expire after 24 hours. Implement automatic refresh before expiration!

🔍 Phase 2: Explore & Validate (Steps 3-4)

✅ Step 3: Validate Customer - Click to expand

Endpoint: /api/customer/validate

Why this matters:

Verifies customer has access to API

Returns customer account details

Required before placing orders

Key Response Field:

validIndicator: true ✅ Customer can place orders

validIndicator: false ❌ Customer not eligible

⚠️ Critical: Always check validIndicator before proceeding with orders!

📍 Step 4: Get Branch Locations - Click to expand

Endpoint: /branches/v2/branchLocations

What you'll discover:

All SRS branch locations

Available shipping methods per branch

Branch contact information

Operating hours

Use this data to:

Show available branches to your users

Let customers choose preferred pickup/delivery location

Calculate shipping costs

🛒 Phase 3: Build Your Order (Steps 5-7)

🏪 Step 5: Find Customer Branches - Click to expand

Endpoint: /branches/v2/customerBranchLocations/{customerCode}

Critical Information Retrieved:

jobAccountNumber - Required for order submission

Customer-specific branch relationships

Delivery addresses (ShipTo locations)

Example Response:

{
  "jobAccountNumber": 78,
  "branchCode": "AMDEN",
  "shipToSequenceNumber": 1
}

💡 Pro Tip: Save the jobAccountNumber - you'll need it for every order!

📦 Step 6: Get Available Products - Click to expand

Endpoint: /branches/v2/activeBranchProducts/{branchCode}

Returns:

Products available at the specific branch

Product IDs, names, and descriptions

Available units of measure (UOM)

Product categories

Why this matters:

Not all products are available at all branches

Shows current inventory availability

Prevents ordering unavailable items

💰 Step 7: Get Pricing - Click to expand

Endpoint: /products/v2/price

Real-time Information:

Current prices per customer

Stock availability (In Stock / Out of Stock)

Quantity discounts

Product substitution options

Request Example:

{
  "customerCode": "ABC123",
  "branchCode": "AMDEN",
  "productList": [
    {
      "productId": 12345,
      "quantity": 10,
      "uom": "EA"
    }
  ]
}

⚡ Performance Tip: Prices are customer-specific. Always use the correct customerCode!

✅ Phase 4: Submit Order (Step 8)

🚀 Step 8: Submit Order - Click to expand

Endpoint: /orders/v2/submit

Required Data (from previous steps):

✅ Access token (Step 2)

✅ Validated customer (Step 3)

✅ Job account number (Step 5)

✅ Product IDs (Step 6)

✅ Pricing information (Step 7)

Successful Response:

{
  "message": "Order Submitted",
  "transactionID": "YOUR-UNIQUE-ID",
  "orderID": "35818786",
  "queueID": null
}

Order Methods:

Synchronous: Immediate processing (Staging/Testing)

Asynchronous: Queue-based processing (Production - Recommended)

🎯 Success! You've completed the full integration flow!

📤 Order Submission Methods

Staging Environment (Testing)

📘 Important: Staging environment supports synchronous orders only and uses sync as the default submission method. All testing must use synchronous submission.

⚡ Synchronous Order Submission (Staging/Testing) - Click to expand

How it works:

You submit order via API

System processes immediately

Instant Order ID response (within seconds)

Characteristics:

✅ Order processed immediately

✅ Instant Order ID response

✅ Required for all Staging environment testing

✅ Simple implementation, perfect for development

⚠️ Not available during system maintenance

Best for:

Development and testing

Low-volume integrations

Simple proof-of-concept implementations

Response Example:

{
  "orderID": "12345678",
  "transactionID": "YOUR-ID",
  "queueID": null
}

Production Environment (Live Orders)

⚡ Synchronous Orders - Click to expand

How it works:

Order processed immediately

Instant Order ID response

Best for:

Low-volume integrations (< 50 orders/day)

Simple implementations

When immediate confirmation is required

Limitations:

⚠️ Orders may fail during system maintenance

⚠️ No automatic retry mechanism

⚠️ Requires manual error handling

🔄 Asynchronous Orders (Recommended for Production) - Click to expand

How it works:

You submit order via API

Order queued for processing

Receive queueID immediately

Order processes in background

Webhook notification when complete

Benefits:

✅ Orders queued safely during maintenance

✅ Automatic retry on temporary failures

✅ Better performance for high-volume

✅ Real-time status updates via webhooks

✅ Maximum reliability

Best for:

Production systems

High-volume integrations (50+ orders/day)

Mission-critical applications

Maximum reliability requirements

Requirements:

Must configure webhook endpoints

Must handle webhook notifications

See Webhook Setup Guide

Response Example:

{
  "queueID": "queue-abc-123",
  "orderID": "12345678",
  "transactionID": "YOUR-ID",
  "status": "queued"
}

Webhook Notification (when processed):

{
  "orderID": "12345678",
  "status": "completed",
  "processedDate": "2026-02-27T10:30:00Z"
}

🚀 Production Recommendation: Use asynchronous orders with webhooks. This ensures orders are processed even during system maintenance. Webhook endpoints must be provided before Production deployment.

🌐 API Environments

🧪 Staging Environment (Testing) - Click to expand

Base URL: https://services-qa.roofhub.pro

Purpose:

Development and testing

Order validation

Integration testing

Characteristics:

✅ Safe for testing (no real orders)

✅ Same API structure as Production

⚠️ Synchronous orders only

⚠️ Test data may be reset periodically

Use this for:

Initial development

Testing new features

Training and demos

🚀 Production Environment (Live Orders) - Click to expand

Base URL: Contact SRS API Support Team for Production credentials

Purpose:

Live order processing

Real customer orders

Production integrations

Characteristics:

✅ Real order processing

✅ Asynchronous orders available (recommended)

✅ High availability (99.9% uptime SLA)

⚠️ Requires Production credentials

⚠️ Real orders charge real money!

Requirements:

Completed Staging testing

Webhook endpoints configured

Production credentials from SRS team

⚡ Quick Start Resources

API Collection

📦 Import Ready-to-Use Collections - Click to expand

Get started immediately with pre-configured API requests:

APIdog Collection:

📥 Import Collection - Pre-configured requests with examples

✅ All 8 steps included

✅ Environment variables pre-set

✅ Example payloads included

Postman Collection:

📥 Download JSON - Import into Postman

✅ Complete request collection

✅ Environment templates

✅ Automated testing scripts

What's included:

Authentication flow

Customer validation

Product queries

Pricing requests

Order submission

Error handling examples

Quick Test with cURL

💻 Test instantly from your terminal - Click to expand

Test the API instantly from your terminal:

Expected Response (Authentication):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Expected Response (Branch Locations):

[
  {
    "branchCode": "AMDEN",
    "branchName": "SRS - Denver",
    "city": "Denver",
    "state": "CO"
  }
]

💡 Pro Tip: Save your credentials as environment variables:
Then use them in scripts: curl -X POST $SRS_BASE_URL/authentication/token

💬 Need Help?

📧 Contact SRS API Support Team - Click to expand

Email: APISupportTeam@srsdistribution.com

Include in your message:

✅ Your client ID (NOT your secret!)

✅ Environment (QA/Production)

✅ Error details or question

✅ Sample request/response (if applicable)

✅ Transaction ID (if available)

Response Time: 1-2 business days

Urgent Issues:

Production outages

Order processing failures

Authentication problems

❓ Common Questions - Click to expand

Q: How long does credential approval take?

A: Usually 1-2 business days after submission

Q: Can I test in Staging before Production?

A: Yes! Staging is required before Production access

Q: Do tokens expire?

A: Yes, after 24 hours. Implement automatic refresh

Q: What's the rate limit?

A: Contact API Support for current limits

Q: Can I use the same credentials for Staging and Production?

A: No, you'll receive separate credentials for each environment

🎯 Ready to Start?

Choose your path:

🆕 First time integrating?
→ Start with Authentication Guide (Steps 1-4)

✅ Already authenticated?
→ Continue to Place Order Guide (Steps 5-8)

🚀 Ready for Production?
→ Review Best Practices and Webhook Setup

Let's build something great together! 🚀

Introduction

Introduction to SRS Integration Partner Services#

🎯 What You'll Learn#

🗺️ Integration Journey#

✅ Integration Checklist#

🚀 Quick Navigation#

📋 Integration Overview - 8 Steps#

🔐 Phase 1: Setup & Authentication (Steps 1-2)#

🔍 Phase 2: Explore & Validate (Steps 3-4)#

🛒 Phase 3: Build Your Order (Steps 5-7)#

✅ Phase 4: Submit Order (Step 8)#

📤 Order Submission Methods#

Staging Environment (Testing)#

Production Environment (Live Orders)#

🌐 API Environments#

⚡ Quick Start Resources#

API Collection#

Quick Test with cURL#

💬 Need Help?#

🎯 Ready to Start?#

Introduction to SRS Integration Partner Services

🎯 What You'll Learn

🗺️ Integration Journey

✅ Integration Checklist

🚀 Quick Navigation

📋 Integration Overview - 8 Steps

🔐 Phase 1: Setup & Authentication (Steps 1-2)

🔍 Phase 2: Explore & Validate (Steps 3-4)

🛒 Phase 3: Build Your Order (Steps 5-7)

✅ Phase 4: Submit Order (Step 8)

📤 Order Submission Methods

Staging Environment (Testing)

Production Environment (Live Orders)

🌐 API Environments

⚡ Quick Start Resources

API Collection

Quick Test with cURL

💬 Need Help?

🎯 Ready to Start?