Integrations

Overview

Use this guide when you connect external systems to Numezis through webhooks, batch jobs, or custom middleware. Browser apps should start with Authentication; machine clients should combine auth, the API reference, and the rules below.

Webhooks

Inbound channel webhooks (for example Telegram or WhatsApp) are registered on the API and validated with provider signatures. Outbound notifications to your systems should treat delivery as at-least-once: implement idempotent handlers keyed by event id.

Typical flow:

1. Register the endpoint URL and secret in company or tenant settings.
2. Receive JSON payloads with event type, tenant/company scope, and entity ids.
3. Verify signature or shared secret before processing.
4. Respond with 2xx quickly; defer heavy work to your own queue.

Rate limits

Public and portal APIs apply per-tenant rate limits. Responses include standard rate-limit headers where applicable. Integrations should use exponential backoff on 429 and avoid tight polling loops—prefer webhooks or documented sync endpoints.

Idempotency

For POST operations that create business records (invoices, bills, payments), send a stable Idempotency-Key header when your client library supports it. Repeating the same key with the same body returns the original result instead of a duplicate document.

Structured errors

API errors use a consistent JSON envelope: machine-readable code, localized message for display, and optional details for validation fields. Map codes in your integration layer; do not parse English message text.

Related

• Authentication
• API reference
• MCP tools
• Developer overview

Feature coverage

No registry features are linked to this hub.