The v-ledge API.

1. 1

   Create an API key

   In v-ledge, open Settings → Company → Developer and choose New API key. Name it, pick its scopes and copy the secret. It starts with vlk_live_ and is shown only once, so store it right away:

   TerminalCopy

   export VLEDGE_API_KEY="vlk_live_…"

2. 2

   Make your first request

   List the five most recent clients to check that everything is wired up.

   cURLJavaScriptPython

   GET /clients

   Copy

   curl "https://acme.v-ledge.vestryx.com/api/v1/clients?limit=5" \
     -H "Authorization: Bearer $VLEDGE_API_KEY"

3. 3

   Create an invoice

   Send the client, dates and line items. v-ledge assigns the next invoice number and calculates subtotal, VAT and total for you.

   cURLJavaScriptPython

   POST /invoices

   Copy

   curl https://acme.v-ledge.vestryx.com/api/v1/invoices \
     -H "Authorization: Bearer $VLEDGE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "clientId": "2b0e8f4c-7d1a-4e3b-8c5f-1a9d6e2b7c40",
       "issueDate": "2026-10-14",
       "dueDate": "2026-11-13",
       "currency": "CHF",
       "taxRate": 8.1,
       "items": [
         { "description": "Consulting, 24 h", "quantity": 24, "unitPrice": 150 },
         { "description": "Implementation", "quantity": 1, "unitPrice": 950 }
       ]
     }'

   Response · 201 Created (abridged)Copy

   {
     "data": {
       "id": "9d3f6a10-52c4-4b8e-a0d7-6e1b2c3f4a58",
       "invoiceNumber": "INV-0143",
       "docType": "invoice",
       "clientId": "2b0e8f4c-7d1a-4e3b-8c5f-1a9d6e2b7c40",
       "status": "draft",
       "issueDate": "2026-10-14",
       "dueDate": "2026-11-13",
       "currency": "CHF",
       "subtotal": 4550,
       "discountAmount": 0,
       "taxRate": 8.1,
       "taxAmount": 368.55,
       "amount": 4918.55,
       "amountPaid": 0,
       "items": [
         { "position": 0, "description": "Consulting, 24 h", "quantity": 24, "unitPrice": 150, "kind": "service" },
         { "position": 1, "description": "Implementation", "quantity": 1, "unitPrice": 950, "kind": "service" }
       ]
     }
   }

Authorization: Bearer vlk_live_…

Scopes

Scopes don’t include each other. An integration that creates invoices and reads them back needs both.

// One record
{ "data": { "id": "9d3f6a10-…", … } }

// A list
{ "data": [ … ], "pagination": { "limit": 50, "offset": 0, "total": 128 } }

// After DELETE
{ "ok": true }

// Any error
{ "error": "items[0].quantity must be greater than zero" }

Updating a record

Send only what changes. Everything else stays as it is.

curl -X PATCH https://acme.v-ledge.vestryx.com/api/v1/invoices/9d3f6a10-52c4-4b8e-a0d7-6e1b2c3f4a58 \
  -H "Authorization: Bearer $VLEDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "dueDate": "2026-11-30", "notes": "Thank you for your business." }'

pagination.total holds the number of matching records, so you know when to stop. Documents and transactions come back newest first by date, clients and suppliers by creation date, and items alphabetically.

curl "https://acme.v-ledge.vestryx.com/api/v1/invoices?status=overdue&limit=200&offset=200" \
  -H "Authorization: Bearer $VLEDGE_API_KEY"

Branch on the status code rather than the message text — messages are written for people and may be refined. Retry 500 responses and network failures with exponential backoff; a 4xx fails the same way until the request changes.

The OpenAPI spec lists every writable field per resource.

Invoice items also take regionCode, estimate items serviceItemId, and vendor-bill items expenseAccount, costCenterId and serviceItemId.

How totals are calculated

1. subtotal is the sum of quantity × unitPrice over all service lines, minus discountAmount.
2. taxAmount is the subtotal × the document’s taxRate.
3. amount is subtotal + taxAmount, rounded to two decimals.

Whenever you send items, these derived values replace any totals in the same request. On PATCH, items replaces every existing position, so always send the complete list. A document holds up to 200 positions.

{ "description": "Loyalty discount", "kind": "discount", "discountMode": "percent", "unitPrice": 10 }

Leave out invoiceNumber, estimateNumber or billNumber and v-ledge assigns the next free number. Supply your own to mirror another system — if it’s taken, you’ll get 409. Invoices (not credit notes) automatically receive a QR reference for the Swiss QR-bill.

Download a PDF

GET /invoices/{id}/pdf and GET /estimates/{id}/pdf return application/pdf, rendered with your saved document design — including the Swiss QR-bill where it applies.

curl https://acme.v-ledge.vestryx.com/api/v1/invoices/9d3f6a10-52c4-4b8e-a0d7-6e1b2c3f4a58/pdf \
  -H "Authorization: Bearer $VLEDGE_API_KEY" \
  -o INV-0143.pdf

Set up an endpoint

1. Open Settings → Company → Developer and choose New endpoint under Webhooks.
2. Enter an HTTPS URL on port 443 that resolves to a public address.
3. Pick the events you want — or none, to receive every event.
4. Copy the signing secret (whsec_…). Like an API key, it’s shown only once.

Events

Payload

Each delivery is a POST with a JSON body and these headers:

{
  "id": "5f2c9a71d0e84b3c6a1f9e27",
  "event": "invoice.created",
  "createdAt": "2026-10-14T09:41:00.000Z",
  "organizationId": "c4a1e2d3-6b7f-4e8a-9c0d-1f2e3a4b5c6d",
  "data": {
    "id": "9d3f6a10-52c4-4b8e-a0d7-6e1b2c3f4a58",
    "invoiceNumber": "INV-0143",
    "amount": 4918.55,
    "currency": "CHF",
    "salesOrderId": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918"
  }
}

Verify signatures

Compute an HMAC-SHA256 of {t}.{raw body} with your signing secret and compare it to v1 in constant time. Reject timestamps older than five minutes to block replays, and always use the raw body — re-serialized JSON won’t match.

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();
const secret = process.env.VLEDGE_WEBHOOK_SECRET;

// express.raw keeps the exact bytes that were signed.
app.post("/hooks/vledge", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-Vledge-Signature") ?? "";
  const { t, v1 = "" } = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = createHmac("sha256", secret).update(`${t}.${req.body}`).digest("hex");

  const valid = v1.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  if (!valid || !fresh) return res.sendStatus(400);

  res.sendStatus(200);
  void handleEvent(JSON.parse(req.body)); // your own async processing
});

Delivery

Import it into Postman or Insomnia to explore the API interactively, or generate a typed client. Point the generated client at your workspace’s base URL.

# TypeScript types
npx openapi-typescript https://vestryx.com/api/v1/openapi.json -o vledge-api.d.ts

# A client for Python, Go, Java, …
npx @openapitools/openapi-generator-cli generate \
  -i https://vestryx.com/api/v1/openapi.json -g python -o ./vledge-client

• One key per integration. Give each system its own key with the smallest scope it needs, so you can revoke one without touching the rest.

• Keep secrets on the server. Load API keys and webhook secrets from environment variables or a secret manager — never from browser or mobile code.

• Rotate without downtime. Create the new key, deploy it, then revoke the old one.

• Retry the right things. Back off and retry 5xx responses and timeouts. Fix and resend 4xx requests.

• Always paginate. Never assume a list fits on a single page.

• Verify every webhook. Check the signature and timestamp, and deduplicate on the event id.