Quickstart

This guide walks through building a working ERP integration: middleware that Alderstone can call, with authentication, a health check, and an end-to-end test. Expect a passing connection test within an hour.

Before you start

You'll need:

1. Somewhere to host HTTPS endpoints reachable from Alderstone's servers: an iPaaS (Workato, Make, n8n) or your own infrastructure. Production endpoints must use valid TLS certificates (no self-signed certs).
2. Admin access to the Alderstone app you're integrating, so you can configure the connection and generate an API key.
3. API credentials for your ERP, stored in your middleware only; they are never entered into Alderstone.

If you haven't decided between REST middleware and a built-in native connector, read Choose your integration path first.

Step 1: Understand the shape of the integration

Alderstone calls your endpoints; you never call Alderstone. Every request is an HTTPS POST with a JSON body, a schemaVersion: "1" field, and an Authorization: Bearer header carrying an Alderstone-generated API key:

The endpoints you implement depend on the app:

• OrderBridge: catalogue search, pricing, and draft sales orders: REST API reference
• Nudge: debtor/invoice/payment sync and push: REST API reference

Step 2: Implement /health

Start with the smallest possible endpoint. POST /health is what Alderstone calls to test the connection, so getting it working proves your hosting, TLS, and authentication all at once. Return 200 with:

{ "schemaVersion": "1", "ok": true, "service": "your-middleware-name" }

Requests without a valid Authorization: Bearer header must get a 401 with the standard error body. You don't have a token to validate yet. For now just check the header is present and well-formed.

Step 3: Generate an API key and connect Alderstone

In the Alderstone app, open the integration settings and configure your middleware:

The key is shown once. Store it in your middleware's secret store and validate incoming Bearer tokens against it. See Authentication for the full flow, including rotation.

When you save, Alderstone runs a connection test: POST /health, and for OrderBridge also a sample POST /sale-draft (PO number DEMO-PO-001 with a demo SKU). Both must succeed before the connection shows as connected. If the test fails, the troubleshooting pages cover the common causes.

Step 4: Implement the remaining endpoints

Work through the endpoint reference for your app, translating each request into your ERP's APIs:

• OrderBridge REST API; the PO workflow page shows when each endpoint is called, which helps you prioritise: catalogue search first, then pricing, then sale-draft.
• Nudge REST API: implement the three */list endpoints first so sync works, then the two */push endpoints. Sync & push flows explains the triggers.

Keep these conventions in mind as you build:

• Echo schemaVersion: "1" on every success response and ignore unknown request fields (Schema versioning).
• Return the standard error body for all failures; Alderstone surfaces these messages to users.
• Make writes idempotent: repeated sale-draft calls with the same poNumber, or repeated pushes for the same invoice, must not create duplicates (Rate limits & retries).
• List endpoints paginate: honour limit, and for Nudge return hasMore until the data set is exhausted.

Platform recipes

Step 5: Run an end-to-end test

Prove the integration with a real workflow, not just curl:

• OrderBridge: upload a PO, match the customer and product lines, and submit the draft sales order. Verify your middleware received the catalog/*, pricing/resolve, and sale-draft calls and that the draft order landed in your ERP.
• Nudge: trigger Sync now in Settings and verify debtors/list, invoices/list, and payments/list were called and data appears in Alderstone. Then dispatch an invoice and apply cash to a payment to exercise invoices/push and payments/push.

Step 6: Go-live checklist

Before pointing production Alderstone at production middleware:

• HTTPS with a valid certificate; Alderstone's egress can reach the endpoint
• Bearer validation rejects bad tokens with 401 and a plan exists for key rotation
• All success responses echo schemaVersion: "1"; all errors use the standard body
• Writes are idempotent (sale-draft by poNumber; pushes by invoice/payment identity)
• Latency within targets (see Rate limits & retries
• Middleware logs requests (without tokens) so failures can be traced to upstream ERP errors
• ERP rate limits are respected; middleware returns 429 instead of hanging when throttled

Common operational situations

Where to next

• Authentication: API key lifecycle
• OrderBridge troubleshooting and Nudge troubleshooting: common fixes
• Troubleshooting FAQ: cross-app questions