Rails Sandbox

Rails Sandbox is a faithful mock of the public 2026-01 Integrations API for collision-repair parts procurement — the same RPC-over-POST wire shape, OAuth install flow, Authorization: Bearer + Partly-Integration-ID headers, and HMAC-SHA256 signed webhooks — served together with these docs as one deploy. It runs a real, seeded collision-repair scenario (a 2019 Toyota Corolla front-end job) so you can drive the whole lifecycle, from opening a job to a confirmed order, against live endpoints with no setup. Two clearly-labelled extensions (place_procurement, reconcile_invoice) carry the buyer loop one step past the public contract; everywhere they appear they are marked as proposed extensions, never passed off as the real 2026-01 contract.

This is not a real vendor's own documentation. It is a Rails-compatible sandbox: a reference build that mirrors a real developer experience so you can prototype against a stable contract.

Built for two kinds of reader

• Human developers building an integration by hand — read the prose, copy the curl, ship.
• Coding agents building an integration from these docs alone — every page is also served as raw markdown, every example is copy-paste-correct against the deployed sandbox, and every fact needed to complete an integration is reachable from /llms.txt.

The same content serves both. There is no separate "agent" content fork — the markdown source is the page.

Start here

1. Quickstart — zero to a confirmed procurement in copy-paste steps, including obtaining sandbox credentials programmatically via the OAuth install flow (no dashboard, no human step).
2. Authentication — the install flow, the two required headers, pre-loaded demo credentials, and every coded auth/install failure.
3. Lifecycle — the procurement spine: which wire method (and MCP tool) drives each state transition, ending at order_confirmed.
4. Webhooks — the signed-event envelope, the 5-minute replay window, dedup semantics, and complete HMAC-SHA256 verification code in TypeScript and Python.
5. Errors — every error kind: its wire shape, meaning, retryability, and the prescribed recovery. Written to be read by LLMs as well as humans.
6. API Reference — generated from the OpenAPI spec: every method's request/response schema, a runnable example, and every error it can return.
7. For AI Agents — connect the deployed MCP servers (the runtime Rails MCP and the docs MCP) — or a local stdio install — and drive the lifecycle live.

The procurement lifecycle, in one line

prepare_vehicle → open_repair_job → identify_parts → recommend_basket → place_procurement ⚠ → confirm_procurement → reconcile_invoice ⚠

the public 2026-01 lifecycle terminates at order_confirmed (the result of confirm_procurement). The two steps marked ⚠ — place_procurement and reconcile_invoice — are proposed extensions beyond that contract; see Lifecycle. Re-read state with get_job / track_procurement rather than assuming it.

Machine-readable surfaces

Built for agents and tooling, not just browsers:

• /llms.txt — the llms.txt index: one line and a link per page. The acceptance bar is that everything needed to build an integration is reachable from here alone.
• /llms-full.txt — every page's markdown, concatenated into one document.
• /openapi.json — the 2026-01 OpenAPI spec at a stable URL; the API Reference is generated from it.
• Per-page markdown — append .md to any page URL, or send Accept: text/markdown, to get the raw source markdown instead of rendered HTML. No lossy conversion — it is the same file these docs are built from.

One call to confirm it's live

The install endpoint is the only unauthenticated method, so it needs no credentials. This rejects an unknown client (the expected failure for placeholder values) — proof the contract surface is up:

curl -s -X POST \
  https://partifact-mock-rails.thanhvuttv.workers.dev/api/2026-01/integrations.insert \
  -H "Content-Type: application/json" \
  -d '{"client_id":"unknown","client_secret":"unknown","access_code":"unknown"}'
# -> {"type":"integration_not_found"}   (HTTP 404)

Every call follows this convention: POST https://partifact-mock-rails.thanhvuttv.workers.dev/api/2026-01/<dotted.method> with a JSON body. Authenticated methods additionally require Authorization: Bearer <api_key> and Partly-Integration-ID: <integration_id> — the Quickstart hands you both.

Fidelity & honesty

Faithful to the public 2026-01 contract; lightweight in implementation, not in contract shape. Two things to keep in mind, stated wherever they matter:

• No currency on the basket. The basket response (recommend_basket / repairer.jobs.baskets.latest.get) carries no currency field — currency is a procurement-level concept that appears later on the procurement and invoice (D52). Any tool that shows a currency on a basket offer has derived it as a presentation-layer label, not read it off the wire.
• place_procurement and reconcile_invoice are proposed extensions beyond the 2026-01 API — the public contract stops at order_confirmed. They are labelled as such everywhere they appear.

Where this sandbox simplifies versus a real production system, the relevant page says so.