xero-tax-mappings

GET/api/v1/accounting/xero/tax-mappings auth: jwt (administrator)

List all Xero tax-type to V-SDC tax-label mappings for the business (active and inactive). Active rows ordered first, then alphabetically. `isActive: boolean` per row so the admin UI can surface a Restore action on soft-deleted entries.

handlers: XeroTaxMappingsController.list

Inputs

No parameters.

Outputs

200

APIResponseDataList<TaxRateMappingDTO>

Mappings for `Provider='xero'`.

POST/api/v1/accounting/xero/tax-mappings/auto-map auth: jwt (administrator)

Fetch Xero `/TaxRates` from the active tenant + V-SDC `/status`, then return match suggestions with `needsReview` flags + alternatives. Does NOT persist — the admin confirms each suggestion via PUT. Rate-limited (10/min open bucket).

handlers: XeroTaxMappingsController.autoMap

Inputs

No parameters.

Outputs

200

APIResponseDataObject<XeroTaxMappingAutoMapResponse>

Suggestions array with `providerTaxType`, `suggestedVsdcLabel`, `alternatives[]`, `needsReview`.

401

APIError

REAUTH_REQUIRED — Xero refresh token rejected.

429

APIError

Rate limit exceeded (caller or Xero).

PUT/api/v1/accounting/xero/tax-mappings auth: jwt (administrator)

Create or update one Xero tax-type to V-SDC label mapping (MERGE on (businessId, 'xero', providerTaxType)). Re-activates an existing inactive row instead of inserting a duplicate. Fires `XERO_TAX_MAPPING_UPDATED` audit.

handlers: XeroTaxMappingsController.upsert

Inputs

name	required	default	description
`providerTaxType` body string	yes	—	Xero tax-type code (e.g. `OUTPUT2`, `ZERORATED`). Trimmed, 1–100 chars.
`providerTaxName` body string \| null	no	—	Human-readable Xero tax name for display.
`providerRate` body number \| null	no	—	Xero rate percent.
`vsdcTaxLabel` body string	yes	—	Target V-SDC tax label (must be one of `F/N/P/E/T/A/B/C/D`).
`vsdcRate` body number \| null	no	—	V-SDC rate percent for display.

Outputs

200

APIResponseDataObject<TaxRateMappingDTO>

Upserted mapping row.

422

APIError

XERO_TAX_MAPPING_INVALID_LABEL — `vsdcTaxLabel` is not a valid V-SDC label.

DELETE/api/v1/accounting/xero/tax-mappings/:providerTaxType auth: jwt (administrator)

Soft-delete a Xero tax mapping — sets `IsActive=0`. Row is retained for history and can be re-activated via the restore endpoint. Idempotent.

handlers: XeroTaxMappingsController.remove

Inputs

name	required	default	description
`providerTaxType` path string	yes	—	Xero tax-type code to deactivate.

Outputs

204

empty

No content.

PATCH/api/v1/accounting/xero/tax-mappings/:providerTaxType/restore auth: jwt (administrator)

Re-activate a previously soft-deleted Xero tax mapping (`IsActive=0` → `1`). Idempotent.

handlers: XeroTaxMappingsController.restore

Inputs

name	required	default	description
`providerTaxType` path string	yes	—	Xero tax-type code to re-activate.

Outputs

204

empty

No content.