Przejdź do głównej treści
Przesyłka to jedna fizyczna paczka: odbiór kurierski z próbkami krwi z lokalizacji badania do laboratorium, domowy zestaw testowy w drodze do pacjenta albo próbka, którą pacjent odsyła. API przesyłek pozwala ci tworzyć, śledzić, modyfikować i anulować zlecenia przesyłek oraz wyświetla w jednym miejscu każdą paczkę, niezależnie od tego, kto ją zamówił.

Jedna lista z filtrowaniem

GET /api/v1/shipments to jedyna kolekcja. Przesyłka istnieje niezależnie — ma relację wiele do wielu z wizytami i może należeć do zamówienia domowego zestawu testowego — dlatego nie ma listy zagnieżdżonej pod obiektem nadrzędnym. Zawęź tę samą listę parametrami ?appointment_id= lub ?home_kit_order_id=, podziel ją na strony za pomocą limit / offset, a gdy masz konkretne ID, przejdź z wbudowanej tablicy shipments obiektu nadrzędnego ({ id, added_at } zarówno w wizytach, jak i w zamówieniach domowego zestawu testowego) do Pobierz przesyłkę.

Zawartość i kto zamówił przesyłkę

Każda przesyłka zawiera dwie informacje, których nie widać w jej adresach:
  • contents — dowolny tekst opisujący zawartość paczki, ustawiany przy tworzeniu ("Medizinisch freigestellte Probe", "Home test kit") i widoczny dla kuriera. Ma charakter wyłącznie informacyjny. Kierunek nie jest osobnym polem: o tym, czy paczka zmierza do laboratorium, informuje pole destination.
  • booked_by — kto wydrukował etykietę: aniva lub external. Tylko przesyłki aniva obsługują Zaktualizuj i Anuluj; paczka external jest śledzona na tej samej liście, ale dla obu tych operacji zwraca 501.
Paczka, w której wysłano etykietę zwrotną, i paczka wracająca z tą etykietą wskazują na siebie nawzajem przez pole paired_with.

Dostęp

  • Możesz odczytać paczkę, gdy co najmniej jedna powiązana wizyta lub jedno zamówienie domowego zestawu testowego znajduje się w twoim kontekście dostępu, albo gdy paczka została nadana z lokalizacji w twoim kontekście dostępu.
  • appointments i home_kit_orders zawierają wyłącznie wizyty i zamówienia z twojego kontekstu dostępu.
  • Zaktualizuj, Anuluj, Przypisz wizyty i Odłącz wizyty wymagają, aby każde powiązane zamówienie domowego zestawu testowego znajdowało się w twoim kontekście dostępu. W przeciwnym razie wywołanie zwraca 403, a paczkę może zmienić tylko Aniva.

Odczyty nigdy nie odpytują przewoźnika

Każdy odczyt pochodzi z naszej bazy danych. Synchronizacja w tle uzgadnia każdą przesyłkę z jej przewoźnikiem (co 10 minut dla GO!, co godzinę dla DHL) i zapisuje znacznik synced_at, który pokazuje aktualność odpowiedzi. Nie ma wymuszonego odświeżania — DHL pozwala na jedno zapytanie śledzące co pięć sekund, więc nie możemy oferować odczytu łączącego się bezpośrednio z przewoźnikiem.

Tworzenie przesyłki

Tworząc przesyłkę, podajesz źródłowe location_id — lokalizację badania, z której kurier ma odebrać paczkę. W polu destination_lab wskazujesz też docelowe laboratorium. Przesyłka trafia na zarejestrowany adres wysyłkowy tego laboratorium. Lokalizacja musi należeć do kontekstu dostępu twojego klucza API. Użyj Pobierz listę lokalizacji, aby znaleźć dostępne identyfikatory lokalizacji. Opcjonalnie możesz przekazać appointment_id, aby powiązać przesyłkę z konkretną wizytą już przy tworzeniu. Powiązanie pojawia się bezpośrednio po obu stronach:
  • w przesyłce jako tablica appointments z wpisami { id, added_at };
  • w wizycie jako tablica shipments z wpisami { id, added_at }.
