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:

📋 Integration Progress Tracker - Click to expand

Prerequisites (from Authentication Guide):

API credentials obtained
Access token retrieved
Customer validated
Branch locations explored

Steps 5-8 Progress (from Order Flow Guide):

🏪 Step 5: Customer branches retrieved
📦 Step 6: Products browsed at branch
💰 Step 7: Real-time pricing obtained
✅ Step 8: Order successfully submitted

Key Data Collected:

jobAccountNumber saved (from Step 5)
Product IDs identified (from Step 6)
Pricing validated (from Step 7)
Order ID received (from Step 8)

Integration Complete:

First test order submitted successfully
Order confirmation received
Webhook setup planned (for Production)
Error handling implemented

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!

🌐 API Environments

Staging (Testing):

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

Safe testing, synchronous orders only

Production (Live Orders):

Contact SRS API Support for credentials

Real orders, async/sync available

⚡ Quick Start

Test the API:

💬 Need Help?

Contact SRS API Support:

Email: APISupportTeam@srsdistribution.com

Include: Client ID (NOT secret), Environment (QA/Production), Error details

Response Time: 1-2 business days

Documentation:

�🎯 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)#

🌐 API Environments#

⚡ Quick Start#

💬 Need Help?#

�🎯 Ready to Start?#