Connectors

A Connector is the installed Windows agent that carries authorized work between Bizmitra and a locally accessible TallyPrime instance.

It is a component of your integration, not a standalone product a customer can buy and use on its own. It requires an application, a paired company, and a developer account behind it.

Why it exists

TallyPrime is desktop software running inside a business's own network. It has no public endpoint, and exposing one would be a poor idea even where it is technically possible.

The Connector inverts the direction. It sits next to Tally, reaches out to Bizmitra over HTTPS, collects work it is authorized to do, executes it locally, and reports back.

No inbound firewall rule. No port forwarding. No static IP. The customer's network stays closed.

The fleet problem

One Connector serves one machine. A partner with 400 customers is operating a fleet of roughly 400 Windows installations they do not own, cannot log into, and cannot reboot.

The connector API exists because of that:

GET    /api/v1/connectors                        # list the fleet
GET    /api/v1/connectors/{machine}              # one connector
GET    /api/v1/connectors/{machine}/companies    # what it serves
GET    /api/v1/connectors/{machine}/jobs         # sync history
GET    /api/v1/connectors/{machine}/business-hours
PATCH  /api/v1/connectors/{machine}/business-hours
PATCH  /api/v1/connectors/{machine}              # rename
POST   /api/v1/connectors/{machine}/disable      # stop it taking work
POST   /api/v1/connectors/{machine}/enable       # resume
DELETE /api/v1/connectors/{machine}              # remove

Build a support view over these early. When a customer says "it stopped working", the answer is almost always visible in the connector list and its job history — the machine went offline, Tally was closed, or the connector was disabled during an office move.

Remote business hours

Use business-hours mode when accounts staff need Tally to remain responsive during the working day. Incremental voucher sync and imports continue, but full sync and heavy reports are deferred until outside the configured window.

PATCH /api/v1/connectors/{machine}/business-hours
Authorization: Bearer {key_id}:{secret}
Content-Type: application/json

{
  "sync_mode": "business_hours",
  "business_hours_start": "10:00",
  "business_hours_end": "17:00",
  "business_days": [0, 1, 2, 3, 4, 5],
  "business_timezone": "Asia/Kolkata",
  "off_hours_full_sync_enabled": true
}

The update is partial: send only fields that should change. Times use 24-hour HH:MM; weekdays are Monday 0 through Sunday 6; and the timezone must be an IANA name. sync_mode accepts normal or business_hours. Set one field to null to remove that remote override and return it to the Connector's local configuration.

The app labels these differently

The API values are unchanged, but the Connector's own settings screen calls business_hours Business hours and normal Around the clock, and business_hours is its default. Use the app's wording when talking a customer through what you changed.

Read the current remote overrides with:

GET /api/v1/connectors/{machine}/business-hours

{
  "success": true,
  "machine_uuid": "muid-1",
  "settings": {
    "sync_mode": "business_hours",
    "business_hours_start": "10:00",
    "business_hours_end": "17:00",
    "business_days": [0, 1, 2, 3, 4, 5],
    "business_timezone": "Asia/Kolkata",
    "off_hours_full_sync_enabled": true
  },
  "effective_after": "next_connector_settings_poll",
  "maximum_propagation_seconds": 600
}

Changes normally reach an online Connector within 10 minutes and do not require a restart. A request is scoped to the authenticated developer; a machine belonging to another account returns 404.

WARNING

Business-hours mode is not a pause control. To stop a machine from processing work, use the disable endpoint. Setting off_hours_full_sync_enabled to false means deferred heavy work remains manual-only outside business hours.

Lifecycle

Disable is reversible and keeps the pairing. Use it during maintenance, or when a customer is in a billing dispute and you want writes to stop without tearing down their setup.

Delete removes the connector. The customer has to install and pair again.

Renaming

PATCH /api/v1/connectors/{machine}

Default machine names are not useful at scale. DESKTOP-4F9J2K1 tells you nothing when a support ticket arrives; Acme Ltd — Accounts PC tells you everything. Rename connectors as part of onboarding.

Pairing codes

Pairing is code-based rather than credential-based, so a customer never handles your API secret:

POST /api/v1/connectors/pairing-code               # generate
GET  /api/v1/connectors/pairing-codes              # list outstanding
POST /api/v1/connectors/pairing-codes/{id}/revoke  # revoke

Codes are short-lived and single-purpose. Revoke any that were issued and not used — an unredeemed code sitting in an old email is a loose end.

Walkthrough in Pairing a company.

Branded builds

An application can have its own Connector build carrying its name and identity. Covered in the Connectors section of these docs, which is not yet published — contact Bizmitra if you need it before then.