Copy page

Migracja z Ecolet

Migracja z Ecolet — przegląd

Integrujesz się z API Ecolet (panel.ecolet.ro, v1/v2), a Twoje przesyłki przechodzą na platformę Apaczka. Ta sekcja mapuje to, co już masz, na Apaczka API v2 — tak, żebyś przepisał warstwę transportową bez odkrywania każdej różnicy na własną rękę.

Trzy strony:

1. Ten przegląd — które pojęcia się zmieniają i w jakiej kolejności je ugryźć.
2. Mapowanie endpointów — wywołanie po wywołaniu, co czym zastąpić.
3. Braki i obejścia — czego Apaczka nie ma i co zrobić zamiast tego.

Pięć różnic, które generują pracę

#	Obszar	Ecolet	Apaczka API v2
1	Uwierzytelnianie	Bearer JWT z oauth/token	Podpis HMAC-SHA256 przy każdym żądaniu
2	Transport	GET / POST / DELETE, ciało JSON, HTTP 401/422/500	Tylko POST, koperta form-urlencoded, zawsze HTTP 200
3	Tworzenie zamówienia	Asynchroniczne — send-order → order_to_send_id → odpytywanie	Synchroniczne — jedno wywołanie zwraca zamówienie i numer listu przewozowego
4	Pieniądze	RON, łańcuchy dziesiętne ("16,28")	Liczby całkowite w jednostkach podrzędnych (grosze: 1 PLN = 100 gr)
5	Adresy	Ustrukturyzowane pola RO + locality_id	line1 / line2 + tekstowe city + postal_code

Cała reszta — etykiety, przesyłki wielopaczkowe, pobranie, okna odbioru — to mechaniczna transformacja.

1. Uwierzytelnianie — bez tokenów, podpisuj każde żądanie

Nie ma wywołania logowania ani sesji. Każde żądanie niesie app_id, znacznik expires oraz podpis HMAC-SHA256 wyliczony z trasy, ładunku i czasu wygaśnięcia, przy użyciu Twojego app_secret.

Code
Ecolet    POST /oauth/token  →  access_token  →  Authorization: Bearer …
Apaczka   sign(app_secret, "order_send/:{json}:{expires}")  →  każde żądanie

Konsekwencje praktyczne:

• Usuń cache tokenu i logikę odświeżania. Nie ma czego przechowywać ani odnawiać.
• expires to krótkie okno ważności pojedynczego żądania, a nie TTL sesji. Zegar serwera ma znaczenie — rozjazd oznacza masowe odrzucenia.
• app_secret nigdy nie opuszcza Twojego serwera. Podpisywanie w przeglądarce lub aplikacji mobilnej oznacza jego wyciek.

Pełny algorytm z przykładami: Podpisywanie żądań (HMAC). Używasz PHP? SDK podpisuje za Ciebie i cała ta sekcja sprowadza się do dwóch argumentów konstruktora.

2. Transport — jeden czasownik, jeden kod statusu

Każdy endpoint to POST na ścieżkę z ukośnikiem na końcu, a ładunek jedzie jako łańcuch JSON wewnątrz pola formularza:

Code
app_id=<uuid>&request=<json>&expires=<unix>&signature=<hmac>

Odpowiedź to zawsze HTTP 200. Faktyczny wynik jest w ciele:

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

Zatem:

• Przepisz GET /order/{id} na POST order/{id}/, a DELETE /order/{id} na POST cancel_order/{id}/.
• Przestań rozgałęziać kod po statusach HTTP. Rozgałęziaj po status z ciała odpowiedzi. Każdy kod HTTP inny niż 200 to awaria transportu, a nie błąd API.
• Ecolet-owe errors[] na poziomie pól nie mają odpowiednika — błąd przychodzi jako pojedynczy message. Jeśli Twój interfejs podświetla konkretne niepoprawne pola, zobacz Braki i obejścia.

Szczegóły: Semantyka błędów.

3. Tworzenie zamówienia — synchroniczne i nieidempotentne

Przepływ w Ecolet wyglądał tak: send-order → order_to_send_id → odpytywanie order-to-send/{id} aż do ordered albo error → dopiero potem odczyt zamówienia.

order_send w Apaczce robi to wszystko w jednym wywołaniu i zwraca id zamówienia, numer listu przewozowego przewoźnika oraz URL śledzenia. Maszyna stanów order_to_send znika — nie ma bytu pośredniego, nie ma czego odpytywać, nie ma order_to_send/destroy.

Pełny przepływ: Cykl życia zamówienia.

4. Pieniądze — liczby całkowite, jednostki podrzędne

	Ecolet	Apaczka
Typ	łańcuch dziesiętny z przecinkiem ("16,28")	liczba całkowita
Jednostka	RON	jednostki podrzędne — w referencji grosze (1 PLN = 100 gr)
Rozbicie opłat	pozycje fees[]	kwoty netto / brutto

Konwertuj na krawędziach systemu i trzymaj liczby całkowite wewnątrz. 1628 oznacza 16,28 — pomyłka o 100 kończy się na prawdziwej fakturze.

Kwoty pobrania i shipment_value działają tak samo; cod.currency niesie kod waluty jawnie.

5. Adresy — dwie linie zamiast ośmiu pól

Ecolet modeluje adres rumuński jako osobne pola. Apaczka przyjmuje dwie swobodne linie adresu plus miasto, kod pocztowy i kraj:

Ecolet	Apaczka	Jak
street_name, street_number	line1	konkatenacja
block, entrance, floor, flat	line2	konkatenacja z prefiksami
locality_id	city	rozwiń id do nazwy (zobacz braki)
locality	city	bezpośrednio
county	state_code	bezpośrednio
—	name, contact_person, email, phone	wymagane pola kontaktowe

Składając line2, użyj przyjętych rumuńskich prefiksów, żeby człowiek (i kurier) nadal to rozczytał:

Code
line2 = "bl. 12, sc. A, et. 3, ap. 27"
        bloc      scara   etaj    apartament

Pilnuj limitów długości pól z referencji API v2 — długi rumuński adres potrafi je przekroczyć.

Punkty nadania/odbioru (paczkomaty, PUDO) podpina się inaczej: id punktu trafia do foreign_address_id na odpowiednim adresie, a typ odbioru pozostaje SELF. Zobacz Typy odbioru (pickup).

Sugerowana kolejność prac

Każdy krok da się przetestować niezależnie, a wcześniejsze odblokowują późniejsze:

1. Podpisywanie — doprowadź jedno wywołanie service_structure do status: 200. Nic innego nie zadziała, dopóki to nie działa.
2. Słownik usług — zmapuj swoje slugi usług Ecolet na numeryczne service_id faktycznie dostępne na koncie. Nie zaszywaj listy na sztywno; czytaj ją z service_structure i cache'uj (odświeżaj raz dziennie).
3. Renderowanie adresu — zbuduj i pokryj testami transformację Ecolet → line1/line2, razem z rozwijaniem locality_id.
4. Tworzenie zamówienia na sandboxie — order_send, potem waybill. W tym momencie możesz już nadawać.
5. Śledzenie — przejdź z wsadowego wywołania statusów Ecolet na tracking per list przewozowy albo (lepiej) na webhooki push.
6. Reszta — pobranie, usługi dodatkowe, punkty, odbiory, anulowanie.
7. Braki — lokalizacje, książka adresowa, użycie /me. Przeczytaj Braki i obejścia przed krokiem 1, żeby żaden z nich nie zaskoczył Cię na końcu.

---

Dalej: Mapowanie endpointów · Braki i obejścia · Szybki start