143 lines
5.3 KiB
Markdown
143 lines
5.3 KiB
Markdown
# Plan integracji MojeGS1 API - przypisywanie EAN z poziomu orderPRO
|
|
|
|
## Cel
|
|
Przycisk "Przypisz EAN z GS1" na stronie szczegółów produktu (`/products/{id}`), który automatycznie generuje kolejny EAN z puli GS1, rejestruje produkt w MojeGS1 i zapisuje EAN lokalnie.
|
|
|
|
## API MojeGS1 v2
|
|
- **Base URL:** `https://mojegs1.pl/api/v2`
|
|
- **Auth:** HTTP Basic (login + hasło)
|
|
- **Spec:** `/api/v2/swagger/external-api/swagger.json`
|
|
|
|
### Endpointy używane:
|
|
- `GET /api/v2/products?page[offset]=X&page[limit]=100&sort=name` — lista produktów (paginacja)
|
|
- `GET /api/v2/products/{Gtin}` — pojedynczy produkt
|
|
- `PUT /api/v2/products/{Gtin}` — utwórz/aktualizuj produkt
|
|
|
|
### Wymagane pola PUT:
|
|
- `brandName` (2-200 znaków) — marka
|
|
- `gpcCode` (8-cyfrowy int) — kod klasyfikacji GPC
|
|
- `netContent` (number) + `netContentUnit` (string: szt, kg, g, l, ml, m, cm, mm, m2, m3)
|
|
- `status` — "ACT" / "WIT" / "HID"
|
|
- `targetMarket` — array, np. ["PL"]
|
|
- `descriptionLanguage` — "PL"
|
|
- `description` — opis (20-4000 znaków, opcjonalne ale zalecane)
|
|
- `commonName` — nazwa zwyczajowa (do 150 znaków)
|
|
|
|
### Struktura request PUT:
|
|
```json
|
|
{
|
|
"data": {
|
|
"type": "products",
|
|
"id": "{GTIN-13}",
|
|
"attributes": {
|
|
"brandName": "marianek.pl",
|
|
"commonName": "Nazwa produktu",
|
|
"gpcCode": 10008365,
|
|
"netContent": 1,
|
|
"netContentUnit": "szt",
|
|
"status": "ACT",
|
|
"targetMarket": ["PL"],
|
|
"descriptionLanguage": "PL"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Stan konta GS1
|
|
- 461 produktów zarejestrowanych
|
|
- **Główny prefiks:** `590532390` (9 cyfr, 451 produktów, ciągła sekwencja 000-450)
|
|
- Drugi prefiks: `590531617` (10 produktów, starsze)
|
|
- Najwyższy GTIN: `5905323904507` (item 450)
|
|
- Następny wolny: `5905323904514` (item 451)
|
|
- Max capacity: 1000 produktów (item 000-999)
|
|
|
|
## Dane dostępowe API
|
|
- Login: `user_85c27342-bc97-4f42-8890-f6b27d3233c4`
|
|
- Hasło: `K3sawGA3X?L?e^bJ$ZqyhieFG)w#c8f+?V^z`
|
|
- **UWAGA:** dane przechowywane w tabeli `app_settings`, NIE w kodzie
|
|
|
|
## Plan implementacji
|
|
|
|
### Krok 1: Tabela app_settings — migracja
|
|
Plik: `database/migrations/20260224_000013_add_gs1_settings.sql`
|
|
Dodać rekordy do `app_settings`:
|
|
- `gs1_api_login` — login API
|
|
- `gs1_api_password` — hasło API (zaszyfrowane lub plain — zależy od obecnego wzorca)
|
|
- `gs1_prefix` — prefiks GS1 (domyślnie `590532390`)
|
|
- `gs1_default_brand` — domyślna marka (domyślnie `marianek.pl`)
|
|
- `gs1_default_gpc_code` — domyślny kod GPC (domyślnie `10008365`)
|
|
|
|
Sprawdzić czy tabela `app_settings` już istnieje (migracja 000012).
|
|
|
|
### Krok 2: Strona ustawień GS1
|
|
Plik widoku: `resources/views/settings/gs1.php`
|
|
Pliki PHP: zmiana w `SettingsController.php` — dodać metody `gs1()` i `gs1Save()`
|
|
Route: `GET /settings/gs1` + `POST /settings/gs1`
|
|
|
|
Formularz z polami: login, hasło, prefiks, domyślna marka, domyślny kod GPC.
|
|
Przycisk "Test połączenia" (opcjonalnie).
|
|
|
|
### Krok 3: Klient MojeGS1
|
|
Plik: `src/Modules/GS1/MojeGS1Client.php`
|
|
|
|
Metody:
|
|
- `listProducts(int $page, int $limit): array` — lista produktów
|
|
- `getProduct(string $gtin): ?array` — pojedynczy produkt
|
|
- `upsertProduct(string $gtin, array $attributes): array` — PUT produkt
|
|
- `findHighestGtin(string $prefix): ?string` — paginuje i szuka max GTIN z prefiksu
|
|
- `generateNextEan(string $prefix): string` — oblicza kolejny EAN z cyfrą kontrolną
|
|
|
|
Statyczna metoda:
|
|
- `calculateEan13CheckDigit(string $partial12): int`
|
|
|
|
### Krok 4: Serwis GS1
|
|
Plik: `src/Modules/GS1/GS1Service.php`
|
|
|
|
Metoda: `assignEanToProduct(int $productId): array`
|
|
1. Pobierz produkt z orderPRO (sprawdź czy nie ma już EAN)
|
|
2. Pobierz ustawienia GS1 z app_settings
|
|
3. Znajdź najwyższy GTIN w GS1 API
|
|
4. Wygeneruj następny EAN
|
|
5. Zarejestruj w GS1 (PUT) z danymi produktu (nazwa, marka, gpcCode)
|
|
6. Zaktualizuj EAN w produkcie orderPRO
|
|
7. Zwróć nowy EAN
|
|
|
|
### Krok 5: Controller endpoint
|
|
Plik: `src/Modules/Products/ProductsController.php`
|
|
Nowa metoda: `assignGs1Ean(Request $request): Response`
|
|
Route: `POST /products/{id}/assign-ean`
|
|
- Walidacja CSRF
|
|
- Wywołanie GS1Service::assignEanToProduct
|
|
- Flash success/error
|
|
- Redirect back do `/products/{id}`
|
|
|
|
### Krok 6: Widok — przycisk na stronie produktu
|
|
Plik: `resources/views/products/show.php`
|
|
Dodać przycisk "Przypisz EAN z GS1" widoczny gdy `$product['ean']` jest pusty.
|
|
Formularz POST do `/products/{id}/assign-ean`.
|
|
|
|
### Krok 7: Tłumaczenia
|
|
Plik: `resources/lang/pl.php`
|
|
Dodać klucze:
|
|
- `products.gs1.assign_ean` — "Przypisz EAN z GS1"
|
|
- `products.gs1.ean_assigned` — "EAN :ean został przypisany i zarejestrowany w GS1."
|
|
- `products.gs1.already_has_ean` — "Produkt ma już przypisany EAN."
|
|
- `products.gs1.error` — "Błąd podczas przypisywania EAN z GS1."
|
|
- `settings.gs1.*` — etykiety formularza ustawień
|
|
|
|
### Krok 8: Routing
|
|
Plik: `routes/web.php`
|
|
Dodać:
|
|
- `POST /products/{id}/assign-ean` → ProductsController::assignGs1Ean
|
|
- `GET /settings/gs1` → SettingsController::gs1
|
|
- `POST /settings/gs1` → SettingsController::gs1Save
|
|
|
|
## Zależności
|
|
- `AppSettingsRepository` — już istnieje (migracja 000012), sprawdzić API
|
|
- `ProductRepository` — metoda update EAN (sprawdzić czy istnieje)
|
|
- Curl extension — wymagany (prawdopodobnie już jest)
|
|
|
|
## Kolejność prac
|
|
1 → 3 → 4 → 5 → 6 → 7 → 8 → 2 (ustawienia na końcu, na początku hardcode credentials do testów)
|
|
Praktycznie: 3 → 4 → 5 → 6 → 7 → 8 (migracja i ustawienia mogą być równolegle)
|