# Auto-publikacja Allegro i OLX z BaseLinkera

Instrukcja operatorska: jak po zapisie produktu z tej apki (**`addInventoryProduct`**) wystawiać oferty na **Allegro** i **OLX** z panelu Base.com / BaseLinker — **bez** bezpośredniej integracji z API marketplace w repozytorium.

> **Zakres:** Allegro (konto `24646`) + OLX. Erli celowo pominięte.
>
> **Powiązane:** [`ARCHITECTURE.md`](ARCHITECTURE.md), [`BASE_TEMPLATES.md`](BASE_TEMPLATES.md), [`rozmowa_z_ai_base.com.md`](rozmowa_z_ai_base.com.md), [`base-com-input-pack.md`](base-com-input-pack.md).

---

## 1. Model przepływu

```mermaid
flowchart TD
  A[Apka: import + AI] --> B[addInventoryProduct]
  B --> C[(Magazyn BL 62360)]
  C --> D[Szablony ofert BL]
  D --> E[Allegro]
  D --> F[OLX]
  G[Reguły / automatyzacje BL] -.-> E
  G -.-> F
```

1. **Apka** zapisuje kartę magazynową: nazwa, opis Base, opisy kanałowe, `features`, zdjęcia, stan, cena.
2. **Szablony ofert** w BL wstawiają treści tagami (`[opis]`, `[opis_dodatkowy1]`, `[opis_dodatkowy2]`).
3. **Publikacja** następuje w panelu BL (ręcznie lub regułą automatyczną po dodaniu produktu).

---

## 2. Co apka wysyła (kontrakt pól)

| Pole BL | Kanał | Tag w szablonie oferty |
|---------|-------|------------------------|
| `text_fields.description` | Base / sklep | `[opis]` |
| `text_fields.description_extra1` | Allegro | `[opis_dodatkowy1]` |
| `text_fields.description_extra2` | OLX (plain text) | `[opis_dodatkowy2]` |
| `text_fields.description_extra3` | WooCommerce (opcjonalnie) | `[opis_dodatkowy3]` jeśli używasz |
| `text_fields.features.Stan` | Allegro (mapowanie) | parametr kategorii przez regułę BL |

Domyślnie apka ma włączone **`generateMarketplaceChannels: true`** — przy zapisie trafiają opisy Allegro i OLX (gdy AI je wygenerowało).

### Outlet / brak EAN na Allegro

Gdy `outletMode=true`, apka ustawia:

```json
"features": { "Stan": "używany" }
```

W panelu BL (jednorazowa konfiguracja):

**Allegro → Kategorie i parametry → Parametry Allegro**

| Parametr Allegro | Akcja |
|------------------|--------|
| Stan | Skopiuj z parametru magazynu → **Stan** |

Potwierdzone wartości: `nowy`, `używany`, `po zwrocie`, `outlet`. Dla **zwolnienia z EAN** najpewniej mapuj na **`używany`** (patrz [`rozmowa_z_ai_base.com.md`](rozmowa_z_ai_base.com.md)).

---

## 3. Konfiguracja jednorazowa w panelu BL

### 3.1 Szablon oferty Allegro (`SZABLON Prawidłowy`)

Minimalny układ treści:

```text
[opis_dodatkowy1]
```

Jeśli chcesz wspólny blok + wariant Allegro:

```text
[opis]
[opis_dodatkowy1]
```

### 3.2 Szablon oferty OLX

```text
[opis_dodatkowy2]
```

OLX w apce jest **plain text** (bez HTML).

### 3.3 Domyślne ustawienia kanału Allegro (na koncie)

Zweryfikuj w BL (wartości z rozmowy z AI Base.com — dostosuj do aktualnego konta):

| Ustawienie | Przykład |
|------------|----------|
| Konto Allegro | Dywanowy-Bazar (`24646`) |
| Szablon | SZABLON Prawidłowy |
| Kategoria domyślna | Dom i Ogród → … → Dywany |
| Cennik wysyłki | - Dywany Standard |
| Wysyłka w ciągu | 3 dni |
| GPSR | tekst + producent + osoba odpowiedzialna |
| Faktura | bez VAT (jeśli dotyczy) |

### 3.4 Mapowanie parametrów magazyn → Allegro

Poza **Stan** zmapuj parametry z `text_fields.features` (Materiał, Kolor, Wymiary itd.) na parametry obowiązkowe kategorii Allegro — lista zależy od kategorii liściowej.

Kanonika nazw w apce: [`config/baselinker-feature-canonical.json`](../config/baselinker-feature-canonical.json).

---

## 4. Publikacja pojedynczego produktu (operator)

Po **„Wyślij do Base.com”** w Studio / kreatorze / dashboardzie:

