vsmsconnect — API — sage

← all endpoints

GET/api/v1/accounting/sage/start auth: jwt (administrator)

Begin a Sage OAuth2 authorisation flow for the caller's business. Generates PKCE + state, persists in OAuthStates, returns the Sage authorisation URL. Rate-limited (10/min open bucket).

handlers: SageAccountingAuthController.start

Inputs

No parameters.

Outputs

200
APIResponseDataObject<SageStartResponse>
`{ authorizationUrl }`.
409
APIError
BUSINESS_CONTEXT_REQUIRED.
429
APIError
Rate limit exceeded.
GET/api/v1/accounting/sage/callback auth: none

Sage OAuth callback. Validates state, exchanges the code, upserts a single SageConnections row (Sage has one business per token — no tenant selection), then 302 redirects (desktop) or serves a 200 text/html bridge page (mobile) opening `vsms://auth/sage/{success|failure}`.

handlers: SageAccountingAuthController.callback

Inputs

namerequireddefaultdescription
code query
string		no—OAuth authorisation code returned by Sage.
state query
string		no—PKCE state issued by `/start`.
error query
string		no—Set by Sage on failure or user denial.

Outputs

302
redirect
Desktop UA — redirect to `${SAGE_FRONTEND_WEB_BASE_URL}/auth/sage/{success|failure}`.
200
text/html
Mobile UA — HTML bridge page opening the native deep link with web fallback.
GET/api/v1/accounting/sage/status auth: jwt

Sage connection summary — whether a Sage connection exists, the connected Sage business, and the current `autoFiscaliseInvoices` flag.

handlers: SageAccountingAuthController.status

Inputs

No parameters.

Outputs

200
APIResponseDataObject<SageStatusResponse>
Connection summary.
409
APIError
BUSINESS_CONTEXT_REQUIRED.
DELETE/api/v1/accounting/sage/connection auth: jwt (administrator)

Soft-deactivate the Sage connection for the caller's business (`IsActive=0`). Rows are retained for history; the user may re-authorise via `/sage/start`. Fires `SAGE_DISCONNECTED` audit.

handlers: SageAccountingAuthController.disconnect

Inputs

No parameters.

Outputs

200
APIResponseDataObject<{ deactivatedCount: number }>
Number of rows deactivated.