Integrator Best-Practice Guide

Overview 🔗

This guide is for ticket-system vendors building a deep helpdesk integration with pcvisit (e.g. DocBee, or any partner using the Integrators enum). It focuses on recommendations, responsibilities, and pitfalls — not on repeating API call details.

Use this guide together with:

Audience: Product owners and engineers at ticket-system / PSA vendors who orchestrate onboarding, sessions, webhooks, and device matching on behalf of MSP customers.

Not in scope here: pcvisit backend internals, BPL bounded-context design, or pcvisit webapp UX implementation.

Mental Model 🔗

Closed loop 🔗

pcvisit acts as the process engine for remote support: sessions run in pcvisit, results are recorded in pcvisit work history, and session completion is pushed to your webhook. Your system closes the loop by attaching duration, participants, and comments to the correct ticket and device.

flowchart LR
    subgraph integrator [Your ticket system]
        Onboard[Onboard MSP]
        Ticket[Ticket and device DB]
        WebhookEP[Webhook endpoint]
    end
    subgraph pcvisit [pcvisit]
        API[GraphQL API]
        Session[Remote session]
        WH[Webhook delivery]
    end
    Onboard -->|activate token register webhook| API
    API -->|asset sync thirdPartyIds| Ticket
    Ticket -->|SSO URL ticket_ref| Session
    Session -->|SessionCompleted| WH
    WH --> WebhookEP
    WebhookEP --> Ticket

Responsibility split 🔗

Recommended Integration Sequence 🔗

Follow these phases in order for a minimal viable integration. Step-by-step API examples live in the Integration Manual — Integrator Integration.

Pilot recommendation: Implement Phase 1 + outbound session with ticket_ref + SessionCompleted webhook before optional features (JWE credentials, live asset subscription, inbound-only sessions).

Best Practices by Topic 🔗

Onboarding and provisioning 🔗

• Always pre-check with SiFindUserByMail before creating a company — avoids duplicate accounts and drives the correct branch (new vs. existing customer). See Manual — Pre-Check.
• Prefer API-only onboarding — there is no web handshake, return_url, or redirect flow. Your UI owns the entire journey.
• Treat CaCreateIntegration as idempotent in intent — one active integration per integrator + company; store the returned CreatedIntegration.token in your secrets store (never in client-side code or logs).
• Register the webhook immediately after activation (CaRegisterIntegrationWebhook). Without it, session results have nowhere to go.
• For existing accounts, resolve eligible companies via FindCompanyTeam + CaRetrievePublicCompanyData; only owner/admin roles may bind the integration.
• Optional tenantUrl on CreateIntegrationInput: use when MSPs configure integration from the pcvisit webapp (inbound path); not required for outbound-only onboarding.

Token and JWT handling 🔗

• Two token layers: partner-wide credentials for provisioning vs. per-company integrator token (CreatedIntegration.token) for day-to-day operations. Scope API calls accordingly.
• SSO JWTs are short-lived — request via SiRetrieveSignedJwt immediately before opening the session URL; do not cache them for reuse across tickets.
• Detect revoked integrations: if the integrator token fails authentication (e.g. on SiRetrieveSignedJwt or asset sync), treat it as integration detached — pcvisit does not push an active callback when the admin removes the integration in the pcvisit UI. Prompt the MSP to re-link. See Manual — Step 9.

Team membership (no auto-join) 🔗

• Never assume a technician is already in the pcvisit team. Call InviteToCompanyTeamOnBehalfOfIntegrator once before their first session.
• Handle TeamUserLimitReached by surfacing Failure.comment_for_user to the technician and routing upgrade actions to the company owner.
• Removal via SiRemoveFromCompanyTeam triggers owner notification — set expectations in your admin UI.

SSO and impersonation 🔗

• Pass targetUserEmail to issue a JWT for that technician (impersonation). Without it, the JWT is for the integrator identity only.
• If SSO fails with SiSignedJwtTargetNotTeammember, add the technician first — do not retry SSO in a loop.
• Request requestEncryptionKey: true only when you will pass JWE credentials in the same flow — RSA key generation is expensive and unnecessary otherwise.

JWE credential handover 🔗

• Use JWE only for known devices (/computer/{id} URLs). Ad-hoc sessions have no fixed target at URL build time.
• Never put credentials in clear text in URLs or GraphQL. Encrypt with the JWK from SiRetrieveSignedJwt (RSA-OAEP + A256GCM). Details: Manual — Step 5.
• Do not call SiDecryptAuthToken from your backend in production flows — the pcvisit webapp consumes auth_token once. Your job is to build the JWE, not to decrypt it.

