Project-Pro/orderPRO
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: rename codebase map files to lowercase

Browse Source
This commit is contained in:
Jacek Pyziak
2026-04-26 21:41:04 +02:00
parent b1b2cc5827
commit ca7540d374
7 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
.paul/codebase/integrations.md Normal file
View File

@@ -0,0 +1,116 @@
# 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 |