A repeatable path from first login to production.
Use this guide as the shared checklist between your team and ConnectUs. A customer should be able to complete most onboarding without a separate custom development project from ConnectUs.
Phase 1 — Access
- Confirm the customer can sign in to SSP at https://quote.connectuscorp.com/.
- Generate a Sandbox Token from Account Settings → API Integrations → Sandbox Token.
- Store the token securely in the customer's integration environment.
- Confirm GET /client/projects succeeds against the sandbox base URL.
Phase 2 — Map your business data
The hardest part of most integrations is not HTTP; it is agreeing what data in one system means in the other. Create a small mapping before writing order automation.
| Your system | ConnectUs concept | Typical mapping |
|---|---|---|
| Your project / program | Project | Use Project name/ID returned by the API |
| Bundle / configured package | Kit | Use a kit available under the selected project |
| Product / device | Item SKU | Map your product record to the ConnectUs SKU |
| Outbound fulfillment request | Sales Order | Create through POST /client/sales_order |
| Your order / PO reference | customer_po_no | Send a stable identifier from your system |
| Carrier/service choice | shipping_method | Use a name returned by available shipping methods |
Phase 3 — Build the sandbox integration
Authentication
Send the Sandbox Token as a Bearer token on every request.
Discovery
Retrieve projects, kits, devices, shipping methods, and Sales Order statuses instead of hard-coding data that can change.
Sales Order creation
Submit your PO reference and item SKUs. Start with the smallest request that meets your business needs, then add shipping and custom fields.
Order reconciliation
Search by customer_po_no and store the returned ConnectUs Sales Order ID.
Status tracking
Retrieve order details and shipping-document data according to your application's needs.
Phase 4 — Error handling
Your integration should treat HTTP status codes as part of the contract:
| Status | Meaning for your integration | Typical action |
|---|---|---|
| 2xx | Request succeeded | Process the response and persist important IDs/references |
| 401 | Authentication failed | Check token and environment; do not endlessly retry |
| 404 | Requested project/kit/order cannot be found in account scope | Re-check IDs and source data |
| 422 | Request validation failed | Read the errors object, correct the data, then retry |
| 500 | Server or upstream service failure | Log X-Request-ID and response; use controlled retry/backoff |
Phase 5 — Sandbox integration acceptance
Before requesting production cutover, confirm that your implementation can complete the following tests:
- Authenticate successfully with the Sandbox Token.
- Retrieve projects available to the customer.
- Retrieve kits for a known project.
- Retrieve available devices and shipping methods.
- Create a test Sales Order with a unique customer_po_no.
- Search the created Sales Order by customer_po_no.
- Retrieve full Sales Order details using its ConnectUs ID.
- Read Sales Order statuses and handle status IDs correctly.
- Handle a deliberate 422 validation response without crashing or silently discarding the error.
- Handle a deliberate 401 authentication failure without uncontrolled retrying.
- Log method, endpoint, time, HTTP status, customer_po_no, and X-Request-ID for supportability.
Phase 6 — Production cutover
Generate the Production Token in SSP and configure the production base URL separately. Keep environment configuration outside application code whenever possible.
- Set base URL to https://workspace.connectuscorp.com/api/v2.
- Set credentials to the Production Token.
- Verify production connectivity with a safe read request.
- Confirm production SKU/project/shipping mappings.
- Enable live Sales Order writes only after the configuration check.
- Document who is authorized to rotate the Production Token.
Recommended operational ownership
Customer developer
Owns request construction, data mapping, retries, logging, and secure token storage.
Customer operations
Owns business mappings such as SKUs, project selection, shipping choices, and PO conventions.
ConnectUs support
Helps investigate platform-side issues. Include environment, timestamp, endpoint, status, and X-Request-ID when escalating.