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. The downloadable customer kit offers a Python standard-library rehearsal without repository access or PostgreSQL; this developer launcher runs the actual hosted API against a disposable local database.

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, try http://host.docker.internal:8765 from n8n instead. Connectivity to a host loopback listener depends on your Docker configuration; this address was verified on one development Mac, and is not a guarantee for other hosts. If it is unreachable, run n8n on the host. Keep the launcher bound to loopback; it is not a production server. The synthetic customer name already matches the template. Set crm_deal_id to the printed deal ID so the draft references the synthetic deal; the template value is only a placeholder. 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"