# Typy odbioru (pickup)

Są dwa zasadniczo różne sposoby, w jakie przesyłka trafia do przewoźnika, i
łatwo je w API pomylić: **typ odbioru wybierany przy tworzeniu zamówienia**
(`order.pickup.type`) oraz **osobne endpointy pickup** dla już istniejących
zamówień. Ta strona wyjaśnia oba.

Przykłady payloadów są zgodne z [referencją API v2](/pl/reference/v2-legacy).

## Typ odbioru przy tworzeniu zamówienia

Obiekt `pickup` w [payloadzie zamówienia](/pl/reference/v2-legacy) decyduje,
jak przesyłka zostanie przekazana:

| Typ | Znaczenie |
|---|---|
| `SELF` | **Sam dostarczasz przesyłkę** do punktu nadania / oddziału przewoźnika. Kurier nie przyjeżdża. Wartość domyślna. |
| `COURIER` | **Kurier odbiera przesyłkę** pod adresem nadawcy w wybranym oknie czasowym. |

To jedyne dwa typy odbioru w publicznym kontrakcie. **Nadanie w punkcie**
(automat, PUDO, placówka pocztowa) to nadal `SELF` — sam punkt wskazuje
`foreign_address_id` w **adresie nadawcy** (identyfikator pochodzi z katalogu
[`points/{type}/`](/pl/reference/v2-legacy)).

:::note[`POCZTA` i `POINT` nie są typami odbioru]

W starszych integracjach albo w panelu Apaczka możesz natknąć się na
`POCZTA` lub `POINT`. Żadna z tych wartości nie należy do publicznego
kontraktu API: `POCZTA` to pozostałość po wycofanym SOAP API v1, a `POINT`
steruje jedynie przyciskami formularza zamówienia w panelu. Zawsze wysyłaj
`SELF`, a identyfikator punktu umieszczaj w `foreign_address_id`.

:::

### `SELF` — nadanie własne

```json
"pickup": { "type": "SELF" }
```

Po utworzeniu zamówienia pobierz [etykietę](/pl/reference/v2-legacy) i — dla
przewoźników, którzy tego wymagają, [kod nadania](/pl/reference/v2-legacy)
do okazania w punkcie.

### `COURIER` — zamówiony odbiór

```json
"pickup": {
  "type": "COURIER",
  "date": "2026-07-21",
  "hours_from": "09:00",
  "hours_to": "15:00"
}
```

:::caution[Pułapka nazewnicza]

Przy tworzeniu zamówienia pola są w liczbie mnogiej — `hours_from` /
`hours_to`. Osobne endpointy [`pickup`](/pl/reference/v2-legacy) i
[`batch_pickup`](/pl/reference/v2-legacy) używają liczby pojedynczej
`hour_from` / `hour_to`. Tak, naprawdę.

:::

Dostępne okna czasowe sprawdź najpierw przez
[`pickup_hours`](/pl/reference/v2-legacy) — kalendarz odbiorów zależy od
kodu pocztowego i usługi:

```json
{ "postal_code": "05-500", "service_id": 65 }
```

## Zamawianie odbioru dla istniejących zamówień

Jeśli zamówienia powstały z `SELF` (albo kurier nie dojechał), odbiór można
zamówić później — bez tworzenia nowego zamówienia:

### `pickup/{order_id}/` — pojedyncze zamówienie

Ponawia odbiór kurierski dla jednego zamówienia. Obecne ograniczenia:

- dostępne wyłącznie dla zamówień **DPD**,
- konto musi mieć uprawnienie **pickup przez API** (włącza wsparcie
  Apaczki).

```json
{ "date": "2026-07-21", "hour_from": "09:00", "hour_to": "15:00" }
```

### `batch_pickup/` — jeden kurier, wiele zamówień

Zamawia jeden odbiór dla wielu zamówień naraz:

```json
{
  "order_ids": [467840212, 467840211],
  "date": "2026-07-21",
  "hour_from": "09:00",
  "hour_to": "15:00"
}
```

Ograniczenia weryfikowane przez API:

- wszystkie zamówienia muszą mieć **ten sam adres nadawcy**,
- wszystkie zamówienia muszą używać **tej samej usługi**, a usługa musi
  wspierać odbiór zbiorczy,
- konto musi mieć uprawnienie **pickup przez API**.

### Z użyciem SDK

[SDK PHP](/pl/sdk) opakowuje wszystkie trzy endpointy:

```php
$hours = $client->getPickupHours('05-500', $service)->getHours();
$firstDay = reset($hours);

$client->schedulePickup($orderId, $firstDay->getDate(), '09:00', '15:00');
// albo dla wielu zamówień naraz:
$client->scheduleBatchPickup($orderIds, $firstDay->getDate(), '09:00', '15:00');
```

## Co wybrać?

- Wysyłka ad-hoc, jedna paczka, kurier ma przyjechać → `pickup.type =
  COURIER` bezpośrednio w `order_send`.
- Drukujesz etykiety przez cały dzień, kurier przyjeżdża raz po południu →
  twórz zamówienia z `SELF`, potem jeden
  [`batch_pickup`](/pl/reference/v2-legacy) dla wszystkich.
- Zostawiasz paczki w automacie/oddziale po drodze → `SELF`, a dla usług
  punktowych punkt w `foreign_address_id` nadawcy — odbiór w ogóle nie jest
  potrzebny.