# Braki i obejścia

Część tego, co dawało API Ecolet, nie ma odpowiednika w Apaczka API v2. Nic
z tego nie jest blokerem, ale każda pozycja to decyzja, którą warto podjąć
**przed** rozpoczęciem przepisywania, a nie po — w większości przypadków
dane albo stan przenoszą się do Twojego systemu.

## Locations API

**Znika:** wyszukiwanie miejscowości, ulic, kodów pocztowych i okręgów
(`locations/ro/localities/{code}`, `locations/{id}/streets/{street}`,
`search-street-postal-codes`, `counties`, `countries`).

**Dlaczego to ważne:** adresy Ecolet są zbudowane wokół `locality_id` — id ze
słownika Ecolet. Apaczka przyjmuje tekstowe `city` i `postal_code`; nie ma
słownika do odpytania ani id do rozwiązania.

**Co zrobić:**

1. **Wyeksportuj słownik miejscowości, póki masz dostęp do Ecolet.**
   Potrzebujesz co najmniej `locality_id → nazwa, okręg, kody pocztowe`. Bez
   tego nie wyrenderujesz historycznych adresów.
2. **Przejmij go na własność.** Rumuńskie dane pocztowe są dostępne w
   źródłach publicznych; odświeżaj je cyklicznie. To największy pojedynczy
   kawałek pracy wynikający z migracji — zaplanuj go jawnie.
3. **Waliduj dalej po swojej stronie.** Apaczka przyjmie adres, pod który
   nie da się doręczyć; zła para `city`/`postal_code` wyjdzie jako błąd
   przewoźnika, a nie jako błąd API.

:::caution[Zrób to najpierw]

Podpowiadanie adresów to zwykle najczęściej wywoływana część integracji
nadawczej. Jeśli Twój checkout opiera się na wyszukiwaniu ulic, ta funkcja
musi działać po Twojej stronie, zanim przełączysz ruch — to nie jest rzecz do
odkrycia w ostatnim sprincie.

:::

## Książka adresowa

**Znika:** `v1/address-book`.

**Co zrobić:** trzymaj adresy we własnej bazie. Jeśli używałeś Ecolet jako
źródła prawdy dla adresów nadawców/odbiorców, wyeksportuj je przed
przełączeniem. Apaczka przyjmuje pełny adres przy każdym zamówieniu, więc
funkcjonalnie nic nie tracisz — przenosi się tylko miejsce przechowywania.

## Koszyk zamówień / walidacja asynchroniczna

**Znika:** `order-to-send/{id}` i `order-to-send/destroy`, a wraz z nimi
maszyna stanów `new` / `ordered` / `error`.

**Dlaczego to ważne:** w Ecolet `send-order` zwracał `order_to_send_id`, a Ty
odpytywałeś, aż zamówienie się zmaterializuje. Ten byt pośredni był też
miejscem, w którym dowiadywałeś się o problemach walidacyjnych.

**Co zrobić:**

- Usuń pętlę odpytywania i stan pośredni w całości — `order_send/` zwraca
  gotowe zamówienie albo kopertę błędu.
- Jeśli pokazujesz użytkownikom koszyk „gotowe do wysłania", trzymaj go
  **lokalnie**. Apaczka nie zna pojęcia wersji roboczej zamówienia.
- Żeby sprawdzić ładunek przed zatwierdzeniem, wywołaj `order_valuation/` na
  finalnym obiekcie zamówienia. Wywróci się na tych samych problemach
  strukturalnych, a przy okazji poda cenę.

## Błędy walidacji na poziomie pól

**Znika:** Ecolet-owe `422` z `errors: { "postal_code": ["…"] }`.

Apaczka zwraca pojedynczy komunikat:

```json
{ "status": 400, "message": "Validation error", "response": null }
```

**Co zrobić:** waliduj po swojej stronie, tam gdzie użytkownik to widzi —
pola wymagane, format kodu pocztowego, format telefonu, długości pól,
dostępność opcji. Traktuj `message` z API jako diagnostykę ostatniej szansy,
do zalogowania i pokazania wsparciu, a nie jako coś do zmapowania z powrotem
na pola formularza. Zobacz [Semantyka błędów](/pl/legacy/error-semantics).

## Śledzenie wsadowe

**Znika:** `order/get-statuses-for-many-orders` — jedno wywołanie, wiele
zamówień.

`tracking/{waybill}/` obsługuje **jeden list przewozowy na wywołanie**.

**Co zrobić:**

- **Preferowane:** przejdź na [webhooki push
  tracking](/pl/guides/tracking). Zmiany statusów przychodzą jako podpisane
  powiadomienia i problem odpytywania znika.
- Jeśli musisz odpytywać: odpytuj tylko przesyłki faktycznie w drodze,
  wydłużaj odstępy wraz z wiekiem przesyłki i cache'uj. Naiwne jedno żądanie
  na otwarte zamówienie na minutę się nie wyskaluje.

## Wyszukiwanie punktów