Obie tablice są posortowane od najstarszego powiązania. Każde id odsyła do kanonicznego punktu końcowego ze szczegółami (Pobierz wizytę / Pobierz przesyłkę) po pełne dane — partnerzy, którzy chcą śledzić postęp przesyłki dla danej wizyty, przechodzą z każdego wpisu w tablicy shipments wizyty do punktu końcowego ze szczegółami przesyłki. Przesyłkę można powiązać z wieloma wizytami, a wizytę z wieloma przesyłkami. Po utworzeniu zarządzaj powiązaniami za pomocą Przypisz wizyty do przesyłki / Odłącz wizyty od przesyłki. Każda operacja zwraca listę wizyt przesyłki po zmianie. Zasada modyfikacji jest taka: powiązania można tworzyć lub usuwać, gdy ALBO wizyta jest po pobraniu krwi (blood_drawn), albo przesyłka została utworzona mniej niż 24 godziny temu. Poza tym oknem powiązanie jest zablokowane, aby dane historyczne pozostały spójne.

Cykl życia

Przesyłki przechodzą przez następujące statusy:
Każda zmiana statusu wysyła webhook shipment.*, na przykład shipment.delivered. shipment.updated uruchamia się przy każdej zmianie, którą możesz odczytać, na przykład przy nowym skanie.

Zasady harmonogramu odbioru

Poniższe zasady obowiązują podczas tworzenia lub aktualizowania harmonogramu odbioru przesyłki. pickup_date (YYYY-MM-DD) oraz pickup_time_from / pickup_time_till (HH:MM, 24 h) to wartości czasu zegarowego interpretowane w strefie czasowej IANA lokalizacji nadania — nie przesyłasz wraz z nimi strefy czasowej.

Modyfikowanie przesyłek

Możesz zaktualizować harmonogram odbioru, liczbę paczek, wagę i uwagi przesyłki za pomocą PATCH /api/v1/shipments/{id}. Jeśli zmieni się którekolwiek z pól istotnych dla logistyki (data odbioru, godzina, liczba paczek lub waga), dotychczasowe zlecenie logistyczne jest automatycznie anulowane i tworzone jest nowe. Pola pominięte w treści aktualizacji pozostają takie jak w istniejącej przesyłce — na przykład zaktualizowanie samego pola weight ponownie utworzy zlecenie z tym samym harmonogramem odbioru. Zaktualizowane pola harmonogramu są sprawdzane według tych samych zasad harmonogramu odbioru.
Przesyłek nie można modyfikować po odebraniu paczki przez kuriera. Próby aktualizacji przesyłki w statusie in_transit, delivered lub fault zwracają 409 Conflict.
Jeśli dostawca logistyczny odrzuci anulowanie lub ponowne utworzenie zlecenia podczas aktualizacji, API zwraca 502 Bad Gateway z komunikatem błędu dostawcy.

Anulowanie przesyłek

Anuluj przesyłkę za pomocą DELETE /api/v1/shipments/{id}. Wywołuje to API dostawcy logistycznego, aby anulować zlecenie, i zmienia status na cancelled.
Przesyłek nie można anulować po odbiorze. Próby anulowania przesyłki, która ma już status in_transit, delivered lub fault, zwracają 409 Conflict. Anulowanie przesyłki ze statusem cancelled nic nie zmienia i zwraca 200 z przesyłką — zobacz Idempotencja.
Dostawca logistyczny może też odrzucić anulowanie z własnych powodów (np. minął termin anulowania). W takim przypadku API zwraca 502 Bad Gateway z komunikatem i kodem błędu dostawcy.

Etykiety zwrotne

Etykieta zwrotna DHL jest częścią zlecenia wysyłkowego. DHL nie może anulować samej etykiety, więc anulowanie wpisu śledzącego etykietę zwrotną zwraca 409 Conflict. Zamiast tego anuluj przesyłkę wychodzącą, dopóki ma status pending. Anuluje to również etykietę: każdy wpis przesyłki zwrotnej o statusie pending powiązany z paczką wychodzącą zmienia status na cancelled i otrzymuje wpis RETURN_LEG_CANCELLED w status_updates. Paczka zwrotna, którą pacjent już nadał, jedzie dalej. Po wysłaniu paczki wychodzącej etykieta pozostaje ważna, a Aniva zamyka wpis przesyłki zwrotnej ręcznie.

Identyfikatory referencyjne przesyłek

Każda przesyłka ma 11-znakowy identyfikator referencyjny: literę, datę i cztery znaki, {letter}YYMMDDXXXX (na przykład P2611194821). Litera wskazuje, do czego należy przesyłka, a nigdy jej kierunek: Przesyłka z dni 20–22 listopada 2026 r. zachowuje swój identyfikator ze słowem na początku: API, MAN, AUTO lub KIT (na przykład AUTO261121UWKX). Oba formaty pozostają ważne. Nie sprawdzaj długości ani pierwszej litery identyfikatora. Użyj identyfikatora, aby pobrać, zaktualizować lub anulować przesyłkę.

