SanMar API toolkit

intent

Use this skill whenever you need to read from or write to SanMar for apparel sourcing, pricing, ordering, or order tracking. The toolkit wraps SanMar's SOAP web services and PromoStandards order-shipment notification service as deterministic, JSON-in / JSON-out CLI actions. Search products by style/color/size, check real-time warehouse inventory, pull customer-specific pricing, validate shopping carts before checkout, submit and track purchase orders, parse uploaded PO PDFs into structured drafts, and auto-resolve marketing color names (e.g. "Athletic Heather") to SanMar mainframe codes (e.g. "ATHHTHR") when the inventory or pricing API rejects the consumer-facing label. Do not use this for other apparel vendors (S&S, Alpha, etc.). Never invent SanMar request shapes from prose; always call the deterministic actions.

inputs

Environment variables (or inline in stdin JSON, where they take precedence):

• SANMAR_CUSTOMER_NUMBER (string, secret, required for most calls) , your SanMar account number. Can also be passed as customer_number in stdin JSON.
• SANMAR_USERNAME (string, secret, required for most calls) , web-services login (usually an email). Can also be passed as username in stdin JSON.
• SANMAR_PASSWORD (string, secret, required for most calls) , web-services password. Can also be passed as password in stdin JSON.
• SANMAR_ENV (string, optional, defaults to production) , set to development to route PO submission to the test-ws endpoint instead. Can also be passed as environment in stdin JSON.
• SANMAR_FTP_USERNAME (string, secret, optional, defaults to SANMAR_CUSTOMER_NUMBER) , SFTP login for mainframe-color resolution. Separate from web-services username.
• SANMAR_FTP_PASSWORD (string, secret, optional, required only for color resolution) , SFTP password, different from web-services password. Can also be passed as ftp_password in stdin JSON.
• SANMAR_FTP_HOST (string, optional, defaults to ftp.sanmar.com) , SFTP server hostname.
• SANMAR_FTP_PORT (string, optional, defaults to 2200) , SFTP server port.
• SANMAR_FTP_CACHE_DIR (string, optional, defaults to /tmp/sme-sanmar-cache) , local directory for cached SDL CSV feeds (24h TTL; SanMar refreshes nightly).

Python runtime:

• Python 3.11+ (python3 binary on PATH).
• requests>=2.28 (required).
• pypdf>=4.0 (required only for parse-po-pdf; loaded lazily).
• paramiko>=3.0 (required only for lookup-mainframe-color and color auto-resolve fallback; loaded lazily).

External connection:

