# Mapowanie endpointów Ecolet → Apaczka

Każdy endpoint Ecolet, co go zastępuje i na co uważać. Tabela jest ułożona z
grubsza według tego, jak intensywnie dany endpoint jest używany w praktyce —
idąc od góry najszybciej dojdziesz do działającej integracji nadawczej.

Wszystkie trasy Apaczki to `POST` z **ukośnikiem na końcu** i podpisaną
kopertą opisaną w [Podpisywanie żądań (HMAC)](/pl/legacy/hmac-signing).
Kształty ładunków: [referencja API v2](/pl/reference/v2-legacy).

## Pokryte — istnieje bezpośredni zamiennik

| Ecolet | Apaczka API v2 | Uwagi |
| --- | --- | --- |
| `POST v1/oauth/token` | — (z założenia brak odpowiednika) | Brak tokenów. Zamiast tego podpisuj każde żądanie — zobacz [Uwierzytelnianie](/pl/guides/authentication). |
| `POST v2/add-parcel/reload-form`<br/>`POST v1/add-parcel/reload-form` | `service_structure/` + `order_valuation/` + `pickup_hours/` | Jedno wywołanie Ecolet rozpada się na trzy: słownik usług i opcji, cena dla konkretnego ładunku oraz dostępne okna odbioru. Zobacz [Wybór usługi z oferty](/pl/guides/choosing-a-service). |
| `GET v1/order/get-statuses-for-many-orders` | `tracking/{waybill}/` | **Jeden list przewozowy na wywołanie** — wariant tablicowy zniknął. Iteruj z cache'em albo przejdź na [webhooki push tracking](/pl/guides/tracking) i przestań odpytywać. |
| `GET v1/order/{id}` | `order/{order_id}/` | Pełne szczegóły zamówienia wraz z ceną (w jednostkach podrzędnych). |
| `DELETE v1/order/{id}` | `cancel_order/{order_id}/` | Osobny endpoint, nie czasownik HTTP. Tylko do momentu przejęcia paczki przez przewoźnika; anulowane zamówienie przestaje też wydawać dokumenty, więc najpierw je pobierz. |
| `GET v1/services` | `service_structure/` | Numeryczne `service_id` zamiast slugów — potrzebujesz tabeli mapowania. Zwraca też opcje i usługi dodatkowe. Cache'uj; odświeżaj raz dziennie. |
| `POST v1/map-points/ro` | `points/{type}/` | Kluczowane typem punktu / przewoźnikiem, a nie miejscowością, i bez filtra `destination` (`sender`/`receiver`) — zobacz [braki](/pl/migration/ecolet-gaps). Wybrany punkt trafia do `foreign_address_id` na adresie, z typem odbioru `SELF` ([Typy odbioru](/pl/guides/pickups)). |
| `GET /api/v1/order/{id}/download-waybill` | `waybill/{order_id}/` | Zwraca **base64 w JSON-ie**, nie strumień binarny: przed zapisem PDF-a wywołaj `base64_decode()`. |
| `POST v2/add-parcel/send-order`<br/>`POST v1/add-parcel/send-order` | `order_send/` | **Synchroniczne** — od razu zwraca id zamówienia, numer listu przewozowego i URL śledzenia. Nieidempotentne; zobacz [Cykl życia zamówienia](/pl/guides/order-lifecycle). |
| `GET v1/order` | `orders/` | Lista stronicowana, maks. 25 pozycji na stronę. |

## Częściowo pokryte — zachowanie się różni

| Ecolet | Apaczka API v2 | Co zrobić |
| --- | --- | --- |
| `GET v1/order-to-send/{id}` | — | Koszyk zamówień / krok walidacji nie ma odpowiednika, bo tworzenie jest synchroniczne. Waliduj po swojej stronie, potem wywołaj `order_send/` i obsłuż kopertę błędu. Opcjonalnie wyceń najpierw finalny ładunek przez `order_valuation/`. |
| `DELETE v1/order-to-send/destroy` | — | Nie ma czego usuwać — wersja robocza, której nie wysłano, po stronie Apaczki nie istnieje. Trzymaj wersje robocze lokalnie. |
| `GET v1/me` | `me/` | Istnieje, ale jest **za flagą funkcyjną** — nie na każdym koncie, i nie odtwarza widoku Ecolet z limitem kredytowym i nieopłaconymi fakturami. Ustal to z opiekunem po stronie Alsendo, zanim się na tym oprzesz; zobacz [braki](/pl/migration/ecolet-gaps). |

