Advanta Quickstart

Reference implementation showing how to integrate Advanta APIs in ~150 lines of Node.

Goal: a bank engineer can clone this repo and have a working integration against the sandbox in under 10 minutes.

What this demonstrates

Four routes, four moving parts of the Advanta platform:

Route	What it does	Advanta endpoint hit
POST /api/connect	Creates a Connect session for an SME → returns a URL the SME opens to connect their ERP	POST /v1/connect/sessions
POST /api/webhooks/advanta	Receives signed webhooks (connection.completed, invoice.created, etc.) and updates local state	(incoming from Advanta)
GET /api/score/:nif	Generates a risk score for an SME (0-100 + ESG + recommended limit/spread)	POST /v1/score
GET /api/erp/:connectionId/invoices	Pulls invoices from the SME's connected ERP	GET /v1/erp/{cid}/invoices

Plus a tiny HTML dashboard at / so you can watch state change in real time.

Quick start

git clone github.com/advanta/quickstart  &&  cd quickstart
cp .env.example .env
# Edit .env and paste your sandbox key (get one at https://tech.advanta.pt/sandbox)
npm install
npm start

Open http://localhost:3000.

Try the happy path

# 1. Create a Connect session for "Construções Ibéricas"
curl -X POST localhost:3000/api/connect \
  -H 'Content-Type: application/json' \
  -d '{"nif":"509123456","name":"Construções Ibéricas","email":"joao@construcoes.pt"}'

# Response: { "connect_url": "https://connect.advanta.pt/cs_2026_xY7p9R8q...", "session_id": "..." }
# → open the connect_url in a browser. In sandbox mode, you can skip OAuth and pick a test profile.

# 2. After the SME completes the flow, your /api/webhooks/advanta endpoint receives connection.completed.
# (For local testing, use a tunnel like ngrok or run the Advanta CLI webhook-forwarder.)

# 3. Now generate a score
curl localhost:3000/api/score/509123456
# → { "score": 78, "tier": "A-", "recommended_limit_eur": 240000, ... }

# 4. List the SME's open invoices
curl localhost:3000/api/erp/conn_2026_aB3xC9D1fK7p/invoices

Receiving webhooks locally

Webhooks come from sandbox.advanta.pt, so they need a public URL. Two options:

Option A — ngrok (any free account):

ngrok http 3000
# Note the public URL e.g. https://abc123.ngrok-free.app
# In the Advanta dashboard → Webhooks → add endpoint:
#   https://abc123.ngrok-free.app/api/webhooks/advanta

Option B — Advanta CLI (forwards events to localhost without a tunnel):

npx @advanta/cli webhooks listen --forward-to http://localhost:3000/api/webhooks/advanta

Production checklist

When you swap the sandbox key for a live one (sk_live_...):

• Replace the in-memory Map with your real DB
• Move webhook signing secret to a secure secret manager
• Add rate-limiting on /api/connect (we already do server-side, you should too)
• Replace console.log with structured logging (your stack)
• Add a request-id propagation header for end-to-end tracing
• Set ADVANTA_BASE=https://api.advanta.pt/v1

Test data

The sandbox accepts these NIFs to hit specific scenarios:

NIF	What you get
509123456	Tier A — happy path (Construções Ibéricas)
508666777	Tier B — concentration risk flag
505333444	Tier C — declined (insolvency proceedings)
507444555	ESG > 80, sustainability-linked candidate
999999990	validation_error (test your error UI)

Full catalog: see docs/api-ecosystem/sandbox-data.md in the main repo.

License

MIT. Use freely. Open issues + PRs welcome.