• SanMar SOAP web services (production: https://www.sanmar.com/SanMarWebService/*; development: https://test-ws.sanmar.com:8080/SanMarWebService/*). Calling IP must be allowlisted by SanMar.
• SanMar SFTP server (ftp.sanmar.com:2200 or custom SANMAR_FTP_HOST:SANMAR_FTP_PORT) for SDL color feed downloads. Separate SFTP credentials required.
• PromoStandards order-shipment notification service for tracking and shipment status (reuses SOAP username/password).

procedure

All calls follow the same pattern:

echo '<json-input>' | python3 scripts/sanmar.py <action>

The action is the first CLI argument; the JSON input object comes on stdin. Output is always a single JSON object on stdout. On error, the exit code is non-zero and stdout is {"error": {"type": "<error_type>", "message": "...", ...}}.

1. Search products by style/color/size

Input JSON: {"style": "TST001", "color": "Navy", "size": "M"}

Procedure:

1. Parse stdin JSON. Extract style (required), color (optional), size (optional).
2. Validate that style is a non-empty string. If not, return validation_error.
3. Load credentials from SANMAR_CUSTOMER_NUMBER, SANMAR_USERNAME, SANMAR_PASSWORD env vars, or from stdin JSON fields customer_number, username, password. If credentials are missing, return config_error.
4. Build SOAP request for SanMarProductInfoServicePort with the three credential fields and the search parameters.
5. POST to the product-info endpoint (production or development based on SANMAR_ENV / environment).
6. Parse SOAP XML response. If errorOccurred=true or a SOAP fault, return api_error with retryable: false for auth/schema errors, retryable: true otherwise.
7. Extract product records from the response. Each includes style, color, size, description, image_url, and other metadata.
8. Return {"products": [...], "count": N} on success.

Output: JSON array of product objects, one per match. Each product has style, color, size, description, image_url, price (if available), and other metadata.

---

2. Check real-time inventory for a style/color/size combination

Input JSON: {"style": "TST001", "color": "Athletic Heather", "size": "M", "auto_resolve_color": true}

Procedure:

1. Parse stdin JSON. Extract style (required), color (required), size (required), auto_resolve_color (optional, defaults to true).
2. Validate that all three are non-empty strings. If not, return validation_error.
3. Load credentials (same as step 3 above). If missing, return config_error.
4. Build SOAP request for SanMarWebServicePort (inventory endpoint) with style, color, size, and credentials.
5. POST and parse response. If a SOAP fault or errorOccurred=true, check the error message.
6. If the error suggests "unknown color" or empty result, and auto_resolve_color: true, proceed to step 7. Otherwise, return api_error.
7. (Color auto-resolve) Call lookup-mainframe-color with the same style, color, size and force_refresh: false. On match, extract the mainframe_color code.
8. Retry the inventory query in step 4 with the mainframe color in place of the marketing color. If still empty or error, return the original error.
9. Extract quantity and warehouse info from the response. Return {"quantity": N, "warehouse": "...", "mainframe_color_used": "..."} if auto-resolve was triggered, or just {"quantity": N, "warehouse": "..."} otherwise.

Output: {"quantity": <int>, "warehouse": "<warehouse_name>", "mainframe_color_used": "<MAINFRAME_CODE>"} (latter field only if color was resolved). Quantity is the on-hand count at the primary warehouse.

---

3. Get pricing for one or more lines (style/color/size combos)

Input JSON: {"lines": [{"style": "TST001", "color": "Navy", "size": "M", "quantity": 50}, ...], "auto_resolve_color": true}

Procedure:

1. Parse stdin JSON. Extract lines (required, non-empty array), auto_resolve_color (optional, defaults to true).
2. Validate each line: style, color, size are required strings; quantity is optional (default 1). Return validation_error if any fail.
3. Load credentials. If missing, return config_error.
4. For each line, attempt a SOAP call to SanMarPricingServicePort with style, color, size, quantity, and credentials.
5. Collect all pricing responses. If any line fails with "unknown color" or zero results, and auto_resolve_color: true, proceed to step 6 for that line only.
6. (Color auto-resolve) Call lookup-mainframe-color for the failing line. On match, retry the pricing query with the mainframe color.
7. Aggregate all responses: each line in the output includes style, color, size, quantity, unit_price, inventory_key (opaque token used by submit), size_index (integer ID for the size), and mainframe_color_used if resolved.
8. Return {"lines": [...], "quote_id": "...", "expires_at": "..."}

Output: {"lines": [{...}, ...], "quote_id": "<quote_id>", "expires_at": "<ISO_8601_timestamp>"}. Each line includes style, color, size, quantity, unit_price (float), inventory_key, size_index, and optionally mainframe_color_used.

---

4. Validate a cart before submitting to SanMar

Input JSON: {"purchase_order": {"po_number": "PO-001", "ship_to": {...}, "lines": [{...}], ...}}

Procedure:

1. Parse stdin JSON. Extract purchase_order (required object).
2. Validate the PO schema: required fields are po_number (string), ship_to (object with name, address, city, state, zip, country), lines (non-empty array). Each line must have style, color, size, quantity, unit_price. Return validation_error if any are missing or malformed.
3. Load credentials. If missing, return config_error.
4. Build SOAP request for SanMarPOServicePort validation endpoint (no actual submit). Include all PO fields and credentials.
5. POST and parse response. If errorOccurred=true, return api_error with the SanMar message (e.g. "style not found", "quantity exceeds inventory").
6. Return {"ok": true} if validation passes, or {"ok": false, "errors": [...]} if SanMar reports issues.

Output: {"ok": true} on success, or {"ok": false, "errors": [{"field": "...", "message": "..."}]} if validation fails.

---

5. Submit a purchase order to SanMar (side-effecting write)

Input JSON: {"purchase_order": {...}, "confirm": true}

Procedure:

1. Parse stdin JSON. Extract purchase_order (required) and confirm (required boolean).
2. Validate the PO schema (same as step 2 in procedure 4). Return validation_error if malformed.
3. If confirm: false, do a dry-run: build and print the SOAP envelope (for human inspection) and exit with {"dry_run": true, "soap_envelope": "<xml...>"}. Do not POST.
4. If confirm: true, load credentials. If missing, return config_error.
5. Build SOAP request for SanMarPOServicePort submit operation. Route to production endpoint (default) or test-ws endpoint (if SANMAR_ENV=development / environment: "development").
6. POST and parse response. If a SOAP fault or errorOccurred=true, return api_error with retryable: false for auth/schema, retryable: true for transient errors (e.g. timeout, XML parse error).
7. Extract po_confirmation_number and order_date from response.
8. Return {"po_confirmation_number": "...", "order_date": "<ISO_8601>", "status": "submitted"}.

Output: Dry-run: {"dry_run": true, "soap_envelope": "<xml>"}. Live: {"po_confirmation_number": "<conf_num>", "order_date": "<ISO_8601>", "status": "submitted"}.

---

6. Check order status or get tracking info

Input JSON (for status): {"po_number": "PO-001"} or {"po_confirmation_number": "CONF-123"} Input JSON (for tracking): {"po_number": "PO-001"} for the get-tracking action

Procedure:

1. Parse stdin JSON. Extract po_number or po_confirmation_number (one required).
2. Load credentials. If missing, return config_error.
3. Build SOAP request for OrderShipmentNotificationServiceBinding (PromoStandards) with the PO identifier and credentials.
4. POST and parse response. If fault or error, return api_error.
5. Extract shipment records: each has ship_date, tracking_number, carrier, estimated_delivery, line_items (style/color/size/quantity/shipped_quantity).
6. Return {"po_number": "...", "shipments": [...], "status": "in_transit"} or similar.

Output: {"po_number": "...", "shipments": [{"ship_date": "<ISO_8601>", "carrier": "...", "tracking_number": "...", "estimated_delivery": "<ISO_8601>", "line_items": [...]}]}.

---

7. Parse a PDF purchase order into a structured draft

Input JSON: {"pdf_path": "/path/to/po.pdf"}

Procedure:

1. Parse stdin JSON. Extract pdf_path (required string).
2. Validate that the file exists and is readable. Return validation_error if not.
3. Import pypdf (if missing, return a clear error: "pypdf>=4.0 required for parse-po-pdf").
4. Open the PDF and extract all text pages. Parse page content using heuristics (regex, patterns) to locate:
   • PO number (look for "PO", "Order", "Number" labels).
   • Order date (MM/DD/YYYY, YYYY-MM-DD, or text month patterns).
   • Ship method (Ground, 2-Day, Overnight, etc.).
   • Ship-to address (block of lines with name, street, city, state, zip).
   • Line items (table rows with style, color, size, quantity, unit price). Each row must have at least style and quantity.
5. Populate draft_for_submit, a purchase_order object ready for create-purchase-order, only if the parse confidence is high (all fields present, no major ambiguities). Otherwise, set draft_for_submit: null.
6. Collect any ambiguous or low-confidence extractions in warnings[] (e.g. "Found 3 possible PO numbers: XXX, YYY, ZZZ; using XXX").
7. Return {"po_number": "...", "order_date": "<ISO_8601>", "ship_method": "...", "ship_to": {...}, "lines": [...], "warnings": [...], "draft_for_submit": null or {...}}.

Output: {"po_number": "<str>", "order_date": "<ISO_8601>", "ship_method": "<str>", "ship_to": {"name": "...", "address": "...", "city": "...", "state": "...", "zip": "...", "country": "US"}, "lines": [{"style": "...", "color": "...", "size": "...", "quantity": <int>, "unit_price": <float>}], "warnings": [<str>], "draft_for_submit": <object or null>}. Always show the parsed PO back to the user for approval before submitting.

---

8. Lookup mainframe color code for a marketing color name

**Input JSON