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-<version>
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, authlib, msal, boto3, paramiko, zeep, pandas, pdfplumber, defusedxml, python-gnupg and the rest, at the same versions. Anything that imports cleanly here will import cleanly in production.

4. Create your local settings file​

Copy the example:

cp settings/example.json settings/my_integration.json

One file in settings/ is one connector instance: its secrets, its configuration and the job parameters of a run. Every file there except example.json is gitignored, so your edits stay local. The shape matches what production injects from the connector instance in the admin portal:

{
  "customer_number": "10000001",
  "secrets": {
    "api_token": "replace-me-with-a-real-token"
  },
  "config": {
    "connector_name": "demo_integration",
    "source_system": "DEMO_ERP",
    "ownership_mode": "managed",
    "api_url": "https://erp.example.com/api"
  },
  "job_params": {
    "since_override": null,
    "lookback_days": 7,
    "page_limit": 500
  }
}

config.source_system is the connector's identity on the API: records it writes carry it, and it changes and removes only records of that source. Without it the connector's connector_name is used. Keep one settings file per integration scenario you test.

5. Run the menu​

python nuntiq.py

Pick a settings file, then an entrypoint. You should see something like:

================================================================
  AP Receiving: local connector sandbox
================================================================

Available settings files in settings/:
   1. example  (template: copy and edit)
   2. my_integration
   q. quit

Pick a settings file (number) > 2

Using settings: my_integration
Available entrypoints in connectors/:
   1. 01_use_settings            -- Read secrets / config / job_params and log what was found.
   2. 03_pull_invoices           -- Pull invoices from an external system (delta-state cursor).
   3. 04_poll_lifecycle_messages -- Poll lifecycle events for invoices matching an ext_reference.
   4. 06_export_invoices_csv     -- Export pending invoices + attachments to a CSV in work_dir.
   5. get_custom_1               -- Mirror the ERP's cost centres into customer data table 1 (sync run).
   6. get_fx_rates               -- Load the customer's own exchange rates from an ERP.
   7. get_supplier               -- Pull suppliers (delta sync or full sync run), patch, delete by key.
   8. push_invoice               -- Post invoices (process engine or claim with leases), report results.
   s. switch settings file
   r. reset fixtures (restore from _seed/)
   q. quit

Pick an entrypoint (number) >

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

The file name is the entrypoint key: a file named after a standard key (get_supplier.py, push_invoice.py) runs with that key's permissions, as in production. A file with another name (01_use_settings.py) may only read invoices.

One run without the menus, for scripts and coding assistants:

python nuntiq.py my_integration get_supplier   # exit code 1 when the run fails

To try a connector template, copy its settings instead: cp templates/erp_sftp_key/settings.example.json settings/acme_files.json. Its connector_dir makes the runner use the template's folder instead of connectors/.

What's next​

Write your first connector →