vsmsconnect — API — http-connector

Getting started

The HTTP connector is a machine-to-machine API. Before your integration code can call it, a human admin at the customer's company must complete a one-time setup in our app to obtain three credentials.

Step 1 — Account + business onboarding (one-time, per customer)

The admin signs up at our app, verifies their email, and registers their business (uploads V-SDC certificate, validates PAC, enters TaxCore UID + licence key). This produces a unique BUSINESS_ID UUID tied to the business's fiscalisation credentials.

Step 2 — Generate an HTTP-scoped API key

In the app: Integrations → Generic HTTP → Issue new key. The key carries no location: where an invoice signs is decided per invoice by the store code on it, not by the credential. One key serves the whole business, however many outlets it has. A one-shot reveal modal then displays three values, each with a copy button:

• Backend URL — e.g. https://api.vsmsconnect.com/api/v1
• Business ID — UUID, e.g. 7f3a1e2c-...
• API key — 64-char hex string, e.g. a3f2b1c8d9e7f6a4b2c1d8e9f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8

The API key is shown once. The customer's admin must copy it and hand it (plus the Backend URL and Business ID) to their integration team — usually via their internal password manager. If the key is lost, the admin revokes it and issues a new one. Backend URL and Business ID remain visible in the app's API Keys list.

Step 3 — Configure your integration

Set three environment variables (or config equivalents) in your code:

VSMS_CONNECT_BACKEND_URL  = "https://api.vsmsconnect.com/api/v1"
VSMS_CONNECT_BUSINESS_ID  = "7f3a1e2c-..."
VSMS_CONNECT_API_KEY      = "a3f2b1c8d9e7f6a4..."

Every request goes to:

POST {VSMS_CONNECT_BACKEND_URL}/businesses/{VSMS_CONNECT_BUSINESS_ID}/fiscalise

with headers:

Authorization: ApiKey {VSMS_CONNECT_API_KEY}
Idempotency-Key: <optional — omit it and the server derives one from invoiceNumber>
Content-Type: application/json

Step 4 — Declare your tax codes & have them mapped

Unless you send raw taxLabels, POST your tax table once to {VSMS_CONNECT_BACKEND_URL}/businesses/{VSMS_CONNECT_BUSINESS_ID}/tax-rates (same ApiKey auth) so a business admin can map every taxCode to a V-SDC label before you send live invoices. Until a code is mapped, invoices using it are accepted but blocked with MISSING_TAX_MAPPING. There are no pre-seeded defaults — a brand-new business cannot fiscalise anything until you declare at least one code and an admin maps it. See Tax codes & labels below for the full model.

Step 5 — Declare your store codes & have them mapped

POST your store list once to {VSMS_CONNECT_BACKEND_URL}/businesses/{VSMS_CONNECT_BUSINESS_ID}/stores (same ApiKey auth), then send storeCode — your own identifier — on every invoice. You never store a VSMS Connect GUID against your shops. GET the same path to read back what each code currently resolves to.

Do this even if the business has a single shop. The rule is not about how many outlets there are — it is that any store code you send has to be mapped before it can sign. A single-location business that sends a code you never declared gets the same block as a chain would. Declaring one store and having it mapped is a minute of setup, and it means the integration behaves identically on the day the customer opens their second shop.

An admin then maps each declared code to one of the business’s Locations in the app. That mapping is what decides which V-SDC certificate signs the store’s invoices.

Routing fails closed — read this before going live

An invoice whose store code cannot be resolved is accepted and blocked, never signed somewhere else. It returns 201 with eligibleForFiscalisation: false and a reason in fiscalisationBlockReasons:

Blocking rather than rejecting is deliberate: a 4xx would lose a real sale over a configuration gap, and an unknown code would never become visible to the admin. The invoice is kept, the code is proposed for review, and the admin’s Re-sync blocked invoices releases it once the mapping exists. Nothing is silently signed under a certificate the sale does not belong to.

The one case that needs no setup at all: a business with a single certified Location, where you send no selector on any invoice. Every sale then signs at that Location. This is a genuine zero-config path, but it is all-or-nothing — send a store code and it must be mapped, exactly as above. It also stops being available the moment the customer certifies a second Location, at which point invoices with no code block with HTTP_STORE_CODE_REQUIRED until you start sending one. Declaring your stores up front avoids that day entirely.

The locationId escape hatch. A caller that already holds our internal GUID may send locationId instead (must belong to the business, else 422 LOCATION_NOT_FOUND). Send exactly one of the two — 422 LOCATION_SELECTOR_EXCLUSIVE if you send both. New integrations should use storeCode.

