O singură listă, filtrată
GET /api/v1/shipments este singura colecție. O expediere este independentă — are o relație mulți-la-mulți cu programările și poate aparține unei comenzi de kit de testare la domiciliu — deci nu există nicio listă imbricată sub un părinte. Restrânge aceeași listă cu ?appointment_id= sau ?home_kit_order_id=, pagineaz-o cu limit / offset și urmărește array-ul shipments inline al părintelui ({ id, added_at } atât pe programări, cât și pe comenzile de kit de testare la domiciliu) către Obține expedierea când ai un id.
Conținutul și cine a făcut rezervarea
Fiecare expediere conține două informații care nu reies din adresele sale:contents— text liber care descrie ce se află în colet, setat la creare ("Medizinisch freigestellte Probe","Home test kit") și afișat curierului. Doar informativ. Direcția nu este un câmp: dacă un colet se îndreaptă spre un laborator se deduce dindestination.booked_by— cine a tipărit eticheta:anivasauexternal. Doar expedierileanivaacceptă Actualizează și Anulează; un coletexternaleste urmărit în aceeași listă, dar returnează501pentru ambele.
paired_with.
Acces
- Poți citi un colet atunci când cel puțin o programare sau o comandă de kit de testare la domiciliu asociată se află în contextul tău de acces sau când a plecat dintr-o locație aflată în contextul tău de acces.
appointmentsșihome_kit_orderslistează doar programările și comenzile din contextul tău de acces.- Actualizează, Anulează, Atașează programări și Detașează programări necesită ca fiecare comandă de kit de testare la domiciliu asociată să fie în contextul tău de acces. În caz contrar, apelul returnează
403și doar Aniva poate modifica coletul.
Citirile nu apelează niciodată curierul
Fiecare citire este servită din baza noastră de date. O sincronizare în fundal reconciliază fiecare expediere cu curierul său (la fiecare 10 minute pentru GO!, din oră în oră pentru DHL) și seteazăsynced_at, care indică cât de vechi este orice răspuns. Nu există reîmprospătare forțată — DHL permite un apel de urmărire la fiecare cinci secunde, așa că o citire care să aștepte răspunsul curierului nu ar putea fi oferită.
Crearea unei expedieri
Când creezi o expediere, specificilocation_id de origine — locația de testare de unde trebuie să ridice curierul. De asemenea, indici laboratorul de destinație cu destination_lab. Expedierea merge la adresa de livrare înregistrată a acelui laborator.
Locația trebuie să fie în contextul de acces al cheii tale API. Folosește Listează locațiile pentru a găsi ID-urile locațiilor disponibile.
Opțional, poți transmite appointment_id pentru a asocia expedierea cu o anumită programare la
momentul creării. Asocierea apare inline pe ambele părți:
- pe expediere, ca un array
appointmentsde intrări{ id, added_at }; - pe programare, ca un array
shipmentsde intrări{ id, added_at }.
id face referire la endpoint-ul canonic de detalii
(Obține programarea /
Obține expedierea) pentru payload-ul complet — partenerii care doresc
evoluția curierului pe programare urmăresc fiecare intrare din array-ul shipments al programării către
endpoint-ul de detalii al expedierii.
O expediere poate fi asociată cu mai multe programări, iar o programare poate fi asociată cu mai multe
expedieri. După creare, gestionează asocierea cu Atașează programări la
expediere /
Detașează programări de la expediere. Fiecare
operație de modificare returnează lista de programări a expedierii după aplicare.
Regula de modificare este: asocierile pot fi create sau eliminate atunci când FIE programarea a trecut de
recoltarea de sânge (blood_drawn), fie expedierea a fost creată cu mai puțin de 24 de ore în urmă. În afara acelui
interval, asocierea este blocată, astfel încât înregistrările istorice să rămână stabile.
Ciclul de viață
Expedierile trec prin următoarele statusuri:
Fiecare modificare de status trimite un webhook
shipment.*, de exemplu
shipment.delivered. shipment.updated se declanșează la fiecare modificare pe care o poți citi, cum ar fi o scanare nouă.
Reguli pentru programul de ridicare
Următoarele reguli se aplică atunci când creezi sau actualizezi programul de ridicare al unei expedieri.pickup_date
(YYYY-MM-DD) și pickup_time_from / pickup_time_till (HH:MM, 24h) sunt valori de oră locală
interpretate în fusul orar IANA al locației de origine — nu trimiți un fus orar împreună cu acestea.
Modificarea expedierilor
Poți actualiza programul de ridicare, numărul de colete, greutatea și notele unei expedieri folosindPATCH /api/v1/shipments/{id}. Dacă se modifică vreun câmp relevant pentru logistică (data ridicării, ora, numărul de colete sau greutatea), comanda logistică existentă este anulată automat și se creează una nouă. Câmpurile pe care le omiți din corpul actualizării sunt păstrate din expedierea existentă — de exemplu, dacă actualizezi doar weight, comanda va fi recreată cu același program de ridicare. Câmpurile de program actualizate sunt validate conform acelorași reguli pentru programul de ridicare.
Dacă furnizorul de logistică respinge anularea sau recrearea în timpul unei actualizări, API-ul returnează 502 Bad Gateway împreună cu mesajul de eroare al furnizorului.
Anularea expedierilor
Anulează o expediere folosindDELETE /api/v1/shipments/{id}. Această cerere apelează API-ul furnizorului de logistică pentru a anula comanda și actualizează statusul la cancelled.
Furnizorul de logistică poate, de asemenea, să respingă anularea din motive proprii (de ex., termenul-limită de anulare a trecut). În acest caz, API-ul returnează 502 Bad Gateway cu mesajul de eroare și codul de eroare ale furnizorului.
Etichete de retur
O etichetă de retur DHL face parte din comanda sa inițială. DHL nu poate anula eticheta separat, așa că anularea rândului care urmărește o etichetă de retur returnează409 Conflict. Anulează în schimb coletul inițial, cât timp este pending. Astfel se anulează și eticheta: fiecare rând de retur aflat în pending al coletului inițial devine cancelled și primește o intrare RETURN_LEG_CANCELLED în status_updates. Un colet de retur pe care pacientul l-a trimis deja își continuă traseul. După ce coletul inițial pleacă, eticheta rămâne valabilă, iar Aniva închide manual rândul de retur.
ID-uri de referință ale expedierilor
Fiecare expediere are un ID de referință de 11 caractere: o literă, data și patru caractere,{letter}YYMMDDXXXX (de exemplu, P2611194821). Litera arată cui aparține expedierea, niciodată direcția ei:
O expediere din 20–22 noiembrie 2026 își păstrează ID-ul cu un cuvânt în față:
API, MAN, AUTO sau KIT (de exemplu, AUTO261121UWKX). Ambele forme rămân valide. Nu verifica lungimea sau prima literă a unui ID. Folosește ID-ul pentru a prelua, actualiza sau anula expedierea.
Adresele expedierii
Câmpurileorigin și destination din răspunsul expedierii conțin obiecte de adresă rezolvate cu următoarea structură:
origin este rezolvată din locația de testare pe care ai specificat-o la
creare, iar destination este laboratorul pe care l-ai indicat în destination_lab.
Pentru un colet cu kit pentru acasă, adresa de livrare a pacientului este destination pentru kit și
origin pentru returul probei; locația care ambalează kitul este origin al acestuia.
Adresa nu conține location_id — corelează un colet de la cabinet prin programarea de care este
legat.
Interval de ridicare
Câmpulpickup din răspunsul expedierii conține intervalul programat de ridicare de către curier. Acesta
include marcajele temporale from și till ca momente UTC (ISO 8601 cu sufix Z, de ex.
2026-04-15T07:00:00Z) și un șir timezone (fusul orar IANA al locației de ridicare). Valorile
de oră locală pickup_date / pickup_time_* pe care le-ai trimis la creare / actualizare sunt convertite în aceste
momente absolute folosind acel fus orar — folosește timezone pentru a afișa from / till înapoi în
ora locală a locației de ridicare. Câmpul este null atunci când nu a fost programat niciun interval de ridicare.
Jurnalul actualizărilor de status
Fiecare expediere conține un arraystatus_updates — fiecare eveniment din ciclul de viață raportat
de furnizorul de logistică, de la cel mai vechi la cel mai nou. Fiecare intrare conține:
state— evenimentul exprimat în vocabularul de statusuri ale expedierii (pending,in_transit,delivered,fault), ca să poți citi cronologia fără să cunoști codurile curierului.nullcând evenimentul nu poartă o stare (crearea etichetei, o scanare fără informații a curierului, intrări înregistrate înainte ca acest câmp să existe). Niciodatăcancelled— o anulare este a noastră, nu un eveniment al curierului.code— codul propriu de status al curierului (GO10,GO90,GOY001la GO!;VA,ZF,LA,ZUla DHL).nullcând curierul nu a furnizat niciunul. Stabil indiferent de limba în care este tradusstatus.detail_code— codul mai detaliat al curierului, acolo unde există:statusDetailedde la DHL, de ex.CNRFC_NRQRD_ZF(redirecționat către un oficiu poștal),HLDCC_SERPT_LA(gata de ridicare acolo),DLVRD_SERPT_ZU(ridicat).nullîn rest.status— eticheta lizibilă a curierului (de ex."Shipment picked up","Die Sendung wurde abgeholt.").description— o explicație a codului sau propoziția mai lungă a curierului.nullcând nu există niciuna.location— locul unde a avut loc scanarea, așa cum îl numește curierul: un depozit GO!, un oraș DHL. Text liber, nu o coordonată.time— marcajul temporal ISO 8601 al evenimentului, așa cum a fost raportat de curier (cu decalajul său).
code
RETURNED_TO_SENDER. Câmpul său status conține motivul curierului. Expedierea rămâne apoi fault, chiar și
după ce curierul ne livrează coletul înapoi.
Lista poate fi goală dacă curierul nu a raportat încă niciun eveniment.
Folosește câmpul status de nivel superior pentru starea curentă canonică. Acesta avansează într-o singură direcție — de la pending
la in_transit și apoi la delivered — cu fault suprapus cât timp cel mai recent eveniment raportează o problemă;
curierii nu își ordonează evenimentele după importanță (DHL adaugă o notificare de redirecționare cu cod pre-transit
după scanarea de predare), așa că cea mai recentă intrare singură nu arată în ce stadiu se află un colet.
Exemplu de expediere
Exemplu de colete cu kit pentru acasă
GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… returnează kitul aflat pe drum spre pacient și proba aflată pe drum înapoi, în pereche:
pending până când pacientul trimite proba — aceasta este starea reală, nu o lipsă.