## Niepokryte — brak odpowiednika

Te wymagają decyzji po Twojej stronie, zanim zaczniesz przepisywać. Każdy
przypadek jest rozpisany na stronie [Braki i
obejścia](/pl/migration/ecolet-gaps).

| Ecolet | Strategia zastąpienia |
| --- | --- |
| `GET v1/locations/ro/localities/{code}` | [Własny słownik miejscowości](/pl/migration/ecolet-gaps#locations-api) |
| `GET v1/locations/{id}/streets/{street}` | [Własne dane ulic](/pl/migration/ecolet-gaps#locations-api) |
| `GET /api/v1/locations/{id}/search-street-postal-codes/{street}` | [Własne dane ulic / kodów pocztowych](/pl/migration/ecolet-gaps#locations-api) |
| `GET /api/v1/locations/ro/counties` | Lista statyczna — `county` mapuje się na `state_code` |
| `GET /api/v1/locations/countries` | Statyczna lista ISO 3166-1 alpha-2 |
| `GET v1/address-book` | [Trzymaj książkę adresową we własnym systemie](/pl/migration/ecolet-gaps) |

## Endpointy, które zyskujesz

Apaczka wystawia kilka rzeczy, których Ecolet nie miał — warto o nich
wiedzieć, zanim zaimplementujesz je samodzielnie:

| Apaczka API v2 | Co robi |
| --- | --- |
| `pickup_hours/` | Dostępne okna odbioru kurierskiego dla usługi i kodu pocztowego. |
| `pickup/{order_id}/` · `batch_pickup/` | Zamówienie kuriera do już istniejących zamówień — zobacz [Typy odbioru](/pl/guides/pickups). |
| `dispatch_code/` · `turn_in/` | Kod nadania oraz potwierdzenie przekazania partii paczek jednemu kurierowi. |
| Webhooki push tracking | Podpisane powiadomienia o statusach na Twój URL zamiast odpytywania — zobacz [Śledzenie przesyłek](/pl/guides/tracking). |

## Usługi dodatkowe

Nazwane usługi Ecolet mapują się na numeryczne id opcji z
`service_structure`. Traktuj poniższe id jako **punkt wyjścia do weryfikacji
na własnym koncie**, a nie jako stałe — dostępne opcje różnią się per
przewoźnik i per usługa.

| Usługa Ecolet | Apaczka | Status |
| --- | --- | --- |
| `saturday_delivery` | opcja `19` | Odpowiednik potwierdzony |
| `sms_notify` | opcja `31` | Odpowiednik potwierdzony |
| `rod` (zwrot dokumentów) | opcja `11` | Odpowiednik istnieje, ale nie ma `rod_code`; opcja jest pomijana, gdy zwrot nie zawiera instrumentów płatniczych |
| `open_package` | jest w słowniku | Zweryfikuj na swojej usłudze, zanim się na tym oprzesz |
| `rop` (zwrot palet), `swap`, `epod` | brak zidentyfikowanego | Odpowiednik niepotwierdzony — zdecyduj per usługa, czy funkcję pominąć, czy blokować zamówienie |

:::caution[Czytaj id, nie zaszywaj ich na sztywno]

Zawsze rozwiązuj id opcji z `service_structure/` dla usługi, której właśnie
używasz, i głośno zgłaszaj błąd, gdy potrzebnej opcji nie ma w słowniku.
Zaszycie powyższych numerów na sztywno skończy się cichym nadawaniem paczek
bez usługi, za którą klient zapłacił.

:::

---

**Zobacz też:** [Przegląd](/pl/migration/ecolet-overview) ·
[Braki i obejścia](/pl/migration/ecolet-gaps) ·
[Referencja API v2](/pl/reference/v2-legacy)