sps

name

sps

description

Drive SPS Commerce Testing & Certification (the "tnc-bridge" API behind commerce.spscommerce.com/testing-and-certification) from the CLI — list active testing trading partners, read the full 9-phase workflow status, and read/act on the 5 testing steps (EDI Specifications, Test Setup Details, Test Document Details, Testing Scenarios, Production Setup Details) without the web portal. Use when the user says "check SPS", "SPS testing", "/sps", "what's the status of <partner> in SPS", "list our SPS testing partners", "investigate the SPS steps", "send the SPS test documents", or wants to read or advance an SPS certification project.

SPS Commerce — Testing & Certification (CLI)

The SPS Testing & Certification web app (commerce.spscommerce.com/testing-and-certification) is a module-federation micro-frontend (served in an iframe from web-assets.sps-cdn.com) whose data comes from an internal REST API at https://api.spscommerce.com/tnc-bridge ("tnc" = Testing aNd Certification). This skill calls that API directly — no portal/browser.

Unofficial. Not affiliated with SPS Commerce. Uses undocumented endpoints with your own account's token; behavior may change without notice.

Setup

1. Paste a bearer token into .env as SPS_TOKEN=… (copy .env.example; the file has the DevTools recipe). Tokens last ~1 hour — on HTTP 401, grab a fresh one.
2. Node 18+ (uses global fetch). company_id auto-resolves from your token; override with SPS_ACCOUNT_ID in .env or --company=<id>.

Auth & access model

• Auth header: Authorization: Bearer <token> (OAuth2 via auth.spscommerce.com, audience spscommerce.com).
• Identity: GET https://id.spsc.io/identity/users/me/ → user + org.
• Resolve company_id: GET {bridge}/internal/company_id/{orgId} → { "company_id": <id> }.
• Role matters. A normal supplier login is tnc:user and uses the /v3/setups, /setup/*, /v2/companies/* endpoints below. The /partnership/v1|v2/* endpoints are tnc:app_admin only (SPS staff) and return 403 for a tnc:user — don't use them.

Commands

S=~/.claude/skills/sps/sps.mjs
node $S whoami                 # identity / org
node $S partners               # active testing trading partners  (GET /v3/setups)
node $S status                 # all setups + 9-phase workflow progress + counts (GET /setup/v2)
node $S steps  [setupId]       # ALL of Steps 1–5 for a setup in one object  ← the big one
node $S specs  [setupId]       # Step 1: EDI Specifications
node $S setup-details [setupId]# Step 2: Test Setup Details (direction + contacts)
node $S documents [setupId]    # Step 3: Test Document Details (field-by-field spec + values)
node $S scenarios [setupId]    # Step 4: Testing Scenarios (doc chains + pass/fail)
node $S errors [setupId]       # Step 4: scenario errors / testing results
node $S prod-setup [setupId]   # Step 5: Production Setup Details (prod EDI ids)
node $S activity               # recent activity feed
# setupId is optional — auto-resolves when the account has exactly one active setup.

Write/action commands are gated behind --confirm (they send EDI to the partner / change state):

node $S acknowledge-specs [setupId] --confirm        # complete Step 1 (PUT .../specs/acknowledge)
node $S send-test [setupId] --all --confirm          # Step 4: Send (All) Test Documents
node $S put <path> --body '{...}' --confirm          # generic authorized write
node $S raw <METHOD> <path|url> [k=v...] [--body '{}'] # probe anything (non-GET needs --confirm)

Flags: --confirm --all --sandbox --env=test --company=<id>.

Validated endpoint map (relative to {bridge} = https://api.spscommerce.com/tnc-bridge)

c = supplier company_id (auto-resolved); s = tc_setup_uid (a setup/project id from partners).

Area	Method & path
Identity	GET https://id.spsc.io/identity/users/me/
company_id	GET /internal/company_id/{orgId}
Partner list	GET /v3/setups
Workflow status	GET /setup/v2 (9 phases + models/scenarios/documents counts)
Step 1 EDI Specs	GET /v2/companies/{c}/setups/{s}/edi-setup/test · …/edi-info/test
Step 2 Setup	GET /v2/companies/{c}/setups/{s}/setup-direction · GET /setup/{s}/details/sf_contacts?account_id={c}
Step 3 Documents	GET /setup/v2/{s}/document_details
Step 4 Scenarios	GET /setup/v5/{s}/scenarios (or /setup/v6/...) · GET /v3/setups/{s}/scenarios/errors/
Step 5 Production	GET /v2/companies/{c}/setups/{s}/edi-setup/prod
Activity	GET /activity/v2
Write — ack specs	PUT /v2/companies/{c}/setups/{s}/specs/acknowledge
Write — send test	POST /setup/v4/{s}/scenarios/submit · …/submit/all
Write — EDI ids	PUT /v2/companies/{c}/setups/{s}/edi-setup/test · …/edi-setup/prod
Write — details	PUT /setup/v3/{s}/details · PUT /setup/{s}/details/sf_contacts · PUT /partnership/v1/{x}/scenario_statuses
Admin-only (403 for tnc:user)	/partnership/v1/{profiles,platforms,company_names} · /partnership/v2/{companies,scenarios}

The 5 steps → workflow phases

GET /setup/v2 returns these phases in order (with date_started / date_completed):

1. EDI Specifications → Acknowledge EDI Specifications
2. Test Setup Details → Confirm Test Setup Details → SPS Configuring Test Setup
3. Test Document Details → Confirm Test Document Details
4. Testing Scenarios → Begin Testing → Testing In Process
5. Production Setup Details → Confirm Production Setup Details → SPS Configuring Production Setup → Testing & Certification Complete

Agent guidance

• Reads are safe — run freely to answer "what's the status / what's left / why is X failing".
• Writes are outward-facing (send EDI to the partner, advance the workflow). The client refuses them without --confirm; always confirm the specific action with the user before passing it.
• On 403 you're hitting an admin endpoint — switch to the tnc:user equivalent above.
• On 400 the endpoint wants a param you omitted (e.g. account_id, company_id) — check the map.