Migracja z Ecolet

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ć:

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.
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.
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.

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:


Code
{ "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.

Ś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. 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:

Zobacz też: Przegląd · Mapowanie endpointów · Dobre praktyki

Last modified on October 5, 2026

Mapowanie endpointów Podpisywanie żądań (HMAC)

Migracja z Ecolet

Braki i obejścia

Locations API

Co zrobić:

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.
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.
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.

Zrób to najpierw

Książka adresowa

Znika: v1/address-book.

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.

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:


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

Ś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. 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

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

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

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:

Zobacz też: Przegląd · Mapowanie endpointów · Dobre praktyki

Last modified on October 5, 2026

Mapowanie endpointów Podpisywanie żądań (HMAC)