Developer Hub

EVCare Pro Integration Developer Hub

Central portal for external website/web app/platform integrations. Includes authentication, access bundles, federated sign-in, webhook reliability, and billing integration guidance.

Access Bundles
External platforms choose one or more access bundles; endpoint allowlist remains the final policy gate.

ORGANIZATION_ACCESS

Organization-wide management endpoints and subordinate account operations.

FLEET_MANAGER_ACCESS

Fleet-scoped vehicles, maintenance, drivers, and tickets.

CLIENT_ACCESS

Client/driver self-service, tickets, and platform sign-in bridge.

ALL_ACCESS

Union of all capabilities including embed portal and federated sign-in.

Quickstart (cURL)
End-to-end sequence: credentials, token issuance, user exchange, session redemption, and payment init.
# 1) Create integration in Admin UI (/admin/integrations) and receive clientId/clientSecret

# 2) Issue machine token
curl -X POST "$API_BASE/v1/integrations/auth/client-token" \
  -H "Content-Type: application/json" \
  -d '{"clientId":"evc_ci_xxx","clientSecret":"evc_cs_xxx"}'

# 3) Exchange external user identity
curl -X POST "$API_BASE/v1/integrations/auth/exchange" \
  -H "Authorization: Bearer $INTEGRATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"integrationId":"int_123","externalSubject":"ext_123","email":"user@example.com","roleHint":"CLIENT"}'

# 4) Redeem session code in browser
curl -X POST "$API_BASE/v1/integrations/auth/session" \
  -H "Content-Type: application/json" \
  -d '{"sessionCode":"evc_session_xxx"}'

# 5) Initialize payment (idempotency key required)
curl -X POST "$API_BASE/v1/integrations/int_123/billing/paystack/initialize" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Idempotency-Key: init-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{"email":"billing@partner.com","amount":1200,"currency":"GHS"}'
How External Platforms Connect
Every external integration receives generated credentials and can authenticate through OAuth2/OIDC.

1. Admin creates an integration at POST /v1/integrations.

2. EVCare returns one-time clientId and clientSecret.

3. Partner backend exchanges credentials for a short-lived token at POST /v1/integrations/auth/client-token.

4. External user identity is mapped to EVCare with POST /v1/integrations/auth/exchange.

5. Browser session is established through POST /v1/integrations/auth/session.

Access Questionnaire (Interactive)
Submit your integration requirements to get a recommended access bundle, confidence score, and scope hints.

Requires authenticated admin access to call /v1/integrations/questionnaire/recommend.

Documentation Library
Share these documents with external developers integrating to EVCare Pro.

Developer Hub Index

Master table of contents for all integration docs.

docs/developer-hub/README.md

Quickstart

5-step integration bootstrap with cURL examples.

docs/developer-hub/01-quickstart.md

Authentication and Credentials

Client ID/secret, token exchange, rotation, and revocation.

docs/developer-hub/02-authentication.md

Federated Sign-In and Embed

External user login, session code redemption, and hosted embed flow.

docs/developer-hub/03-federated-login-and-embed.md

Access Bundles and Endpoint Selection

Bundle decision guide and allowlist strategy.

docs/developer-hub/04-access-bundles-and-endpoint-selection.md

Webhooks and Delivery Reliability

Configuration, delivery logs, retries, and replay.

docs/developer-hub/05-webhooks-and-reliability.md

Subscriptions and Paystack

Usage metering, invoices, initialize/verify/webhook payment lifecycle.

docs/developer-hub/06-subscriptions-and-paystack.md

Errors, Idempotency, and Security

Error matrix, required headers, signatures, and secure operation.

docs/developer-hub/07-errors-idempotency-and-security.md

Testing and Go-Live Checklist

Validation checklist and production readiness.

docs/developer-hub/08-testing-and-go-live.md

Maintenance Service Selection

Configure allowed organizations/workshops and independent workshop selection.

docs/developer-hub/09-maintenance-service-selection.md

Troubleshooting Matrix

Common integration failures and precise remediation steps.

docs/developer-hub/10-troubleshooting-matrix.md

Questionnaire and Access Recommender

Integrator questionnaire, confidence score, and rationale output.

docs/integrations/questionnaire.md

Security and Reliability Deep Dive

Platform security posture, integrity controls, and reliability guarantees.

docs/integrations/security-and-reliability.md

Backward Compatibility Guide

Migration and coexistence guidance for existing integrations.

docs/integrations/migration-and-backward-compat.md

OpenAPI Contract

Formal integration API spec with examples and reusable error responses.

functions/src/config/integrations.openapi.yaml