22 — Integration & API Layer

Status: Not Started Depends On: 19 — Finance & Accounting, 13 — Fleet Management

Goal

Covers mainPlan.md §16 in full — outbound/inbound integration with third-party systems.

Background / Context

No external system integration exists today. Each function here depends on a specific named third-party provider (accounting platform, telematics provider, B2B portal) that hasn't been chosen yet — this step cannot be scoped precisely until that choice is made per Open Questions.

Data Model Changes

Integration Sync Log

TargetSystem, EntityType, EntityId, Status (Success, Failed, Retrying), AttemptedAt, ErrorDetail (nullable).

API Endpoints

Function reference	Endpoint intent
`syncToAccountingSystem(transactionId, targetSystem)`	Internal/background job — triggered on GL posting (19_finance_accounting.md)
`syncTelematicsData(vehicleId, provider)`	Internal/background job — feeds `recordVehicleTelemetry` (13_fleet_management.md)
`pushOrderToDistributorPortal(orderId)`	Internal/background job — triggered on order status change (05_delivery_ride.md)
—	`GET /api/integrations/sync-log?targetSystem=...` — for support/debugging

Business Rules

Every outbound sync must be retryable and idempotent — a failed sync logs to Integration Sync Log and retries rather than silently dropping.
No integration should be able to block the originating business transaction (order creation, GL posting) — sync happens after commit, asynchronously.

Open Questions

Which accounting platform (QuickBooks/SAP/Xero — reference doc names all three as examples), and which telematics provider — is either actually contracted yet, or is this step purely speculative until a vendor is chosen?
Does a "distributor-facing B2B portal" already exist to push orders to, or is this describing a future/external system not yet built?

Implementation Notes

Fill this section in during planning discussion before writing any code.

2.2 KiB Raw Permalink Blame History