1. **Sprawdź ostrzeżenia** w apce (waga 0, tytuł Allegro, brak zdjęć).
2. Otwórz **kartę produktu w BL** (Studio: ustawienia → *Otwórz kartę* lub *Otwórz publikacje*).
3. W BL uzupełnij ręcznie, jeśli trzeba:
   - **cenę > 0** (apka często wysyła `0` — ustawiasz w BL),
   - **wagę** (źródło Tara często daje 0 kg),
   - kategorię **marketplace** Allegro (≠ kategoria magazynu `category_id`).
4. Zakładka **Publikacje (Channels Data)** — podgląd treści per kanał; ewentualne nadpisanie.
5. **Wystaw na Allegro** / **Wystaw na OLX** (przycisk w BL lub reguła automatyczna).

### Checklist przed wystawieniem

| # | Warunek | Gdzie sprawdzić |
|---|---------|-----------------|
| 1 | Cena > 0 PLN | karta produktu BL |
| 2 | Stan magazynu > 0 | karta produktu BL |
| 3 | Min. 1 zdjęcie | apka + BL |
| 4 | Waga > 0 (Allegro wysyłka) | karta produktu BL |
| 5 | Opis Allegro (`description_extra1`) | podgląd payloadu / BL |
| 6 | Opis OLX (`description_extra2`) | j.w. |
| 7 | `features.Stan` przy outlet | payload / parametry BL |
| 8 | Kategoria Allegro + parametry kategorii | zakładka Publikacje |
| 9 | GPSR / dostawa / zwroty | ustawienia konta Allegro w BL |

Apka dodaje te punkty jako **ostrzeżenia** (`meta.validationIssues`, kod `PUBLISH_*`) — nie blokują zapisu do magazynu.

---

## 5. Auto-publikacja (reguły po stronie BL)

Repozytorium **nie** wywołuje API wystawiania ofert. Automatyzacja = konfiguracja w BaseLinkerze, np.:

- reguła: *po dodaniu produktu do magazynu 62360 → utwórz szkic oferty Allegro*,
- reguła: *gdy spełnione warunki (cena, stan, zdjęcie) → opublikuj*,
- harmonogram synchronizacji stanów.

**Kroki do zrobienia w panelu BL (do uzupełnienia po Twojej weryfikacji UI):**

1. **Integracje** → Allegro / OLX — połączenia aktywne.
2. **Magazyn** → **Automatyzacje** (lub odpowiednik w Twojej wersji panelu) → nowa reguła:
   - trigger: dodanie / aktualizacja produktu w inventory `62360`,
   - warunek: tag `OUTLET` lub kategoria, stan > 0, min. 1 zdjęcie,
   - akcja: utwórz ofertę Allegro z szablonem `SZABLON Prawidłowy`.
3. Powtórz analogicznie dla OLX (osobny szablon, plain text).
4. Test na **jednym** produkcie z apki → sprawdź log błędów walidacji w BL.

> Dokładne nazwy menu w BL mogą się różnić między wersjami konta. Jeśli reguł nie ma w UI, publikacja pozostaje ręczna z karty produktu — nadal korzystasz z przygotowanych pól `description_extra*`.

---

## 6. Zmienne środowiskowe (opcjonalne)

| Klucz | Domyślnie | Opis |
|-------|-----------|------|
| `BASELINKER_PANEL_PRODUCT_URL` | `…inventory_products.php?inventory_id={inventoryId}&product_id={productId}` | Karta produktu po zapisie |
| `BASELINKER_PANEL_PUBLISH_URL` | jak wyżej + `&tab=channels` | Link „Publikacje” (dostosuj do swojego panelu) |

Placeholdery: `{inventoryId}`, `{productId}`.

---

## 7. Rozwiązywanie problemów

| Objaw | Przyczyna | Działanie |
|-------|-----------|-----------|
| Pusty opis na Allegro | `generateMarketplaceChannels` wyłączone lub brak AI | Włącz w configu; uruchom regenerację kanałów w kreatorze |
| OLX bez treści | Brak `description_extra2` w payloadzie | Regeneruj kanał OLX; sprawdź profil `OLX_Clearance_Fast` |
| Allegro wymaga EAN | Brak mapowania `Stan` | Ustaw `outletMode` + regułę parametru Stan → `używany` |
| Błąd wysyłki — waga 0 | Tara nie podaje wagi | Uzupełnij ręcznie w BL przed wystawieniem |
| Zła kategoria Allegro | `category_id` to kategoria magazynu | Ustaw kategorię marketplace w Publikacjach |

---

## 8. Powiązanie z kodem

| Plik | Rola |
|------|------|
| [`src/baselinker.js`](../src/baselinker.js) | Zapis `description_extra1/2` przy `generateMarketplaceChannels` |
| [`config/editor-config.json`](../config/editor-config.json) | Kanały, prompty AI, profile sprzedaży |
| [`src/marketplacePublish.js`](../src/marketplacePublish.js) | Ostrzeżenia `PUBLISH_*`, budowa URL panelu |
| [`public/studioProfile.js`](../public/studioProfile.js) | `afterSave`: `open_base` \| `open_publish` |

---

*Ostatnia aktualizacja: czerwiec 2026 — inventory 62360, Allegro 24646.*