BUSY → DigiVista billing sync

What is ready and what needs setup

DigiVista has a signed snapshot receiver, invoice validation, duplicate/version protection and sync-run counts. It does not directly connect to a BUSY installation yet. The BUSY-side export/API adapter must be configured with your authorised solution partner. Invoices and payment entries remain in BUSY.

BUSY integration guidance · BUSY report export guidance

Setup steps

  1. Confirm BUSY version, where it runs and your solution partner’s supported API/export method.
  2. Review customer mapping. Each exported party must map to an active DigiVista company ID; do not match by name alone.
  3. Your administrator sets BILLING_BRIDGE_SECRET as a server environment variable. Keep the same secret in the trusted desktop/partner adapter. Never put it in browser code, a screenshot or a public file.
  4. The adapter prepares the normalized JSON below and signs each request. The included scripts/push-busy-snapshot.mjs sender requires CRM_ORIGIN, BILLING_BRIDGE_SECRET and BUSY_SNAPSHOT_FILE.
  5. Send one test invoice. Verify amount, cumulative received amount, due date and company before enabling a recurring schedule.
  6. Send the same snapshot again: invoice values must remain unchanged. Test a newer payment update, an older conflicting snapshot, an invalid customer and a cancelled invoice.
  7. Review Billing overview → BUSY automatic sync. Rejected rows need review; a successful HTTP response can still contain rejected rows. Sender exits with code 2 when rows are rejected.

Normalized payload

{"provider":"BUSY","invoices":[{
"externalInvoiceId":"BUSY-company-FY-voucher-unique-id",
"invoiceNumber":"TEST-001","companyId":"exact-crm-company-id",
"invoiceDate":"2026-10-10","dueDate":"2026-10-20",
"currency":"INR","totalAmount":"50000.00","paidAmount":"20000.00",
"status":"Issued","sourceUpdatedAt":"2026-10-10T06:00:00Z"
}]}

Invoice identity must remain unique across company, financial year and voucher series. paidAmount is cumulative, never an additional receipt. Cancellation uses status Cancelled. Existing manual imports require approveExisting=true after review; future updates use strictly newer source timestamps.

POST /api/integrations/billing with x-crm-timestamp (Unix seconds) and x-crm-signature = lowercase HMAC-SHA256(secret, timestamp + '.' + exact request body). Signature expiry is five minutes. Send 1–100 invoices, maximum 500 KB per request.

Background reminders and owner brief

The included scripts/run-background-jobs.mjs invokes the existing secured /api/jobs endpoint. Schedule it every five minutes in a trusted runner using CRM_ORIGIN and CRM_JOB_TOKEN. Setting a token alone does not activate a schedule. In-app reminders do not send email or WhatsApp messages.

Six-feature setup and test checklist