---
phase: 127-erli-integration-foundation
plan: 01
subsystem: settings, integrations, api, database
tags: [erli, marketplace, integration-settings, api-client, encrypted-secrets]

requires:
  - phase: 113-fakturownia-integration-foundation
    provides: integrations hub test-result pattern and encrypted integration settings
  - phase: 117-smsplanet-integration-settings
    provides: single global settings + real API test pattern
provides:
  - single global Erli API configuration
  - encrypted Erli Bearer API key storage
  - real Erli connection test via GET /inbox
  - Erli row in integrations hub
affects: [erli-orders-import, erli-status-sync, erli-shipments, erli-tracking]

tech-stack:
  added: []
  patterns: [single-global-marketplace-settings, encrypted-bearer-api-key, real-readonly-api-test]

key-files:
  created:
    - database/migrations/20260515_000114_create_erli_integration_settings.sql
    - src/Modules/Settings/ErliIntegrationRepository.php
    - src/Modules/Settings/ErliApiClient.php
    - src/Modules/Settings/ErliIntegrationController.php
    - resources/views/settings/erli.php
  modified:
    - src/Modules/Settings/IntegrationsHubController.php
    - routes/web.php
    - resources/lang/pl.php
    - DOCS/DB_SCHEMA.md
    - DOCS/ARCHITECTURE.md
    - DOCS/TECH_CHANGELOG.md
    - .paul/ROADMAP.md
    - .paul/STATE.md

key-decisions:
  - "Erli starts as one global configuration, not multi-account"
  - "No sandbox/environment switch in Phase 127"
  - "Connection test performs a real read-only Erli API request"

patterns-established:
  - "Erli settings mirror Fakturownia/SMSPLANET single-row repository pattern"
  - "Erli API test uses Authorization: Bearer plus User-Agent and stores result in integrations.last_test_*"

duration: ~20min
started: 2026-05-15T23:00:00+02:00
completed: 2026-05-15T23:19:00+02:00
---

# Phase 127 Plan 01: Erli Integration Foundation Summary

**Single global Erli marketplace configuration with encrypted API key storage, real read-only API test, settings UI, and integrations hub row.**

## Performance

| Metric | Value |
|--------|-------|
| Duration | ~20min |
| Started | 2026-05-15T23:00:00+02:00 |
| Completed | 2026-05-15T23:19:00+02:00 |
| Tasks | 3 completed |
| Files created | 6 |
| Files modified | 8 |

## Acceptance Criteria Results

| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Schema And Single Integration Row | Pass | Migration creates `erli_integration_settings`, seeds/updates `integrations.type='erli'`, fixed row `id=1`, encrypted key column. |
| AC-2: Save Erli Configuration | Pass | `/settings/integrations/erli/save` validates CSRF, saves label/API key/active flag, preserves secret on empty input, shows saved/missing state. |
| AC-3: Real API Connection Test | Pass | `ErliApiClient::testConnection()` performs authenticated `GET /inbox`; controller stores `integrations.last_test_*`. Live test awaits real credentials. |
| AC-4: Integrations Hub Visibility | Pass | `IntegrationsHubController::buildErliRow()` adds Erli with configured/missing, active, last test and configure link. |
| AC-5: Documentation Updated | Pass | `DOCS/DB_SCHEMA.md`, `DOCS/ARCHITECTURE.md`, `DOCS/TECH_CHANGELOG.md` updated. |

## Accomplishments

- Added global Erli settings table and repository with encrypted Bearer API key handling.
- Added real connection-test client for official Erli API using `GET https://erli.pl/svc/shop-api/inbox`.
- Added authenticated settings routes and compact UI under `/settings/integrations/erli`.
- Added Erli to the integrations hub.
- Documented schema, architecture and technical changelog.

## Task Commits

No per-task commits were created during APPLY. Phase commit is created during UNIFY transition.

## Files Created/Modified

| File | Change | Purpose |
|------|--------|---------|
| `database/migrations/20260515_000114_create_erli_integration_settings.sql` | Created | Global Erli config table and base integration seed. |
| `src/Modules/Settings/ErliIntegrationRepository.php` | Created | Settings persistence, secret encryption, active credentials. |
| `src/Modules/Settings/ErliApiClient.php` | Created | Real read-only Erli API connection test. |
| `src/Modules/Settings/ErliIntegrationController.php` | Created | Settings page, save action, test action. |
| `resources/views/settings/erli.php` | Created | Erli settings and test UI. |
| `routes/web.php` | Modified | Erli DI wiring and routes. |
| `resources/lang/pl.php` | Modified | Erli translations and hub provider label. |
| `src/Modules/Settings/IntegrationsHubController.php` | Modified | Erli row in integrations hub. |
| `DOCS/DB_SCHEMA.md` | Modified | Added `erli_integration_settings`. |
| `DOCS/ARCHITECTURE.md` | Modified | Added Erli foundation flow/classes. |
| `DOCS/TECH_CHANGELOG.md` | Modified | Added Phase 127 technical entry. |

## Decisions Made

| Decision | Rationale | Impact |
|----------|-----------|--------|
| Single global Erli configuration | User chose one global account; matches small single-instance integration pattern. | Future phases use one Erli integration id unless requirements change. |
| No sandbox switch | User explicitly declined sandbox/environment toggle. | UI/schema stay simpler; live testing uses production API credentials. |
| Real read-only connection test | User required a real API test. | Test uses `GET /inbox`, but does not import or mark messages read. |

## Deviations from Plan

### Summary

| Type | Count | Impact |
|------|-------|--------|
| Deferred | 2 | Environment/live resources needed |
| Scope additions | 0 | None |
| Auto-fixed | 0 | None |

### Deferred Items

- Run `php bin/migrate.php` when local MySQL/XAMPP is online.
- Save real Erli API key and perform manual `/settings/integrations/erli` connection test.
- `sonar-scanner` was not available in PATH, so scan was not run.

## Issues Encountered

| Issue | Resolution |
|-------|------------|
| Live API verification needs real Erli credentials | Implemented real test path and documented manual follow-up. |
| SonarQube CLI missing from PATH | Documented as verification gap. |

## Verification Results

| Check | Result |
|-------|--------|
| `php -l src/Modules/Settings/ErliIntegrationRepository.php` | Pass |
| `php -l src/Modules/Settings/ErliApiClient.php` | Pass |
| `php -l src/Modules/Settings/ErliIntegrationController.php` | Pass |
| `php -l src/Modules/Settings/IntegrationsHubController.php` | Pass |
| `php -l resources/views/settings/erli.php` | Pass |
| `php -l routes/web.php` | Pass |
| `php -l resources/lang/pl.php` | Pass |
| `git diff --check` | Pass; only CRLF warnings from Git |

## Next Phase Readiness

**Ready:**
- Erli credentials can be stored and decrypted by future import/status/shipment services.
- Hub and last-test result contract is available for operator visibility.
- API client establishes header, timeout, SSL and error-handling pattern for future Erli calls.

**Concerns:**
- Real credentials and migration smoke remain manual follow-up.
- `/inbox` test endpoint checks authorization but does not verify order payload mapping yet.

**Blockers:**
- None for planning Phase 128.

---
*Phase: 127-erli-integration-foundation, Plan: 01*
*Completed: 2026-05-15*