Adresy przesyłki

Pola origin i destination w odpowiedzi przesyłki zawierają pełne obiekty adresowe o następującej strukturze:
W przypadku paczki z gabinetu adres origin jest ustalany na podstawie lokalizacji badania podanej przy tworzeniu, a destination to laboratorium wskazane w destination_lab. W przypadku paczki z zestawem domowym adres dostawy pacjenta jest polem destination zestawu i polem origin zwrotu próbki; miejscem origin zestawu jest punkt, który go pakuje. Adres nie zawiera location_id — powiąż paczkę z gabinetu za pomocą przypisanej do niej wizyty.

Okno odbioru

Pole pickup w odpowiedzi przesyłki zawiera zaplanowane okno odbioru kurierskiego. Obejmuje znaczniki czasu from i till w UTC (ISO 8601 z sufiksem Z, np. 2026-04-15T07:00:00Z) oraz ciąg timezone (strefa czasowa IANA lokalizacji odbioru). Wartości czasu zegarowego pickup_date / pickup_time_* wysłane podczas tworzenia lub aktualizacji są przeliczane na te bezwzględne punkty w czasie z użyciem tej strefy czasowej — użyj timezone, aby ponownie wyświetlić from / till jako czas lokalny w miejscu odbioru. Pole ma wartość null, gdy nie zaplanowano okna odbioru.

Dziennik zmian statusu

Każda przesyłka ma tablicę status_updates — wszystkie zdarzenia cyklu życia zgłoszone przez dostawcę logistycznego, od najstarszego. Każdy wpis zawiera:
  • state — zdarzenie w słowniku statusów przesyłki (pending, in_transit, delivered, fault), dzięki czemu odczytasz oś czasu bez znajomości kodów przewoźnika. null, gdy zdarzenie nie ma przypisanego stanu (utworzenie etykiety, skan przewoźnika o braku informacji, wpisy zapisane przed wprowadzeniem tego pola). Nigdy cancelled — anulowanie pochodzi od nas, nie od przewoźnika.
  • code — własny kod statusu przewoźnika (GO10, GO90, GOY001 w GO!; VA, ZF, LA, ZU w DHL). null, gdy przewoźnik go nie podał. Pozostaje niezmienny niezależnie od języka pola status.
  • detail_code — bardziej szczegółowy kod przewoźnika, jeśli istnieje: statusDetailed w DHL, np. CNRFC_NRQRD_ZF (przekierowano do placówki pocztowej), HLDCC_SERPT_LA (gotowa do odbioru na miejscu), DLVRD_SERPT_ZU (odebrana). W pozostałych przypadkach null.
  • status — czytelna dla człowieka etykieta przewoźnika (np. "Shipment picked up", "Die Sendung wurde abgeholt.").
  • description — wyjaśnienie kodu lub dłuższy komunikat przewoźnika. null, gdy żadne z nich nie istnieje.
  • location — miejsce skanowania według nazwy przewoźnika: magazyn GO!, miasto w DHL. Zwykły tekst, a nie współrzędne.
  • time — znacznik czasu zdarzenia w formacie ISO 8601 zgłoszony przez przewoźnika (wraz z przesunięciem strefowym).
Gdy przewoźnik odsyła paczkę do nadawcy, na osi czasu pojawia się wpis z polem code RETURNED_TO_SENDER. Jego status zawiera powód podany przez przewoźnika. Przesyłka zachowuje status fault, również po dostarczeniu paczki z powrotem do nas. Lista może być pusta, jeśli przewoźnik nie zgłosił jeszcze żadnych zdarzeń. Aby sprawdzić właściwy bieżący stan, użyj głównego pola status. Przechodzi ono w jednym kierunku — od pending przez in_transit do delivered — z nakładanym stanem fault, gdy najnowsze zdarzenie zgłasza problem; przewoźnicy nie sortują zdarzeń według ich wagi (DHL dopisuje powiadomienie o przekierowaniu z kodem pre-transit już po skanie przekazania), więc sam najnowszy wpis nie mówi, na jakim etapie jest paczka.

Przykładowa przesyłka

Przykładowe paczki z zestawem domowym

GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… zwraca w parze zestaw w drodze do pacjenta oraz próbkę w drodze powrotnej:
Wpis przesyłki zwrotnej istnieje od momentu wydrukowania etykiety zwrotnej i pozostaje w statusie pending, dopóki pacjent nie nada próbki — to rzeczywisty stan, a nie luka.