2.2 KiB
2.2 KiB
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 Logand 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.