Skip to main content

Installation

You'll write and test your connector locally using the Connector Toolkit — a sandbox that mirrors the production framework exactly. Everything runs against in-memory dummy data backed by JSON files. No Nuntiq account, no network access, no AWS required.

Prerequisites​

  • Python 3.10 or newer. Check with python --version.
  • A code editor (VS Code, PyCharm, whatever you like).
  • ~10 MB of disk space.

1. Download the toolkit​

Download the latest toolkit (.zip)

Unzip it somewhere convenient — your projects folder, ~/dev/, anywhere. The zip extracts into a single directory named nuntiq-connector-toolkit-<version>/.

2. Create a virtual environment​

cd nuntiq-connector-toolkit-0.2.0
python -m venv .venv

Activate it:

.\.venv\Scripts\Activate.ps1

3. Install dependencies​

pip install -r requirements.txt

requirements.txt mirrors what's pre-installed in the production runtime — requests, httpx, pandas, pdfplumber, paramiko, authlib, and the rest. Anything that imports cleanly here will import cleanly in production.

4. Create your local settings file​

Copy the example:

cp settings.example.json settings.json

settings.json is your local config — secrets, non-secret settings, per-run parameters. It's gitignored, so your edits stay local. The shape matches what production injects from your connector instance's registration:

{
  "customer_number": "10000001",
  "secrets": {
    "api_token": "your-test-token"
  },
  "config": {
    "connector_name": "demo",
    "api_url": "https://api.example.com"
  },
  "job_params": {
    "lookback_days": 7
  }
}

You'll edit this every time you switch which integration scenario you're testing.

5. Run the menu​

python nuntiq.py

You should see something like:

================================================================
  Nuntiq — local connector sandbox
================================================================

Available connectors in connectors/:
   1. 01_use_settings           -- Read & log all three settings sources.
   2. 02_pull_suppliers         -- Inbound delta sync (timestamp cursor).
   3. 03_pull_invoices          -- Inbound delta sync (numeric_id cursor).
   4. 04_poll_lifecycle_messages -- Cross-invoice lifecycle delta poll.
   5. 05_push_invoices          -- Claim → push → ack → result loop.
   6. 06_export_invoices_csv    -- Read-only export with attachments.
   r. reset fixtures (restore from _seed/)
   q. quit

Pick a connector (number) >

Pick 1. You should see your settings echoed back. That confirms everything is wired up.

What's next​

Write your first connector →