Run a local development workspace

Use this guide to test the public API with synthetic customer and deal records. It requires access to the private Terramine source repository.

Building a customer integration? Start with the API quickstart using your workspace URL and service key.

Get the scripts

The launcher imports application code and test fixtures. Clone the complete repository; the script cannot run on its own.

For developers who already have repository access:

git clone git@github.com:dmitriisorokin88/spareparts-sales-agent.git
cd spareparts-sales-agent
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txt

The launcher is scripts/integration_pilot.py. Its fixtures are in tests/, and its application dependencies are in server/. GitHub requires repository access to open the source link.

Start the local workspace

Start a local PostgreSQL 16 server with permission to create a database and roles. From the repository root with the virtual environment active, run:

TEST_DESK_POSTGRES_DSN=postgresql://postgres@127.0.0.1:5432/postgres \
  python scripts/integration_pilot.py --port 8765

The launcher creates an isolated database and two roles using the CloudDesk test fixtures. It prints a fresh loopback base URL, service key, synthetic customer ID and deal ID. Copy the service key into your local credential store; it is not saved in the repository. Only machine API paths are exposed. Browser owner controls and background jobs are disabled. Stop with Ctrl-C to delete the unique database and roles; after a forced kill, use the printed database name to clean them manually.

Set the workflow's base URL to the printed http://127.0.0.1:8765 when n8n runs on the host. With Docker Desktop, use http://host.docker.internal:8765 from n8n instead; this was verified against the loopback listener on this Mac. The synthetic customer name already matches the template. Use --smoke to verify lookup, draft creation and idempotent retry without starting the listener.

Run the workflow twice with the same service key, quote_request_id and payload. Both runs should return the same draft ID and order number. Use a new quote_request_id for a new quotation request. The local workspace has no business-event delivery; use a configured tenant to test signed webhooks.

For a host curl check, set PILOT_API_KEY to the printed key and PILOT_DEAL_ID to the printed deal ID locally, then run:

curl --fail-with-body \
  -H "Authorization: Bearer $PILOT_API_KEY" \
  "http://127.0.0.1:8765/api/v1/crm/deals/$PILOT_DEAL_ID"