vsmsconnect — API — certificates

← all endpoints

GET/api/v1/businesses/:businessId/locations/:locationId/certificates auth: jwt (administrator | update_taxcore_credentials)

List all Certificates registered against a Location. Returns the PUBLIC projection — VSDC credentials (PFX filename, password, PAC) are stripped; `hasCertificate: boolean` indicates cert presence.

handlers: CertificatesController.list

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
locationId path
uuid		yes—Parent Location UUID.

Outputs

200
APIResponseDataList<PublicCertificateDTO>
Certificates for the Location (credential fields stripped).
POST/api/v1/businesses/:businessId/locations/:locationId/certificates auth: jwt (administrator | update_taxcore_credentials)

Upload a new V-SDC certificate for a Location. multipart/form-data: PFX file + password + PAC + UID. The server RC2→3DES-converts the PFX, verifies the PAC against V-SDC /status, cross-checks UID against status.uid, writes the file under CERT_STORAGE_DIR/{uuid}.pfx, and persists a Certificates row. PFX bytes are cleaned up if persistence fails. PFX file max 5 MB.

handlers: CertificatesController.create

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
locationId path
uuid		yes—Parent Location UUID — validated against the business.
file body
multipart .pfx		yes—PFX certificate (max 5 MB). RC2-40-CBC accepted; normalised to 3DES on write.
password body
string		yes—PFX passphrase. Stored AES-256-GCM encrypted.
pac body
string		yes—PAC issued by TaxCore. Verified against V-SDC /status before persistence.
uid body
string		yes—8-character uppercase alphanumeric UID. Cross-checked against status.uid.
name body
string		no—Optional certificate display name. Falls back to the parent Location's name when blank.

Outputs

201
APIResponseDataObject<PublicCertificateDTO>
Newly created Certificate (public projection).
404
APIError
LOCATION_NOT_FOUND — locationId does not belong to the business.
409
APIError
CERTIFICATE_LOCATION_ALREADY_ACTIVE — the Location already holds an active certificate (one per Location). Revoke it first, or rotate its credentials in place via PATCH with file+password+pac+uid. Checked before the V-SDC call, so a rejected upload contacts nothing and writes nothing.
422
APIError
CERTIFICATE_INVALID — missing/unreadable PFX or wrong passphrase. VSDC_PAC_INVALID / VSDC_UID_MISMATCH / VSDC_URL_NOT_FOUND_IN_CERT on V-SDC verification failure. VALIDATION_ERROR for schema violations.
502
APIError
VSDC_UNAVAILABLE — network/server failure during PAC verification.
GET/api/v1/businesses/:businessId/locations/:locationId/certificates/:certificateId auth: jwt (administrator | update_taxcore_credentials)

Fetch a single Certificate (public projection — credential fields stripped).

handlers: CertificatesController.getById

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
locationId path
uuid		yes—Parent Location UUID.
certificateId path
uuid		yes—Target Certificate UUID.

Outputs

200
APIResponseDataObject<PublicCertificateDTO>
Certificate (public projection).
404
APIError
CERTIFICATE_NOT_FOUND.
PATCH/api/v1/businesses/:businessId/locations/:locationId/certificates/:certificateId auth: jwt (administrator | update_taxcore_credentials)

Patch a Certificate's metadata — name and/or status (active|revoked). Re-activating (status='active') is rejected with 409 CERTIFICATE_LOCATION_ALREADY_ACTIVE when the Location already holds another active certificate: one active certificate per Location.

handlers: CertificatesController.update

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
locationId path
uuid		yes—Parent Location UUID.
certificateId path
uuid		yes—Target Certificate UUID.
name body
string		no—Updated display name (min 1 char).
status body
'active' | 'revoked'		no—Revocation toggle.

Outputs

200
APIResponseDataObject<PublicCertificateDTO>
Updated Certificate (public projection).
404
APIError
CERTIFICATE_NOT_FOUND.
422
APIError
VALIDATION_ERROR — empty body or schema violation.
POST/api/v1/businesses/:businessId/locations/:locationId/certificates/:certificateId/revoke auth: jwt (administrator | update_taxcore_credentials)

Revoke a Certificate (sets Status='revoked'). Convenience action — equivalent to PATCH with status='revoked'.

handlers: CertificatesController.revoke

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
locationId path
uuid		yes—Parent Location UUID.
certificateId path
uuid		yes—Target Certificate UUID.

Outputs

200
APIResponseDataObject<PublicCertificateDTO>
Revoked Certificate (public projection).
404
APIError
CERTIFICATE_NOT_FOUND.
DELETE/api/v1/businesses/:businessId/locations/:locationId/certificates/:certificateId auth: jwt (administrator | update_taxcore_credentials)

Delete a Certificate. Removes the DB row and unlinks the PFX file from CERT_STORAGE_DIR (fire-and-forget; unlink errors swallowed).

handlers: CertificatesController.remove

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
locationId path
uuid		yes—Parent Location UUID.
certificateId path
uuid		yes—Target Certificate UUID.

Outputs

204
void
Certificate removed.
404
APIError
CERTIFICATE_NOT_FOUND.