vsmsconnect — API — businesses

← all endpoints

POST/api/v1/businesses/register auth: jwt

First-user business registration with TaxCore verification. Validates the supplied PFX/PAC/UID against V-SDC, creates the business, promotes the calling user to Administrator, and returns fresh JWT tokens. No role guard — the caller has no businessId yet.

handlers: BusinessesController.registerBusiness

Inputs

namerequireddefaultdescription
file body
multipart .pfx		yes—PFX certificate file (.pfx / .p12). Converted RC2 → 3DES on the server before storage.
name body
string		yes—Business display name.
tin body
string		yes—Tax Identification Number. Must be unique across all businesses.
pac body
string		yes—PAC (Privileged Access Code) issued by TaxCore.
uid body
string		yes—8-character uppercase alphanumeric UID assigned by TaxCore. Cross-checked against V-SDC `/status`.
pfxPassword body
string		yes—Passphrase for the uploaded PFX certificate.
street body
string | null		no—Optional street address.
city body
string | null		no—Optional city.
country body
string | null		no—ISO 3166-1 alpha-2 code (e.g. 'VU', 'AU').
currencyCode body
string		noVUVISO 4217 three-letter currency code. Defaults to 'VUV' when omitted.

Outputs

201
APIResponseDTO<{ business: PublicBusinessDTO; accessToken: string; refreshToken: string }>
Business created. Sets a httpOnly refresh-token cookie. The `business` is the public projection (credential fields stripped).
409
APIError
BUSINESS_TIN_TAKEN — the supplied TIN already belongs to another business.
422
APIError
CERTIFICATE_INVALID — missing or unreadable PFX, or wrong passphrase. VSDC_PAC_INVALID / VSDC_UID_MISMATCH on V-SDC verification failure.
POST/api/v1/businesses auth: jwt (administrator)

Create an additional business. Used after the first business is registered. TIN must be unique across all businesses.

handlers: BusinessesController.create

Inputs

Request body type: CreateBusinessRequest

namerequireddefaultdescription
name body
string		yes—Business display name.
tin body
string		yes—Tax Identification Number. Must be unique across all businesses.
street body
string | null		no—Street address.
city body
string | null		no—City.
country body
string | null		no—ISO 3166-1 alpha-2 code (e.g. 'VU').
currencyCode body
string		noVUVISO 4217 three-letter currency code. Defaults to 'VUV' when omitted.

Outputs

201
APIResponseDataObject<PublicBusinessDTO>
Newly created business. `vsdcPfxPassword`, `vsdcPac`, `vsdcCertificateFile` are stripped server-side.
409
APIError
BUSINESS_TIN_TAKEN.
422
APIError
VALIDATION_ERROR for schema violations.
GET/api/v1/businesses auth: jwt

Returns the single business the authenticated user belongs to. Users without a businessId receive an empty list. Returned as an APIResponse list shape for FE consistency.

handlers: BusinessesController.list

Inputs

No parameters.

Outputs

200
APIResponseDataList<PublicBusinessDTO>
List with zero or one entry. Credential fields are stripped.
PATCH/api/v1/businesses/:businessId auth: jwt (administrator | update_business_settings)

Partially update non-credential business settings — name, address fields, currencyCode, and the demo Xero tenant id used for Training routing. At least one field must be provided.

handlers: BusinessesController.updateSettings

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID. Must match the caller's JWT businessId — Administrators bypass via requireBusinessAccess.
name body
string		no—Updated display name (non-empty).
street body
string | null		no—Pass null to clear.
city body
string | null		no—Pass null to clear.
country body
string | null		no—ISO 3166-1 alpha-2 code, or null to clear.
currencyCode body
string		no—ISO 4217 three-letter currency code.
demoXeroTenantId body
uuid | null		no—Xero tenant id that routes invoices through V-SDC Training mode. Empty string is normalised to null. Pass null to disable Training routing.

Outputs

200
APIResponseDataObject<PublicBusinessDTO>
Updated business (credential fields stripped).
404
APIError
BUSINESS_NOT_FOUND.
422
APIError
VALIDATION_ERROR — empty body or schema violation.
PATCH/api/v1/businesses/:businessId/taxcore-config auth: jwt (administrator | update_taxcore_credentials)

Update V-SDC credentials for a business. multipart/form-data — every field optional, at least one required. When `pac` is supplied, the server verifies it against V-SDC `/status` (mTLS) before persisting. When `businessUID` is also supplied, `status.uid` is cross-checked against it.

handlers: BusinessesController.updateTaxcoreConfig

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
file body
multipart .pfx		no—New PFX certificate. Converted RC2 → 3DES and written under CERT_STORAGE_DIR; only the UUID filename is stored in DB. Replaces any prior cert.
password body
string | null		no—PFX passphrase (also stored as VsdcPfxPassword). Null clears the field. Write-only — never returned.
pac body
string | null		no—PAC. Verified against V-SDC `/status` before being persisted. Null clears. Write-only.
businessUID body
string | null		no—8-character uppercase alphanumeric UID. Cross-checked against status.uid when pac is also supplied.

Outputs

200
APIResponseDataObject<PublicBusinessDTO>
Updated business. `hasCertificate: boolean` is included instead of the cert filename.
404
APIError
BUSINESS_NOT_FOUND.
422
APIError
VALIDATION_ERROR (no fields) | CERTIFICATE_INVALID (bad PFX / wrong passphrase / cert lacks the TaxCore.PublicConfiguration.TaxCoreApiUrl extension) | VSDC_PAC_INVALID | VSDC_UID_MISMATCH | VSDC_URL_NOT_FOUND_IN_CERT.
502
APIError
VSDC_UNAVAILABLE — network/server failure when verifying the PAC.
POST/api/v1/businesses/:businessId/default-certificate auth: jwt (administrator | update_taxcore_credentials)

Registration wizard step 2 shortcut. Creates a Certificate row against the business's default Location and mirrors the same fields into the legacy `Businesses.Vsdc*` columns so the consumer's fallback path keeps working.

handlers: BusinessesController.createDefaultCertificate

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
file body
multipart .pfx		yes—PFX certificate file.
password body
string		yes—PFX passphrase.
pac body
string		yes—PAC issued by TaxCore.
uid body
string		yes—8-character uppercase alphanumeric UID.
name body
string		no—Optional certificate display name. Falls back server-side to the default Location's name.

Outputs

201
APIResponseDataObject<PublicCertificateDTO>
Newly created certificate row (public projection). Legacy `Businesses.Vsdc*` columns are also updated server-side.
404
APIError
LOCATION_NOT_FOUND — the business has no default Location (legacy business missed the back-seed migration).
422
APIError
CERTIFICATE_INVALID — missing or unreadable PFX, or wrong passphrase.