# 22 — Integration & API Layer

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

---

## Goal

Covers [mainPlan.md §16](./mainPlan.md#16-integration--api-layer) 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](./19_finance_accounting.md)) |
| `syncTelematicsData(vehicleId, provider)` | Internal/background job — feeds `recordVehicleTelemetry` ([13_fleet_management.md](./13_fleet_management.md)) |
| `pushOrderToDistributorPortal(orderId)` | Internal/background job — triggered on order status change ([05_delivery_ride.md](./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.