# Usage

## Opening the settings

Open the **Afterbuy** extension configuration (plugin settings). Settings can be overridden **per sales channel** — use the correct channel.

## API settings

| Option | Meaning |
|--------|---------|
| **Activate interface** | Master switch for export and shipping status sync |
| **User Token** / **Partner Token** | Credentials for the Afterbuy shop interface |
| **Test credentials** | Validates tokens against Afterbuy |

Credentials: [Afterbuy account → show access data](https://farm01.afterbuy.de/afterbuy/konto.aspx).

## Transfer settings

Typical options:

- **Customer recognition** / **Product recognition** — how Afterbuy matches customer and product
- **Feedback date** — controls Afterbuy feedback / email behaviour
- **Transfer shipping** — if disabled, Afterbuy calculates shipping costs
- **Always transfer shipping address** — also sends the shipping address (`Lieferanschrift` / `KL*`) when it matches the billing address
- **SKU used for discounts** — article number for discount line items (default: `10000`)
- **Product attributes** for Artikelnr / AlternArtikelNr1 / ArtikelStammID
- **Afterbuy marking ID** (optional) — Afterbuy-internal ID of a custom colour marking (`MarkierungID`); the marking must exist in Afterbuy

The Shopware **customer comment** on the order is always sent as Afterbuy field **`Kommentar`**. There is no separate toggle for this.

## Order status

| Option | Meaning |
|--------|---------|
| **Order state for export** | Only orders with this status are transferred. If empty, the default is **`open`**. |
| **Order state after export** | Optional Shopware status after a successful transfer |
| **Shipping status for shipped orders** | Optional delivery status set by the shipping status sync |

## How order export works

There is **no** immediate export on checkout. Flow:

1. Scheduled task `netzkollektiv.afterbuy_processor_task` (every **5 minutes**) or CLI
2. Eligible orders are queued on the message bus
3. The worker sends each order to Afterbuy

### Which orders are exported?

- Interface active, tokens set and valid
- Sales channel matches the storefront channel being processed
- **No** tag `afterbuy-processed`
- Order status matches the setting (otherwise `open`)

After an attempt (success **or** failure) the order gets the tag `afterbuy-processed` and a note in the **internal comment** (Shopware ≥ 6.7) or customer comment (older). Failed exports are **not** retried automatically — remove the tag to export again.

### Manual export (CLI)

```bash
bin/console netzkollektiv-extensions:afterbuy:process <sales-channel-id> [order-number]
```

Then consume the queue, e.g.:

```bash
bin/console messenger:consume async -vv
```

## Shipping status sync

Sync uses the Afterbuy **XML API** (`GetSoldItems`):

1. Scheduled task `netzkollektiv.afterbuy_shipping_status_task` (**hourly**) or CLI
2. Transactions with a shipping date in the last **2 days** (max. 250)
3. Match via Afterbuy `OrderIDAlt` = Shopware **order number**
4. Tracking codes → delivery tracking; optional configured shipping status

### Manual (CLI)

```bash
bin/console netzkollektiv-extensions:afterbuy:check-shipping <sales-channel-id>
```

## Logs and troubleshooting

Log file: `var/log/netzkollektiv_afterbuy*.log`

Typical messages:

| Message | Meaning |
|---------|---------|
| `not active or credentials not set` | Interface off or tokens empty |
| `credentials incorrect` | Token check failed |
| `Processing 0 orders` | No matching order (status / channel / tag) |
| `Adding order … to queue` | Queued — worker must be running |
| `Could not import order` | Afterbuy rejected the order (see order comment) |

## Infrastructure notes

- Without a running **message consumer** / admin worker, tasks and export messages stay queued.
- After a plugin update, **restart** any persistent consumer.
- Export and shipping sync share the same active switch and tokens (per sales channel).