sps-certification-setup

name

sps-certification-setup

description

Guide and execute SPS Commerce Testing & Certification (TnC) setup for an Orderful customer end-to-end. Use this skill whenever a user asks to configure, submit, or monitor an SPS certification setup — including populating EDI info, connection details, EDI setup, test document details, and checking scenario/test results. The skill pulls EDI configuration from the Orderful customer's account via MCP and calls the SPS TnC Bridge API directly. Also trigger for: "set up SPS testing", "configure SPS certification", "SPS TnC setup", "fill in SPS test details", "check SPS scenario status", "what's failing in SPS testing", "submit SPS setup", "configure SPS for this customer", "help with SPS testing".

SPS Certification Setup Skill

Your goal is to guide an Orderful customer through SPS Commerce Testing & Certification from start to finish — pulling their EDI configuration from Orderful, populating the SPS TnC Bridge, and helping them achieve certification.

All SPS API calls use curl via Bash. Orderful data is fetched via MCP tools. Always follow the phase sequence below and never skip to execution without presenting a plan first.

---

Authentication

Before anything else, you need two things:

1. SPS Bearer Token — ask the user if not provided. It refreshes daily. Strip the "Bearer " prefix if they include it; store just the raw token. All SPS calls use:

   Authorization: Bearer <token>
   

   Base URL: https://api.spscommerce.com

2. Orderful Organization — ask for the org name, ID, or EDI account ISA ID of the customer you're configuring. Use search_organizations or get_account_context to resolve it.

Store these for all subsequent calls in the session:

• SPS_TOKEN — the raw bearer token
• PREPROD_ID — from user.preprod_id in the setup list response (fetched in Phase 1)
• ORDERFUL_ORG_ID — Orderful org ID of the customer
• ORDERFUL_EDI_ACCOUNT_ID — their primary EDI account ID

---

Phase 1 — Load Context

Run these in parallel once you have the SPS token and Orderful org identifier.

1a. Fetch SPS Setup List

curl -s -H "Authorization: Bearer <SPS_TOKEN>" \
  https://api.spscommerce.com/tnc-bridge/setup/v2

Extract and store:

• user.preprod_id → PREPROD_ID (used as {companyId} in ALL config endpoints)
• setups[] → full list of TnC setups
• For each setup note: tc_setup_uid, name, status, workflow_status, setup_process, progresses[]

1b. Fetch Orderful EDI Account Context

get_account_context(organizationId: <ORDERFUL_ORG_ID>)

From the response extract:

• ISA ID (the account's primary isaId) → maps to interchange_id / test_interchange_id
• ISA Qualifier → maps to interchange_qualifier / test_interchange_qualifier (usually "ZZ")
• GS ID — typically same as ISA ID unless the account has a separate GS sender ID
• Connection type — check communicationChannels for any existing AS2, SFTP, or FTP channels
• AS2 ID — if an AS2 channel exists, extract the customer's AS2 ID

1c. Present Setup Overview

List all setups from SPS with their current state. For each setup show:

• Trading partner name (name)
• Current phase (determine from progresses[] — the active phase = started but not completed)
• status / workflow_status
• scenarios_passed / scenarios_total
• Whether setup_process === "begin" (needs configuration)

Ask the user which setup they want to work on if there are multiple. If there's only one, confirm before proceeding.

---

Phase 2 — Assess Setup State

Once you have the target setup (tc_setup_uid), classify its state:

Phase Detection Logic

Inspect progresses[] — each element has date_started and date_completed.

Active Phase	What It Means	Action
"Acknowledge EDI Specifications"	Just started — move to config	Go to Phase 3
"Confirm Test Setup Details"	Needs EDI Info / Connection / EDI Setup	Go to Phase 3
"SPS Configuring Test Setup"	SPS reviewing — wait	Go to Phase 4
"Confirm Test Document Details"	Ready for document details	Go to Phase 5
"Begin Testing" / "Testing In Process"	Testing underway	Go to Phase 6
"Confirm Production Setup Details"	Moving to production config	Note for user
"Testing & Certification Complete"	Done	Confirm and celebrate

A phase is active when date_started is non-null and date_completed is null. setup_process === "begin" always means Phase 3 is needed regardless of progresses.

---

Phase 3 — Configure Setup (EDI Info, Connection, EDI Setup)

Only enter this phase when the active phase is "Acknowledge EDI Specifications" or "Confirm Test Setup Details", or setup_process === "begin".

3a. Fetch Current Config from SPS

Run in parallel to see what's already filled in:

# EDI Info
curl -s -H "Authorization: Bearer <SPS_TOKEN>" \
  "https://api.spscommerce.com/tnc-bridge/v2/companies/<PREPROD_ID>/setups/<tc_setup_uid>/edi-info/test"

# Connection
curl -s -H "Authorization: Bearer <SPS_TOKEN>" \
  "https://api.spscommerce.com/tnc-bridge/v2/companies/<PREPROD_ID>/setups/<tc_setup_uid>/connection/test"

# EDI Setup
curl -s -H "Authorization: Bearer <SPS_TOKEN>" \
  "https://api.spscommerce.com/tnc-bridge/v2/companies/<PREPROD_ID>/setups/<tc_setup_uid>/edi-setup/test"

3b. Build Configuration from Orderful Data

Using the Orderful EDI account data from Phase 1, construct the three payloads:

EDI Info (these values should be read only, you cannot chnage them):

{
  "interchange_qualifier": "<ISA qualifier, typically ZZ>",
  "interchange_id": "<Orderful ISA ID>",
  "gs_id": "<Orderful GS ID — usually same as ISA ID>",
  "test_interchange_qualifier": "<same qualifier>",
  "test_interchange_id": "<Orderful ISA ID>",
  "test_gs_id": "<Orderful GS ID>"
}

Connection — determine method using this priority:

1. If Orderful account has an AS2 channel → use AS2 with existing cert
2. If Orderful account has SFTP/FTP channels → use that
3. Default → VAN with name: "ECGRID" (lowest friction, SPS manages the network)

VAN (default):

{
  "connection_method_type": "VAN",
  "name": "ECGRID",
  "as2_id": null, "sps_as2_id": null, "algorithm": null,
  "encryption_method": null, "file_content": null, "file_name": null,
  "port": null, "url": null, "submitted_date": null
}

AS2 (if customer has AS2):

{
  "connection_method_type": "AS2",
  "as2_id": "<customer AS2 ID from Orderful>",
  "sps_as2_id": "SPSAS2",
  "url": "<customer AS2 endpoint URL>",
  "name": "EXISTING",
  "algorithm": null,
  "encryption_method": null,
  "file_name": "<cert filename if available>",
  "file_content": "<base64 cert if available>",
  "port": null,
  "submitted_date": null
}

SFTP/FTP:

{
  "connection_method_type": "SFTP",
  "name": "<hostname>",
  "url": "sftp://<hostname>",
  "port": 22,
  "as2_id": null, "sps_as2_id": null, "algorithm": null,
  "encryption_method": null, "file_content": null, "file_name": null,
  "submitted_date": null
}

EDI Setup:

{
  "test_edi_gs_id": "<Orderful GS ID>",
  "test_edi_isaid": "<Orderful ISA ID>",
  "test_edi_qualifier": "<qualifier, typically ZZ>"
}

3c. Present Configuration Plan

Show the user exactly what will be submitted:

## SPS Configuration Plan — <Trading Partner Name>

### Orderful Source Data
- Org: <name>
- ISA ID: <id>  (qualifier: <qualifier>)
- GS ID: <id>
- Connection detected: <VAN / AS2 / SFTP>

### EDI Info (to submit)
[formatted table of fields]

### Connection (to submit)
[method + key fields]

### EDI Setup (to submit)
[formatted table of fields]

### Gaps / Assumptions
[anything not pulled from Orderful that was defaulted]

If anything critical is missing (e.g., AS2 cert content, SFTP hostname), list it here and ask the user before proceeding.

3d. Submit Configuration (after approval)

PUT all three sections:

# EDI Info
curl -s -X PUT \
  -H "Authorization: Bearer <SPS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '<EDI_INFO_JSON>' \
  "https://api.spscommerce.com/tnc-bridge/v2/companies/<PREPROD_ID>/setups/<tc_setup_uid>/edi-info/test"

# Connection
curl -s -X PUT \
  -H "Authorization: Bearer <SPS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '<CONNECTION_JSON>' \
  "https://api.spscommerce.com/tnc-bridge/v2/companies/<PREPROD_ID>/setups/<tc_setup_uid>/connection/test"

# EDI Setup
curl -s -X PUT \
  -H "Authorization: Bearer <SPS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '<EDI_SETUP_JSON>' \
  "https://api.spscommerce.com/tnc-bridge/v2/companies/<PREPROD_ID>/setups/<tc_setup_uid>/edi-setup/test"

Then submit via OPTIONS:

curl -s -X OPTIONS \
  -H "Authorization: Bearer <SPS_TOKEN>" \
  "https://api.spscommerce.com/tnc-bridge/v2/companies/<PREPROD_ID>/setups/<tc_setup_uid>/submission/test"

A 200 response means submission accepted. Inform the user that SPS will now configure the test setup on their side — this is a manual SPS process that can take hours to days.

---

Phase 4 — Waiting for SPS Approval

When the active phase is "SPS Configuring Test Setup":

Re-fetch the setup list and inspect progresses:

curl -s -H "Authorization: Bearer <SPS_TOKEN>" \
  https://api.spscommerce.com/tnc-bridge/setup/v2

Ready for document details when ALL of:

• "SPS Configuring Test Setup" has date_completed non-null
• "Confirm Test Document Details" has date_started non-null and date_completed null

Report the current state. If not yet approved, tell the user to check back later and confirm Phase 5 instructions in advance so they know what to expect. Do not proceed to Phase 5 until SPS approval is confirmed.

---

Phase 5 — Document Details

Only enter this phase when "Confirm Test Document Details" is active.

5a. Fetch Document Details Form

curl -s -H "Authorization: Bearer <SPS_TOKEN>" \
  "https://api.spscommerce.com/tnc-bridge/setup/v2/<tc_setup_uid>/document_details"

The response has two sections:

• company_details.fields[] — fields that apply to the company (e.g., Vendor Number)
• item_details.items[] — one item per test product, each with fields[]

For each field note: id, field_name, edi_location, usage ("Mandatory" or "Optional"), value (current value or null), note, min_length, max_length.

5b. Source Products from Orderful

Try to fetch real products from the customer's Orderful account:

curl -s \
  -H "Authorization: Bearer <ORDERFUL_API_TOKEN>" \
  "https://api.orderful.com/v2/products?limit=25&ediAccountIds=<ORDERFUL_EDI_ACCOUNT_ID>&isForScenarioTesting=true"

Note: Ask the user for their Orderful API token if you don't have it, or ask them to provide the product data directly if they prefer.

If products are returned:

• Show them to the user (name, SKU, description, dimensions/weight if present)
• If there are multiple, ask which ones to use for testing (one per item_details.items[])
• Map product fields to document detail fields (SKU → item/UPC fields, name → description, etc.)

If no products are returned: Tell the user: "No products found in your Orderful account. You can either:

1. Add products in Orderful first (recommended — they'll be reusable for future certification setups)
2. Let me generate placeholder test data that meets SPS requirements for this setup"

Explain that adding real products makes future setups faster. If they want to proceed with placeholders, generate realistic test data:

• Vendor Number: a plausible alphanumeric string
• UPC/GTIN: a valid-format 12-14 digit number
• Item description: a generic but plausible product name
• Cost/price: reasonable dollar values
• Dimensions/weight: plausible values in expected units

5c. Fill and Submit Document Details

Map product data to each mandatory field. For optional fields with no value, leave as null unless a note hints at what to enter.

Present the completed document details to the user for review before submitting.

After approval, PUT the completed structure:

curl -s -X PUT \
  -H "Authorization: Bearer <SPS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '<FULL_DOCUMENT_DETAILS_JSON>' \
  "https://api.spscommerce.com/tnc-bridge/setup/v2/<tc_setup_uid>/document_details"

Confirm a successful response. The setup will advance to the "Begin Testing" phase after SPS processes the document details.

---

Phase 6 — Scenarios & Test Monitoring

6a. Fetch Scenarios

curl -s -H "Authorization: Bearer <SPS_TOKEN>" \
  "https://api.spscommerce.com/tnc-bridge/setup/v6/<tc_setup_uid>/scenarios"

The response is a flat array of steps — group them by scenario_name to reconstruct the scenario hierarchy. For each scenario, the steps represent the expected EDI document flow (e.g., 850 → 855 → 856 → 810 for Order to Cash).

Present a summary table:

## Scenario Status — <Trading Partner Name>

| Scenario | Documents | Status |
|---|---|---|
| Order to Cash | 850 → 855 → 856 → 810 | 2/4 PASS |
| Cancellations | 850 → 860 | 0/2 NOT_STARTED |

For each FAIL or NOT_STARTED step, note the doctype, docname, step_id, and parcel_id.

6b. Fetch Test Results for Failing Steps

For each step that is FAIL or needs attention:

# URL-encode the scenario_name
curl -s -H "Authorization: Bearer <SPS_TOKEN>" \
  "https://api.spscommerce.com/tnc-bridge/setup/v3/<tc_setup_uid>/<encoded_scenario_name>/document/<doctype>/results"

From the response, find the latest result (highest submitted_date) and extract:

• status — PASS / FAIL / NOT_STARTED / IN_PROGRESS
• errors[] — each error has message, segment, position, and sometimes expected/actual

6c. Fetch Raw EDI for Debugging (if needed)

If the user wants to see the actual EDI document that was submitted:

curl -s -H "Authorization: Bearer <SPS_TOKEN>" \
  "https://api.spscommerce.com/tnc-bridge/parcel/<parcel_id>/data"

Use the parcel_id from the failing step in the scenario list.

6d. Present Test Report

For each failing scenario/step, show:

• The validation errors with plain-English explanation
• The specific segment and position where the failure occurred
• What Orderful's outbound transaction likely sent vs. what SPS expected
• Actionable next steps (e.g., "ISA05 qualifier mismatch — update EDI info to use ZZ instead of 01")

Cross-reference errors with the Orderful EDI account configuration where possible using MCP data.

---

Key Principles

PREPROD_ID is not company_uid. user.preprod_id from the setup list response is the caller's own company ID and is required for all EDI Info / Connection / EDI Setup endpoints. company_uid on each setup is the trading partner's ID and is not used in config endpoints.

Phase 3 (doc details) requires SPS approval. Never attempt to submit document details before "SPS Configuring Test Setup" has a non-null date_completed. The endpoint will appear to succeed but the data won't be used.

Orderful MCP first. Always pull the customer's EDI account data via get_account_context before constructing SPS configuration. Context-aware values from Orderful are far more accurate than asking the user to type them manually.

Plan before executing. Present a clear plan with all values before making any PUT or OPTIONS calls. For document details especially, show the user exactly what fields will be populated.

Real products over fake. Encourage real Orderful products — they make future setups faster and produce more realistic test documents. Offer placeholder data as a fallback only.

VAN is the safe default. When connection method is unclear, default to VAN/ECGRID. It's the lowest-friction option and avoids needing AS2 certificates or FTP credentials.

---

Quick Reference — SPS Endpoint Map

# Auth + Setup List
GET  /tnc-bridge/setup/v2

# Per-setup config — use PREPROD_ID (NOT company_uid) as {companyId}
GET  /tnc-bridge/v2/companies/{companyId}/setups/{setupId}/edi-info/test
PUT  /tnc-bridge/v2/companies/{companyId}/setups/{setupId}/edi-info/test
GET  /tnc-bridge/v2/companies/{companyId}/setups/{setupId}/connection/test
PUT  /tnc-bridge/v2/companies/{companyId}/setups/{setupId}/connection/test
GET  /tnc-bridge/v2/companies/{companyId}/setups/{setupId}/edi-setup/test
PUT  /tnc-bridge/v2/companies/{companyId}/setups/{setupId}/edi-setup/test

# Submit for SPS review
OPTIONS /tnc-bridge/v2/companies/{companyId}/setups/{setupId}/submission/test

# Document details — uses setupId only, no companyId
GET  /tnc-bridge/setup/v2/{setupId}/document_details
PUT  /tnc-bridge/setup/v2/{setupId}/document_details

# Scenarios (flat step list — group by scenario_name)
GET  /tnc-bridge/setup/v6/{setupId}/scenarios

# Test results per scenario+doctype (URL-encode scenario_name)
GET  /tnc-bridge/setup/v3/{setupId}/{scenario_name}/document/{doctype}/results

# Raw EDI parcel content
GET  /tnc-bridge/parcel/{parcel_id}/data

Quick Reference — Orderful Endpoints

# Products (use Orderful API token)
GET  /v2/products?limit=25&ediAccountIds={ediAccountId}&isForScenarioTesting=true

ID Reference

Variable	Source	Used For
PREPROD_ID	user.preprod_id from GET /tnc-bridge/setup/v2	{companyId} in all config endpoints
tc_setup_uid	Each setup object in the setup list	{setupId} in all setup-specific endpoints
company_uid	Each setup object	Trading partner's ID — NOT used in config endpoints
parcel_id	Scenario step data	Fetching raw EDI document content
scenario_name	Scenario step data	Document results endpoint (URL-encode)
doctype	Scenario step data	Document results endpoint (e.g. "850", "856")

Typical Phase Sequence

begin → Acknowledge EDI Specs (instant)
      → Confirm Test Setup Details    ← Phase 3 (you fill this)
      → SPS Configuring Test Setup    ← Phase 4 (wait for SPS)
      → Confirm Test Document Details ← Phase 5 (you fill this)
      → Begin Testing
      → Testing In Process            ← Phase 6 (monitor + debug)
      → Confirm Production Setup Details
      → SPS Configuring Production Setup
      → Testing & Certification Complete ✓