Either selector affects a fresh sale only: refunds and copies inherit the original sale’s location and certificate automatically.

Multi-tenant integrations

If your software integrates with multiple of our customers, each customer's admin completes Step 1 + Step 2 independently. You end up with one Business ID and one API key per customer — not per outlet, since the key carries no location. Each customer’s outlets are told apart by the storeCode on each invoice, so your per-customer configuration stays two values however many shops they run. The Backend URL is the same for every customer.

Tax codes & labels

Each line item carries exactly one of taxCode or taxLabel — and either one takes a single value or an array.

An item can bear more than one tax. A label identifies one rate inside one tax category, and an item may be liable for several categories at once — VAT plus a levy, say. Pass an array when it is: "taxCode": ["VAT15", "ECAL"], or "taxLabel": ["A", "D"] if you are using raw labels. At most one tax per category; a repeated entry is rejected (TAX_CODES_DUPLICATE), and there is no cap on how many categories an item may carry.

Note this is the same field, not a separate plural one: "VAT15" and ["VAT15"] mean exactly the same thing. Existing integrations need no change, and adding a second tax to a line means putting the value you already send in brackets.

Every amount is still computed by V-SDC from the labels and the item total — which is the only place it can be right, because a tax-on-total rate is charged on the item total including the other taxes on that line, and an amount-per-quantity tax makes the remaining taxes compute on the remainder. Sending several labels attaches them; it never asks you to do that arithmetic.

taxCode is a semantic code from your system — an open vocabulary (any non-empty string up to 100 chars, e.g. VAT15, VAT0, EXCISE). VSMS Connect cannot pull your tax catalogue, so you declare your codes via POST /tax-rates and a business admin maps each one to a V-SDC label in the app before the first invoice. A code with no confirmed mapping does not fail the request — the invoice is accepted but blocked with MISSING_TAX_MAPPING until an admin maps it (an unmapped code also surfaces automatically in the admin’s tax-mappings panel). No codes exist by default: taxCode is your own vocabulary, and every code you use has to be declared (or discovered from an invoice) and then mapped by an admin before it can sign.

taxLabel is the escape hatch: send a raw V-SDC label directly and bypass mapping entirely.

The valid labels are defined by TaxCore, not by VSMS Connect — we do not publish the list here. The set and its meanings belong to the tax authority and can be changed by them at any time, so any copy printed in these docs would eventually be wrong in a way you could not detect. VSMS Connect syncs the labels the business’s V-SDC is actually configured with; the authoritative list for a given business is the one offered in the app’s tax-mapping panel, where an admin maps each of your codes to a label. Ask the business admin, or refer to the current TaxCore documentation.

This is also why taxCode is the recommended path: you send your own vocabulary and the admin maps it, so a label change is their configuration problem rather than a release of your software.

A label identifies one specific tax rate — e.g. the 9% rate of the VAT category. Each label belongs to exactly one tax category (VAT, ECAL, PBL…) and never reappears under another, and each category declares how its rates are applied: on the net price, on the total with other taxes included, or as a fixed amount per unit of quantity.

Rates arrive as a revision: TaxCore publishes a tax group with an id and an effective date, so both the rates and the label set can change on a date set by the authority. That is why nothing is hard-coded here — VSMS Connect syncs the group the business’s V-SDC currently reports.

V-SDC computes every tax amount itself, from the labels and the item total. The taxRatePercent and tax amounts you send are used for reconciliation and display on our side; they are never what the fiscal receipt is signed with, and they cannot override the authority’s figures. If your numbers disagree with the SDC’s, the SDC is right by definition.

Case matrix

One endpoint, POST /fiscalise, handles every fiscalisation case via two body fields: invoiceType (NORMAL / COPY / PROFORMA / ADVANCE) and transactionType (SALE / REFUND), plus an optional training: true flag that overrides invoiceType to TRAINING. The other routes are operational / configuration helpers:

• POST /tax-rates — declare your tax table so an admin can map each taxCode to a V-SDC label before you send invoices (see Tax codes & labels above).
• POST /stores — declare your own store codes so an admin can map each one to the Location whose certificate signs it. Any code you send must be mapped first, whatever the number of outlets.
• GET /stores — read back what each declared code currently resolves to.
• GET /fiscalise/:invoiceId — idempotent status retrieval after a 202 from POST.
• POST /fiscalise/:invoiceId/trigger — explicit dispatch for a PROFORMA imported via the 201 path.
• POST /fiscalise/cancel — submit a V-SDC cancellation document, targeting the payment by fiscalInvoiceNumber or by your own invoiceNumber.