-
Notifications
You must be signed in to change notification settings - Fork 0
Integrations
External services GDX talks to. Everything here is optional — the app runs
without any of them, and each one lights up when its keys are configured (see
Configuration Reference; .env.template documents
every variable).
Two-way sync with QuickBooks Online: customers, invoices, payments, and expenses/bills.
- Pull — scheduled syncs plus Intuit webhooks on entity changes; incoming customers are matched to local records by fuzzy name + phone.
- Push — locally created/edited invoices are pushed back on a short cycle (a dirty flag marks what needs pushing).
-
Setup — an OAuth connect flow from the QuickBooks page (server-side
token exchange; tokens stored encrypted). Env:
QB_CLIENT_ID,QB_CLIENT_SECRET,QB_REDIRECT_URI,QB_ENVIRONMENT,QB_WEBHOOK_VERIFIER_TOKEN. - Budgets read the QB P&L for budget-vs-actual comparisons.
Online payments for invoices — customers pay via Stripe Checkout from a shared
invoice link or the Customer Portal, which also supports
saved payment methods and ACH with micro-deposit verification. Stripe
Connect onboarding (Express) is available for routing payments to a
connected account. The public payment endpoints are hardened: the pay token
scopes exactly one invoice, charge amounts are derived server-side from the
invoice (never trusted from the browser), and webhooks are
signature-verified — a failed or reversed charge flows back onto the
invoice. Env: STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY,
STRIPE_WEBHOOK_SECRET.
Connect bank accounts over the Banno Consumer API (the digital-banking
platform many community banks run): OAuth with PKCE, multi-institution,
synced transactions, and a statement archive — feeding
bank statement reconciliation.
Your bank has to provision API access for the app; see
BANKING_READINESS.md
for what to ask them for. BANK_FEEDS_REDIRECT_URI overrides the OAuth
callback URL when the default (built from the public base URL) isn't right.
VoIP integration: inbound/outbound call log, SMS threads, voicemail, faxes, click-to-call, and a cold-leads list of missed callers.
- Setup — paste your Phone.com API token in Settings → Integrations; the app validates it, discovers your extensions, and stores it encrypted. Pick a default extension/caller ID.
- Webhooks + polling + nightly reconciliation keep history complete: a 10-minute recent-calls poll lands voicemails within minutes even when webhooks misbehave, a nightly job pushes your customers to Phone.com as contacts (desk-phone caller ID shows names), and webhook URL secrets rotate weekly automatically.
- Outbound email — any SMTP provider, configured per tenant in Settings (with a send-test button). The system sends estimate/invoice emails, appointment reminders, review requests, payment reminders, and portal magic links through it.
-
Outlook / Microsoft 365 — optional per-employee mailbox sync via
Microsoft Graph OAuth: the Inbox module shows synced email, with webhook
subscriptions created on connect, renewed automatically (and re-created if
missing), and a 30-minute polling fallback. A sync-health monitor
raises an in-app banner (and an alarm) when a mailbox stops syncing, so a
silent failure can't go unnoticed for days. Graph needs a public HTTPS
notification URL — set
GDX_PUBLIC_BASE_URL(see Configuration Reference) or subscriptions can't be created. - Vendor paperwork by email — the mailbox sync can turn a supplier's emailed PDF invoice into a bill in the review queue, capture order confirmations, and ingest statements of account automatically (see Inventory & Purchasing). It is opt-in and off until you list senders: only mail from an address (or domain) you add to the vendor sender allowlist is ever processed — a stranger's attachment is never opened or parsed. Re-seeing the same message won't create a duplicate document.
Geocoding, drive-time estimates between jobs, route optimization, and service-area (polygon) checks on the dispatch side. Optional API key; the dispatch board works without it, minus traffic-aware features.
AI assists (quick estimates, line-item suggestions, message drafts) call any
OpenAI-compatible endpoint — a local vLLM/Ollama/LocalAI works. Configure
AI_PROVIDER_URL / AI_PROVIDER_MODEL / AI_PROVIDER_KEY, or set a
tenant-specific key in Admin → AI Settings (stored encrypted, validated on
save). Without a provider, every AI feature degrades gracefully to keyword
matching or built-in templates.
Your marketing site's contact form can create leads directly in GDX:
POST /api/v1/landing-leads with an API key scoped landing_leads:write
(minted in the /developer portal or via CLI). Each submission lands in the
leads triage list, notifies every user, and is audit-logged. Spam protection:
honeypot field, optional Cloudflare Turnstile (TURNSTILE_SECRET), and a
60 req/min per-key rate limit. Full setup guide, request reference, and
troubleshooting: Website Lead Intake.
Subscribe your own endpoints to app events: job.* (created/updated/
completed/cancelled), estimate.* (sent/accepted/declined), invoice.*
(created/sent/paid/overdue), customer.*, payment.*, appointment.*.
Managed under Admin → Webhooks, with a test-send button.
The app mounts a Model Context Protocol server at /mcp (Streamable
HTTP) exposing tools over customers, jobs, estimates, invoices, documents,
email, and scheduling for AI clients. Access is tenant-bound: every request
needs a JWT bearer issued for the instance's host (audience <host>/mcp),
signed with the deployment's JWT keys. The OAuth discovery documents are
published, but the authorize/token endpoints are not implemented yet, so
connector-style onboarding (e.g. from a chat product) can't complete —
tokens must be provisioned out of band. Treat MCP as experimental.
Celery beat drives the recurring machinery: hourly appointment-reminder
scans; daily recurring-job generation; Outlook subscription renewal (every
6h) with a 30-minute polling fallback and sync-health checks; the daily
vendor-bill/-statement email sweep; a 10-minute Phone.com recent-calls poll
plus nightly reconciliation, stats rollups, and customer→contact pushes, and
weekly webhook-secret rotation; nightly estimate-draft purge/archive and
estimate-expiry sweeps; nightly customer rolling-volume refreshes; daily
GPS-location pruning; a half-hourly timeclock sweep that closes forgotten
shifts; the per-tenant QuickBooks banking-sync dispatcher; nightly
forecasting snapshots and reconciliation; a nightly audit-chain
tamper-evidence check; the daily planner digest (when configured); and daily
billing follow-up + invoice reminder scans (automatic reminders are opt-in).
Two worker queues (priority:high for user-facing sends, priority:low for
batch work) — see Architecture.
- Configuration Reference — the env vars that turn each of these on.