# Key Integrations

# Key Integrations

## Integration Priority Table

| Integration | Type | Priority | Launch Date |
|-------------|------|----------|-------------|
| **Fortnox** | REST v3, OAuth2 | **P0** | **Launch** |
| **PostNord** | REST, OAuth2 | **P0** | **Launch** |
| DHL Sweden | REST | P1 | Month 2 |
| Instabee / Budbee | REST JSON | P1 | Month 3 |
| Shopify | REST + GraphQL | P1 | Month 3 |
| WooCommerce | REST | P2 | Month 6 |
| Visma | REST | P2 | Month 6 |

---

## P0 — Fortnox (Launch Critical)

**Why P0:** 598,000 Swedish companies use Fortnox. Fortnox Marketplace is the primary distribution channel. Deep integration = instant value for every new customer.

**API:** Fortnox REST API v3 (api.fortnox.se)
**Auth:** OAuth2 (authorisation code flow)

### Sync scope
| Data | Direction | Frequency |
|------|-----------|-----------|
| Products (artiklar) | Fortnox to Plock | On demand + webhook |
| Suppliers (leverantorer) | Fortnox to Plock | On demand |
| Purchase orders | Bidirectional | Real-time |
| Sales orders | Fortnox to Plock | Real-time (webhook) |
| Stock levels | Plock to Fortnox | On every transaction |
| Invoices | Plock to Fortnox | On order completion |

### Fortnox Marketplace listing
- Plock listed as official Fortnox Marketplace integration
- Customers connect via OAuth flow directly from Fortnox UI
- Integration reviewed and certified by Fortnox team

---

## P0 — PostNord (Launch Critical)

**Why P0:** PostNord is the dominant carrier for Swedish e-commerce (primary for ~70% of SMBs).

**API:** PostNord REST API (developer.postnord.com)
**Auth:** OAuth2

### Features
- Generate shipping labels (PDF + ZPL for Zebra printers)
- Book pickup
- Track shipments (webhook updates)
- Print manifests at end of day
- Support for: PostNord MyPack, Varubrev, DHL Parcel (via PostNord reseller)

---

## P1 — DHL Sweden (Month 2)

**API:** DHL Express REST (developer.dhl.com)
**Features:** Label generation, booking, tracking, rate quotes
**Auth:** API key

---

## P1 — Instabee / Budbee (Month 3)

**API:** Instabee REST JSON (developer.budbee.com)
**Features:** Label generation, booking, real-time tracking, consumer notifications
**Note:** Instabee acquired Budbee — same API, two brands

---

## P1 — Shopify (Month 3)

**API:** Shopify REST Admin API + GraphQL
**Auth:** OAuth2 (Shopify Partner app)

### Sync scope
- Orders to Plock outbound queue
- Inventory levels bidirectional (Plock as source of truth)
- Product catalogue to Plock (read-only)
- Fulfilment events to Shopify order tracking

---

## P2 — WooCommerce (Month 6)

**API:** WooCommerce REST API
**Auth:** API key
**Sync scope:** Orders, products, inventory levels (similar to Shopify)

---

## P2 — Visma (Month 6)

**API:** Visma eAccounting REST API
**Auth:** OAuth2
**Sync scope:** Similar to Fortnox — products, orders, invoices, stock levels

---

## Integration Architecture

All integrations run through the Integration Layer in the Kotlin backend:

**File structure:**
- integrations/fortnox/ — FortnoxClient.kt, FortnoxSyncService.kt, FortnoxWebhookHandler.kt
- integrations/carriers/ — PostNordClient.kt, DhlClient.kt, InstabeeClient.kt
- integrations/ecommerce/ — ShopifyClient.kt, WooCommerceClient.kt

**Queue:** Redis + Kotlin coroutines for async integration jobs (label generation, carrier calls, sync tasks)

**Error handling:** Retry with exponential backoff, dead-letter queue, alert on persistent failure