117 lines
5.1 KiB
Markdown
117 lines
5.1 KiB
Markdown
# 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 |
|