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 poledestination.booked_by— kto wydrukował etykietę:anivalubexternal. Tylko przesyłkianivaobsługują Zaktualizuj i Anuluj; paczkaexternaljest śledzona na tej samej liście, ale dla obu tych operacji zwraca501.
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.
appointmentsihome_kit_orderszawierają 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 znaczniksynced_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łowelocation_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
appointmentsz wpisami{ id, added_at }; - w wizycie jako tablica
shipmentsz wpisami{ id, added_at }.
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.
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.
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ą zwraca409 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
Polaorigin i destination w odpowiedzi przesyłki zawierają pełne obiekty adresowe o następującej strukturze:
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
Polepickup 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). Nigdycancelled— anulowanie pochodzi od nas, nie od przewoźnika.code— własny kod statusu przewoźnika (GO10,GO90,GOY001w GO!;VA,ZF,LA,ZUw DHL).null, gdy przewoźnik go nie podał. Pozostaje niezmienny niezależnie od języka polastatus.detail_code— bardziej szczegółowy kod przewoźnika, jeśli istnieje:statusDetailedw 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 przypadkachnull.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).
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:
pending, dopóki pacjent nie nada próbki — to rzeczywisty stan, a nie luka.