# External Integrations

## Allegro (Polish e-commerce — OAuth2)

**Auth:** OAuth2 Authorization Code Grant  
**Scopes:** `orders:read/write`, `sale:offers:read`, `shipments:read/write`  
**Token storage:** Encrypted in `allegro_integration_settings`  
**Token refresh:** `AllegroTokenManager` — auto-refreshes before expiry  
**User-Agent:** Required from 01.07.2026 (env: `ALLEGRO_USER_AGENT_URL`)

| File | Purpose |
|------|---------|
| `src/Modules/Settings/AllegroApiClient.php` | REST calls: `getCheckoutForm()`, `listCheckoutForms()`, `getCheckoutFormShipments()` |
| `src/Modules/Settings/AllegroOAuthClient.php` | OAuth2 flow, token exchange |
| `src/Modules/Settings/AllegroTokenManager.php` | Token refresh & storage |
| `src/Modules/Settings/AllegroOrderImportService.php` | Transform & insert Allegro orders |
| `src/Modules/Settings/AllegroOrdersSyncService.php` | Continuous order sync |
| `src/Modules/Settings/AllegroStatusSyncService.php` | Push status changes to Allegro |
| `src/Modules/Settings/AllegroStatusDiscoveryService.php` | Fetch available Allegro statuses |
| `src/Modules/Shipments/AllegroShipmentService.php` | Create shipments via Allegro |
| `src/Modules/Shipments/AllegroTrackingService.php` | Track delivery status |

## shopPRO (Polish e-commerce — API Key)

**Auth:** API Key + Base URL in integration config  
**Pagination:** page/per_page, max 100 items  
**Date filter:** `updated_from` parameter

| File | Purpose |
|------|---------|
| `src/Modules/Settings/ShopproApiClient.php` | `fetchOrders()`, status/payment sync |
| `src/Modules/Settings/ShopproOrdersSyncService.php` | Order import/sync |
| `src/Modules/Settings/ShopproPaymentStatusSyncService.php` | Payment sync |
| `src/Modules/Settings/ShopproStatusSyncService.php` | Status mapping |
| `src/Modules/Settings/ShopproOrderMapper.php` | Order transformation (867 LOC) |

## Apaczka (Polish parcel aggregator)

**Auth:** App ID + App Secret  
**Base URL:** `https://www.apaczka.pl/api/v2`  
**Custom exception:** `src/Core/Exceptions/ApaczkaApiException.php`

| File | Purpose |
|------|---------|
| `src/Modules/Settings/ApaczkaApiClient.php` | `getServiceStructure()`, `sendOrder()`, `getOrderDetails()`, `getWaybill()` |
| `src/Modules/Shipments/ApaczkaShipmentService.php` | Implements `ShipmentProviderInterface` |
| `src/Modules/Shipments/ApaczkaTrackingService.php` | Implements `ShipmentTrackingInterface` |

## InPost (Parcel lockers + courier)

**Auth:** Organization token  
**Production:** `https://api-shipx-pl.easypack24.net/v1`  
**Sandbox:** `https://sandbox-api-shipx-pl.easypack24.net/v1`  
**Services:** Paczkomat Standard, Kurier Standard, Kurier Express

| File | Purpose |
|------|---------|
| `src/Modules/Shipments/InpostShipmentService.php` | Create shipments |
| `src/Modules/Shipments/InpostTrackingService.php` | Track delivery status |

## Provider Abstraction

Shipment providers implement a common interface:
- `ShipmentProviderInterface` — `createShipment()`, `downloadLabel()`
- `ShipmentTrackingInterface` — `getDeliveryStatus()`
- `ShipmentProviderRegistry` — selects correct provider by type
- `ShipmentTrackingRegistry` — selects correct tracker

## Email (SMTP via PHPMailer)

**Library:** PHPMailer 7.0  
**Config:** Multiple mailboxes from DB (`EmailMailboxRepository`)  
**Features:** HTML + attachments, template variable resolution, logging

| File | Purpose |
|------|---------|
| `src/Modules/Email/EmailSendingService.php` | Compose & send via configured mailbox |
| `src/Modules/Email/VariableResolver.php` | Replace `{{var}}` in templates with order data |
| `src/Modules/Email/AttachmentGenerator.php` | Generate PDF attachments via Dompdf |
| `src/Modules/Email/EmailMailboxRepository.php` | SMTP credentials & config |
| `src/Modules/Email/EmailTemplateRepository.php` | Email template storage |

## Print Queue API (Windows client)

**Auth:** Bearer API key (header `Authorization: Bearer {key}`)  
**Purpose:** Windows desktop client retrieves print jobs (shipment labels)

| File | Purpose |
|------|---------|
| `src/Modules/Printing/PrintApiController.php` | `POST /api/print/jobs`, status endpoints |
| `src/Modules/Printing/ApiKeyMiddleware.php` | Validates API key against DB |
| `src/Modules/Printing/PrintApiKeyRepository.php` | API key management |
| `src/Modules/Printing/PrintJobRepository.php` | Job queue tracking |

## PDF & Excel (Libraries)

| Library | Version | Used For |
|---------|---------|---------|
| `dompdf/dompdf` | ^3.1 | Receipts, invoices, email attachments |
| `phpoffice/phpspreadsheet` | ^5.5 | Accounting export to XLSX |

## SSL / HTTP

All external API calls use cURL with certificate validation.  
Resolver: `src/Core/Http/SslCertificateResolver.php`  
Config: `CURL_CA_BUNDLE_PATH` in `.env`

## Integration Config Storage

| Table | Contents |
|-------|---------|
| `integrations` | Base record (source type, enabled, API key encrypted) |
| `allegro_integration_settings` | OAuth tokens (encrypted), Allegro-specific config |
| `*_status_mappings` | Bidirectional status code translations |
| `email_mailboxes` | SMTP connection settings |
| `print_api_keys` | Print client API keys |