Webhooks 🔗

• Mandatory: Verify X-Pcvisit-Signature = HMAC-SHA256(signingSecret, raw_body) on every request. Reject unsigned or invalid payloads.
• Idempotency: De-duplicate on data.taskId, not deliveryId — retries get a new deliveryId but the same task.
• Response semantics:
  • HTTP 2xx — accepted; pcvisit stops retrying for that attempt.
  • HTTP 4xx — no retry; return a clear JSON { "message": "..." } for display in pcvisit admin UI.
  • HTTP 5xx / timeout — pcvisit retries with backoff; your handler must stay idempotent.
• Do not poll session history to replace webhooks — pcvisit owns delivery and recovery.
• Pilot scope: Subscribe to SessionCompleted only; SessionStarted and SessionParticipantChanged are reserved for later phases.

Full payload and headers: Manual — Step 8.

Device matching 🔗

• Initial sync: FindCurrentAssets with baseDN depth sub from root (see BaseDN).
• Ongoing sync: Prefer AmFindAssets subscription for online/offline and ID updates; fall back to periodic full query if WebSocket infrastructure is unavailable.
• Matching priority: Compare ThirdPartyIds fields your product already stores (e.g. ninjaOneDeviceId, teamViewerId, dattoAgentId); use siteId for same-network clustering; use customIds for vendor-specific fallbacks.
• Availability: Not every ID is present on every device immediately — agent collectors roll out over time. Design matching to tolerate partial thirdPartyIds and enrich on later syncs/webhooks.
• Tree, not flat list: Assets include Folder and Computer nodes — use GraphQL inline fragments; folder semantics are MSP-defined (customer, site, department).

External session context 🔗

• Pass ExternalSessionContext when creating sessions via API, or ticket_ref on the session-start URL for browser flows.
• Conventions: Set integratorId consistently; use ticketId for your ticket key; optional externalDeviceRef for your device primary key; metadata for non-standard tags (keep keys stable).
• Inbound sessions (started in pcvisit without ticket): rely on webhook thirdPartyIds + computerId for post-hoc ticket/device assignment.

Error handling 🔗

• Always handle the Failure union branch on mutations and queries.
• Show comment_for_user in your UI — do not parse or rewrite it; do not expose raw error codes to end users.
• Branch logic on error (ErrorIDs) for retries, re-link flows, and owner vs. technician routing.
• Integrator-relevant codes (see Manual — Error Handling): SiSignedJwtTargetNotTeammember, SiSignedJwtLimitExceeded, TeamUserLimitReached, plus CanceledSubscription / FeatureNotLicensed where applicable.

Resilience and data loss 🔗

• Session data remains in pcvisit work history even if webhook delivery fails — pcvisit retries and runs internal recovery (~24h). Recommend MSPs keep work-history licensing as a safety net.
• Your webhook endpoint must be highly available — use idempotent handlers and monitor 4xx rates (they are not retried).
• Asset sync gaps: If sync fails due to invalid token, pause sync and surface re-link — do not silently drop device mappings.

User communication (pass-through) 🔗

pcvisit sends lifecycle e-mails and provides webapp touchpoints (onboarding, trial limits, integration removed). Your responsibilities:

• Display comment_for_user from API failures directly in ticket/session UI.
• On integrator-token auth failure, guide admin to re-link integration.
• Link to pcvisit-hosted informational pages where provided — do not duplicate long-form pcvisit legal/product copy in your product.

Rollout Recommendations 🔗

1. Sandbox first — use a dedicated stage GraphQL endpoint and test full loop: provision → webhook → SSO URL → complete session → receive webhook.
2. MVP feature set: SiFindUserByMail, FirstTimeCustomerPlaceOrderOnBehalfOfIntegrator or link path, CaCreateIntegration, CaRegisterIntegrationWebhook, InviteToCompanyTeamOnBehalfOfIntegrator, SiRetrieveSignedJwt, session URL with ticket_ref, FindCurrentAssets, SessionCompleted handler.
3. Phase 2 enhancements: JWE credentials, AmFindAssets live sync, inbound session matching, CaDeleteIntegration admin action.
4. Security review checklist: Token storage, webhook HMAC, TLS-only callback URL, no credential logging, JWE only on known devices.

Quick Reference Map 🔗

DocBee as Reference Implementation 🔗

Throughout the Integration Manual, DocBee is used as the concrete integratorId example. The same patterns apply to any vendor entry in Integrators once enabled for your partner credentials.

When comparing against internal specs, treat the published Manual and API Reference as the contract for implementation; they are aligned with the current GraphQL schema in public_api.schema.json.