`points/{type}/` zwraca punkty według typu / przewoźnika, a nie według
miejscowości, i nie ma filtra `destination` (`sender` / `receiver`). Rumuńskie
paczkomaty często różnią się tym, czy przyjmują nadania, doręczenia, czy
jedno i drugie.

**Co zrobić:** czytaj `option_send`, `option_deliver` i `option_cod` na
każdym punkcie i filtruj samodzielnie, zanim pokażesz punkt użytkownikowi.
Cache'uj katalog (zmienia się wolno) i wybieraj po swojej stronie według
współrzędnych albo kodu pocztowego.

Id punktów są Apaczki, nie Ecolet — jeśli masz zapisane id punktów Ecolet na
starych zamówieniach, zostaw je, ale dla nowych pobieraj świeże.

## Konto bankowe dla pobrania

**Różnica:** Ecolet zawsze wypłacał pobranie na konto skonfigurowane na
użytkowniku. Apaczka oczekuje konta wypłaty na zamówieniu — albo
`cod.bankaccount`, albo `cod.bankaccount_id` wskazującego konto zapisane w
panelu.

**Co zrobić:** zapisz konto wypłaty w panelu Apaczki raz i wysyłaj
`cod.bankaccount_id`. To odtwarza zachowanie Ecolet bez umieszczania numerów
kont w każdym żądaniu.

## Informacje o koncie i kredycie

`me/` istnieje, ale jest **za flagą funkcyjną** i nie odtwarza `v1/me` z
Ecolet — limit kredytowy, wykorzystanie kredytu, nieopłacone faktury,
zablokowani przewoźnicy i usługi nie są jego częścią.

**Co zrobić:** jeśli Twoja integracja blokuje tworzenie zamówień na
podstawie kondycji kredytowej klienta, podnieś ten temat z opiekunem po
stronie Alsendo przed przełączeniem. Nie buduj na `me/`, dopóki nie
potwierdzisz, że jest włączone na Twoim koncie i zwraca to, czego
potrzebujesz.

## Mniejsze różnice

| Obszar | Różnica | Co zrobić |
| --- | --- | --- |
| Etykiety | Base64 wewnątrz JSON-a, nie strumień binarny | `base64_decode()` przed zapisem pliku |
| Format etykiety | `is_zebra` jest polem żądania; w Ecolet brało się z ustawień użytkownika | Przekazuj format jawnie przy każdym żądaniu |
| Wielopaczkowość | `parcel.amount` / obiekt `parcels` | Jeden wpis `shipment[]` na fizyczną paczkę |
| Godziny odbioru | Ecolet przyjmuje jedną godzinę, Apaczka przedział | Wysyłaj `hours_from` / `hours_to`; poprawne okna czytaj z `pickup_hours/` |
| Kody rabatowe | Brak odpowiednika | Rabaty to ustalenie handlowe na koncie, nie pole API |
| `uit_code` | Brak odpowiednika | Trzymaj jako własne metadane (towary wysokiego ryzyka podatkowego wg ANAF) |
| `sender_forklift` / `receiver_forklift` | Brak odpowiednika | Dotyczy palet; sposób obsługi per usługa ustal z opiekunem po stronie Alsendo |
| Limity zapytań | Inny model i inne limity | Cache'uj `service_structure/` i `points/` (odświeżanie dzienne) oraz `pickup_hours/` (minuty). Przy wielu workerach praktyczną odpowiedzią jest wspólny cache — Redis lub odpowiednik. |

## Checklista migracji

Przed przełączeniem upewnij się, że masz:

- [ ] Wyeksportowany słownik miejscowości Ecolet i dane książki adresowej
- [ ] Działające po Twojej stronie wyszukiwanie ulic / kodów pocztowych
- [ ] Tabelę mapowania slugów usług Ecolet na `service_id` Apaczki, zbudowaną
      z `service_structure/` i odświeżaną, a nie zaszytą na sztywno
- [ ] Mapowanie usług dodatkowych z jawną decyzją dla tych bez odpowiednika
- [ ] Ustrukturyzowane adresy przechowywane po Twojej stronie — sklejenie
      `line1`/`line2` jest jednokierunkowe
- [ ] Pieniądze obsługiwane jako całkowite jednostki podrzędne od końca do końca
- [ ] Usuniętą pętlę odpytywania `order_to_send` i przejrzane zachowanie przy
      ponawianiu (`order_send/` nie jest idempotentne)
- [ ] Śledzenie przeniesione na webhooki albo odpytywanie ograniczone do
      przesyłek w drodze
- [ ] Skonfigurowane w panelu Apaczki konto wypłaty pobrania
- [ ] Walidację przeniesioną na swoją stronę, z logowaniem `message` z API
- [ ] Cały przepływ przećwiczony na [sandboksie](/pl/guides/testing)

---

**Zobacz też:** [Przegląd](/pl/migration/ecolet-overview) ·
[Mapowanie endpointów](/pl/migration/ecolet-endpoint-map) ·
[Dobre praktyki](/pl/guides/best-practices)