champro-api

CHAMPRO API

CHAMPRO publishes PromoStandards services, and the promostandards skill already drives them. This skill is for the parts that standard cannot reach for this supplier — which turns out to be most of the order lifecycle.

Why this exists

CHAMPRO's registry entry lists exactly five endpoints. Run echo '{"config":"Champro"}' | python3 ../promostandards/scripts/ps.py capabilities and you get PRODUCT 2.0.0, PPC 1.0.0 and PO 1.0.0 — plus MED 1.1.0 and Company Data, which that skill does not implement. There is no INV service at any version, no ODRSTAT and no OSN, and every endpoint registers test_url: "".

That leaves four holes, and each is load-bearing:

Keep using promostandards for CHAMPRO product data and pricing. Style, color, size, description and price breaks all come from PRODUCT 2.0.0 and PPC 1.0.0, and this skill deliberately does not duplicate them.

Three things that will bite you

HTTP 200 does not mean it worked. Verified against the live API: a bad key returns 200 from every endpoint, with the failure buried under a different key name each time — Error on ProductInfo and OrderStatus, ResponseMessage on Inventory, RequestErrors[] on PlaceOrder, and nothing at all on the Custom Builder's GetOrderInfo, which answers with a bare []. Those captures are checked in at assets/fixtures/auth_failures.json and the tests assert this client treats every one as a failure. Never write a raw call against these endpoints that branches on the status code.

A rejected order is not the same as no order. PlaceOrder answers a partially-valid request by creating the suborders it liked and reporting errors for the rest — CHAMPRO's own documented example does exactly this, rejecting two SKUs for inventory while cutting two real suborders. There is no cancel endpoint and no idempotency key, so resending is how you get duplicate garments. place-order classifies this as partial and exits 3 (escalation_required) with the suborder ids that now exist. Resubmit only the failed lines, as a new order. Never the whole request.

Sandbox is a URL, not a flag. /api/Order/PlaceOrder is real; /api/OrderSandBox/PlaceOrder is not. Worse, /api/OrderSandBox/ is a catch-all that routes every path to the sandbox place-order, while /api/Order/ correctly 404s — verified live. So client.py never assembles an order URL from caller input: place_order() takes a boolean and picks the whole literal path. production: true is the only way to reach the real host, and it is not the default.

Two keys, and they fail quietly

Both are generated on Account & Contact Info, and swapping them produces no error message: GetOrderInfo returns [] and GetFile returns 404 — indistinguishable from an empty design and an unknown session. cb-get-design therefore reports resolved: false with an explicit note rather than "0 items".

PlaceOrder additionally requires the calling IP to be on the account's allowlist (error code 15); reads do not. On a hosted agent the egress address is not the container's own and can change between runs. Run check-access first — it prints the IP to paste into the allowlist and tells an invalid key apart from an un-allowlisted one.

Actions

echo '' | python3 scripts/champro.py 

The action is argv[1], arguments are a JSON object on stdin, and the result is one JSON object on stdout — or {"error": {...}} with a non-zero exit. Credentials come from the environment or inline (api_customer_key, cb_customer_key), so they are omitted from the tables below.

Setup

Catalog — the MOQ / lead-time gap in PPC

Inventory — no PromoStandards INV service exists for CHAMPRO

Orders — no PromoStandards PO test endpoint exists for CHAMPRO

Tracking — no PromoStandards ODRSTAT or OSN service exists for CHAMPRO

Custom Builder — no PromoStandards equivalent in any spec

Reference

Run python3 scripts/champro.py with no action for the full list.

Rules that matter

Validate before you send, because you cannot un-send. place-order runs every local rule first and refuses on a blocking finding. Pass product_masters and it also checks SKUs, MOQ increments and lead-time names against ProductInfo; without it those checks report as skipped, never as passed — "not checked" and "checked and fine" must not look alike to a caller about to place an order.

MOQ is an increment, not a floor. With MOQCustom: 12, a quantity of 18 is rejected (error 25) even though it exceeds the minimum. The increment applies to the product-master total across the order's lines, which is why a roster of 6 + 6 is fine and 12 + 6 is not.

Two gates on every write, guarding different mistakes. confirm: true means "send it"; production: true means "send it to the real host". They are independent, and the default of both is the safe one. A sandbox order costs nothing — CHAMPRO purges sandbox orders older than 30 days — so rehearse there first, every time.

One order is entirely STOCK or entirely CUSTOM (error 07). A stock line carries a warehouse; a custom line carries roster fields, and the order carries a lead_time and a proof_file_url. split-mixed-cart separates a mixed cart into two orders with suffixed PO numbers, since two orders cannot share one PO.

Follow suborders, not the PO. One order can produce several suborders, one per fulfilling warehouse, each with its own SubOrderID that ships and tracks independently. get-order-status takes those ids; asking about only the first reports "shipped" while the rest is still in production. track-order takes a place-order result and follows all of them.

Unreadable is not zero. An inventory quantity that will not parse stays None and the row is flagged has_unreadable_quantity, because "we could not read the stock level" and "there is none" drive opposite decisions.

Third-party and collect shipping need a payer account. Twenty of the forty published shipping methods bill someone other than your CHAMPRO account, and those require shipping_customer_account. validate-order enforces it; a method name outside the published list is rejected with near-matches.

CHAMPRO fetches your proof file server-side. A CUSTOM order's proof_file_url must be a publicly reachable PDF/JPG/JPEG/PNG (errors 01 and 02). A cb-get-file URL carries your embed key and will not work there — download the proof, host it, and pass that URL.

CHAMPRO does not validate addresses; UPS does. Ship-to must satisfy UPS address rules or the order fails verification (errors 06 and 24). Validate before submitting.

Reference

• references/promostandards_gaps.md — what CHAMPRO publishes, what it does not, and the evidence for each gap
• references/api_reference.md — every endpoint, field and error code, with the observed-vs-documented differences
• references/custom_builder.md — the embed, the design-session lifecycle, and the order methods
• references/examples.md — end-to-end flows
• scripts/_selftest.py — offline fixture tests, no network or credentials. Run it after any change: python3 scripts/_selftest.py