Nudge REST API

Implement these endpoints so Nudge can sync debtors, invoices, and payments from your ERP, and push outbound invoices and payments back. Every call uses POST, JSON, and a required Bearer token. See Sync & push flows for when each endpoint is called.

The base URL is configured in Settings → ERP connection with transport REST (no trailing slash), authenticated with an Alderstone-generated API key. Contract version is always "1".

Endpoints

Implement the three inbound */list endpoints first (sync calls these), then add the outbound push endpoints:

Path	Direction	Purpose
`POST /health`	Test	Connection validation on save
`POST /debtors/list`	Inbound	Paginated debtor import
`POST /invoices/list`	Inbound	ACCREC-style invoice import
`POST /payments/list`	Inbound	Payment import
`POST /invoices/push`	Outbound	Create invoice in ERP on dispatch
`POST /payments/push`	Outbound	Create payment in ERP on cash application

All endpoints use the standard error body for failures and must echo schemaVersion: "1" on success responses.

POST/health

Health check

Return 200 when the token is valid and the service is ready.

Try in sandbox

Request

POST

/health

{
  "schemaVersion": "1"
}

Response

200

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

Errors

401

{
  "schemaVersion": "1",
  "error": "Missing or invalid Authorization header. Use: Authorization: Bearer <token>",
  "code": "UNAUTHORIZED"
}

POST/debtors/list

Debtors list

Paginate until hasMore is false. Maps to your ERP's active contacts or debtors API.

Try in sandbox

Request

POST

/debtors/list

{
  "schemaVersion": "1",
  "page": 1,
  "limit": 100
}

Response

200

{
  "schemaVersion": "1",
  "debtors": [
    {
      "erpDebtorId": "DEB-001",
      "name": "Acme Ltd",
      "email": "ar@acme.example"
    }
  ],
  "hasMore": false
}

Errors

401

{
  "schemaVersion": "1",
  "error": "Missing or invalid Authorization header. Use: Authorization: Bearer <token>",
  "code": "UNAUTHORIZED"
}

POST/invoices/list

Invoices list

Omit modifiedSince on first full sync. Incremental sync passes ISO datetime from last successful sync.

Try in sandbox

Request

POST

/invoices/list

{
  "schemaVersion": "1",
  "page": 1,
  "limit": 100,
  "modifiedSince": "2026-01-01T00:00:00.000Z"
}

Response

200

{
  "schemaVersion": "1",
  "invoices": [
    {
      "erpInvoiceId": "INV-1001",
      "invoiceNumber": "INV-1001",
      "erpDebtorId": "DEB-001",
      "debtorName": "Acme Ltd",
      "issueDate": "2026-01-15",
      "dueDate": "2026-02-15",
      "currency": "ZAR",
      "amountTotal": 1150,
      "amountOutstanding": 1150,
      "status": "AUTHORISED",
      "lines": [
        {
          "description": "Consulting",
          "quantity": 10,
          "unitPrice": 100,
          "amount": 1000
        }
      ]
    }
  ],
  "hasMore": false
}

Errors

401

{
  "schemaVersion": "1",
  "error": "Missing or invalid Authorization header. Use: Authorization: Bearer <token>",
  "code": "UNAUTHORIZED"
}

POST/payments/list

Payments list

Payments reference the invoice they settle via erpInvoiceId. Payments that don't match a synced invoice are skipped. See Sync & push flows for the edge cases.

Try in sandbox

Request

POST

/payments/list

{
  "schemaVersion": "1",
  "page": 1,
  "limit": 100
}

Response

200

{
  "schemaVersion": "1",
  "payments": [
    {
      "erpPaymentId": "PAY-501",
      "erpInvoiceId": "INV-1001",
      "amount": 500,
      "paymentDate": "2026-02-01"
    }
  ],
  "hasMore": false
}

Errors

401

{
  "schemaVersion": "1",
  "error": "Missing or invalid Authorization header. Use: Authorization: Bearer <token>",
  "code": "UNAUTHORIZED"
}

POST/invoices/push

Invoice push

Called when Alderstone dispatches an invoice. Return stable erpInvoiceId for idempotent retries.

Try in sandbox

Request

POST

/invoices/push

{
  "schemaVersion": "1",
  "invoiceNumber": "AS-2026-0042",
  "erpDebtorId": "DEB-001",
  "issueDate": "2026-03-01",
  "dueDate": "2026-03-31",
  "currency": "ZAR",
  "status": "AUTHORISED",
  "lines": [
    {
      "description": "Services",
      "quantity": 1,
      "unitPrice": 1000,
      "amount": 1000
    }
  ]
}

Response

200

{
  "schemaVersion": "1",
  "erpInvoiceId": "INV-ERP-9001"
}

Errors

401

{
  "schemaVersion": "1",
  "error": "Missing or invalid Authorization header. Use: Authorization: Bearer <token>",
  "code": "UNAUTHORIZED"
}

POST/payments/push

Payment push

Called on cash application approval. bankAccountCode is optional (from connection settings in Alderstone).

Try in sandbox

Request

POST

/payments/push

{
  "schemaVersion": "1",
  "erpInvoiceId": "INV-ERP-9001",
  "amount": 1000,
  "paymentDate": "2026-03-15",
  "bankAccountCode": "090"
}

Response

200

{
  "schemaVersion": "1",
  "erpPaymentId": "PAY-ERP-7001"
}

Errors

401

{
  "schemaVersion": "1",
  "error": "Missing or invalid Authorization header. Use: Authorization: Bearer <token>",
  "code": "UNAUTHORIZED"
}

Test in the sandbox

The recommended way to test your middleware is the Developer Sandbox. It sends the same requests Alderstone makes, validates responses against this contract, and includes a built-in mock ERP when you have not deployed middleware yet.

Open sandbox

Quick link

GET

/sandbox

/sandbox?product=nudge&endpoint=health