Finvosmart API

Connect your own systems to Finvosmart: create GST invoices, keep customers and items in sync, read your books and receive webhook notifications. Everything uses JSON over HTTPS with token-based sign-in.

Quick start

1. Sign in. Use a dedicated user for your integration, with the least-privileged role that covers what it needs. You get an access token.

curl -X POST https://app.finvosmart.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"integration@yourcompany.com","password":"…","companyCode":"ACME482"}'

{
  "success": true,
  "data": { "accessToken": "eyJhbGciOi…", "refreshToken": "eyJhbGciOi…", "companyCode": "ACME482", … }
}

2. Call the API with the token in the Authorization header. When it expires, sign in again or use POST /auth/refresh with the refresh token.

curl "https://app.finvosmart.com/api/v1/invoices?page=0&size=20" \
  -H "Authorization: Bearer <accessToken>"

Conventions

• Base URL: https://app.finvosmart.com/api/v1
• Every response is wrapped as { success, message, data, error }; your result is in data.
• Lists that can grow are paged: pass page (from 0) and size; read content, totalElements and totalPages.
• Dates are YYYY-MM-DD. Amounts are decimal numbers in rupees.
• Errors use standard status codes: 400 (invalid request — see message), 401 (sign in again), 403 (the user's role lacks the permission listed below), 404 (not found), 429 (too many requests).
• Rate limits: 30 requests per second per IP for the API; 5 sign-in attempts per minute per IP.

{
  "success": true,
  "data": {
    "content": [ … ],
    "currentPage": 0, "pageSize": 20, "totalElements": 134, "totalPages": 7
  }
}

Webhooks

An administrator registers an HTTPS address under Settings → Webhooks (or with POST /webhooks), choosing one event or * for all of them. The signing secret is shown once, when the endpoint is registered or its secret is replaced — store it then. When something happens, Finvosmart sends a JSON POST:

POST https://your-server.example/finvosmart
Content-Type: application/json
User-Agent: Finvosmart-Webhooks/1.0
X-FINVO-Event: payment.received
X-FINVO-Delivery: 5f0c6a4e-…            (new for every attempt)
X-FINVO-Timestamp: 1792473600           (Unix seconds)
X-FINVO-Signature: sha256=9c1f…         (HMAC-SHA256 of "<timestamp>.<body>")

{
  "id": "3b1e2f7a-…",                   (the same on every attempt: use it to ignore repeats)
  "event": "payment.received",
  "createdAt": "2026-10-20T04:30:00Z",
  "company": "<your company id>",
  "data": {
    "paymentId": "…", "invoiceId": "…", "invoiceNumber": "INV/26-27/000042",
    "customerId": "…", "customerName": "Acme Traders", "amount": 59000.00, "tdsAmount": 0,
    "paymentDate": "2026-10-20", "mode": "UPI", "reference": "4183…", "balanceDue": 0
  }
}

Verify every delivery. The signature is sha256= followed by the HMAC-SHA256, in lowercase hex, of the timestamp header, a full stop and the raw body, keyed with your secret. Refuse deliveries whose timestamp is more than five minutes away from your clock, and compare in constant time:

const crypto = require('crypto')

// rawBody: the request body exactly as received (before JSON parsing).
// headers: X-FINVO-Timestamp and X-FINVO-Signature from the request.
function isValid(rawBody, timestamp, signature, secret) {
  const age = Math.abs(Date.now() / 1000 - Number(timestamp))
  if (!Number.isFinite(age) || age > 300) return false          // older than 5 minutes: a replay
  const expected = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody, 'utf8').digest('hex')
  const a = Buffer.from(expected), b = Buffer.from(signature || '')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

import hmac, hashlib, time

def is_valid(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    try:
        if abs(time.time() - int(timestamp)) > 300:   # older than 5 minutes: a replay
            return False
    except (TypeError, ValueError):
        return False
    signed = timestamp.encode() + b"." + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")

Events

• Answer with any 2xx status within 10 seconds; do slow work afterwards. Redirects are not followed.
• A delivery that fails with a network error, a 5xx or a 429 is tried up to three times (at once, after 2 seconds, after 10 seconds). Other answers are not retried.
• The same event can arrive twice — ignore an id you have already handled.
• After 15 failed deliveries in a row the endpoint is switched off; Settings → Webhooks shows the last error and switches it back on.
• The Send test button there (or POST /webhooks/{id}/test) sends a ping event, signed the same way.
• Only public HTTPS addresses are accepted: no IP addresses in private ranges, no localhost or internal names.

Need an endpoint that isn't listed, or higher limits? Contact us.