Salt la conținutul principal
O expediere este un singur colet fizic: o ridicare prin curier care transportă probe de sânge de la o locație de testare la un laborator, kitul aflat pe drum spre un pacient cu kit de testare la domiciliu sau proba pe care acel pacient o trimite înapoi prin poștă. API-ul de expedieri îți permite să creezi, să urmărești, să modifici și să anulezi comenzi de expediere și listează fiecare colet într-un singur loc, indiferent cine l-a rezervat.

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 din destination.
  • booked_by — cine a tipărit eticheta: aniva sau external. Doar expedierile aniva acceptă Actualizează și Anulează; un colet external este urmărit în aceeași listă, dar returnează 501 pentru ambele.
Un colet care a inclus o etichetă de retur și coletul pe care acea etichetă îl aduce înapoi indică unul spre celălalt prin 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 și home_kit_orders listează 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, specifici location_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 appointments de intrări { id, added_at };
  • pe programare, ca un array shipments de intrări { id, added_at }.
Ambele array-uri sunt ordonate începând cu cea mai veche asociere. Fiecare 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 folosind PATCH /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.
Expedierile nu pot fi modificate după ce curierul a ridicat coletul. Încercările de a actualiza o expediere cu statusul in_transit, delivered sau fault returnează 409 Conflict.
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 folosind DELETE /api/v1/shipments/{id}. Această cerere apelează API-ul furnizorului de logistică pentru a anula comanda și actualizează statusul la cancelled.
Expedierile nu pot fi anulate după ridicare. Încercările de a anula o expediere care este deja in_transit, delivered sau fault returnează 409 Conflict. Anularea uneia care este deja cancelled nu are niciun efect și returnează 200 cu expedierea — vezi Idempotență.
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âmpurile origin și destination din răspunsul expedierii conțin obiecte de adresă rezolvate cu următoarea structură:
Pentru un colet de la cabinet, adresa 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âmpul pickup 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 array status_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. null câ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, GOY001 la GO!; VA, ZF, LA, ZU la DHL). null când curierul nu a furnizat niciunul. Stabil indiferent de limba în care este tradus status.
  • detail_code — codul mai detaliat al curierului, acolo unde există: statusDetailed de 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. null câ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).
Când curierul returnează coletul expeditorului, cronologia primește o intrare cu 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:
Rândul de retur există din momentul în care eticheta de retur este tipărită și rămâne pending până când pacientul trimite proba — aceasta este starea reală, nu o lipsă.