Pāriet uz galveno saturu
Sūtījums ir viena fiziska paka: kurjera savākts sūtījums ar asins paraugiem no testēšanas vietas uz laboratoriju, komplekts ceļā pie mājas testa komplekta pacienta vai paraugs, ko šis pacients nosūta atpakaļ. Sūtījumu API ļauj tev izveidot, izsekot, mainīt un atcelt sūtījumu pasūtījumus un vienuviet uzskaita visas pakas neatkarīgi no tā, kas tās pieteicis.

Viens saraksts, filtrēts

GET /api/v1/shipments ir vienīgā kolekcija. Sūtījums ir patstāvīga vienība — tam ir daudzi-pret-daudziem saistība ar pierakstiem, un tas var piederēt mājas testa komplekta pasūtījumam —, tāpēc nevienam vecākobjektam nav pakārtota saraksta. Sašaurini to pašu sarakstu ar ?appointment_id= vai ?home_kit_order_id=, sadali lapās ar limit / offset un izmanto vecākobjektā iekļauto masīvu shipments ({ id, added_at } gan pierakstos, gan mājas testa komplektu pasūtījumos), lai atvērtu Iegūt sūtījumu, kad tev ir viens ID.

Saturs un pasūtītājs

Katram sūtījumam ir divi fakti, kas nav redzami no tā adresēm:
  • contents — brīvs teksts, kas apraksta pakas saturu, iestatīts izveides brīdī ("Medizinisch freigestellte Probe", "Home test kit") un rādīts kurjeram. Tikai informatīvs. Virziens nav atsevišķs lauks: to, vai paka dodas uz laboratoriju, var nolasīt laukā destination.
  • booked_by — kas izdrukāja uzlīmi: aniva vai external. Tikai aniva sūtījumiem darbojas Atjaunināt un Atcelt; external paka tiek izsekota tajā pašā sarakstā, bet abos gadījumos atgriež 501.
Paka, kurā bija iekļauta atgriešanas uzlīme, un paka, ko šī uzlīme nogādā atpakaļ, savstarpēji norāda viena uz otru laukā paired_with.

Piekļuve

  • Tu vari lasīt paku, ja vismaz viens piesaistīts pieraksts vai mājas testa komplekta pasūtījums ir tavā piekļuves kontekstā vai ja tā nosūtīta no atrašanās vietas tavā piekļuves kontekstā.
  • appointments un home_kit_orders uzskaita tikai pierakstus un pasūtījumus tavā piekļuves kontekstā.
  • Darbībām Atjaunināt, Atcelt, Piesaistīt pierakstus un Atsaistīt pierakstus nepieciešams, lai visi piesaistītie mājas testa komplektu pasūtījumi būtu tavā piekļuves kontekstā. Pretējā gadījumā izsaukums atgriež 403, un paku var mainīt tikai Aniva.

Lasīšana nekad neizsauc pārvadātāju

Katrs lasīšanas pieprasījums tiek apkalpots no mūsu datubāzes. Fona sinhronizācija salīdzina katru sūtījumu ar tā pārvadātāju (ik pēc 10 minūtēm GO!, reizi stundā DHL) un iestata synced_at, kas parāda atbildes vecumu. Piespiedu atsvaidzināšanas nav — DHL atļauj vienu izsekošanas izsaukumu ik pēc piecām sekundēm, tāpēc lasīšanu ar tiešu pieprasījumu pārvadātājam nevar piedāvāt.

Sūtījuma izveide

Izveidojot sūtījumu, tu norādi sākumpunktu location_id — testēšanas vietu, kur kurjeram tas jāpaņem. Tu norādi arī galamērķa laboratoriju laukā destination_lab. Sūtījums tiek nosūtīts uz šīs laboratorijas reģistrēto piegādes adresi. Atrašanās vietai jābūt tavas API atslēgas piekļuves kontekstā. Izmanto Skatīt atrašanās vietas, lai atrastu pieejamos atrašanās vietu ID. Pēc izvēles vari norādīt appointment_id, lai izveides brīdī piesaistītu sūtījumu konkrētam pierakstam. Saistība parādās abās pusēs:
  • sūtījumā kā appointments masīvs ar { id, added_at } ierakstiem;
  • pierakstā kā shipments masīvs ar { id, added_at } ierakstiem.
Abos masīvos vispirms ir vecākā saistība. Katrs id norāda uz kanonisko detalizētās informācijas galapunktu (Iegūt pierakstu / Iegūt sūtījumu), lai saņemtu pilnus datus — partneri, kuri vēlas sekot kurjera gaitai katram pierakstam, seko katram ierakstam pieraksta shipments masīvā līdz sūtījuma detalizētās informācijas galapunktam. Sūtījumu var piesaistīt vairākiem pierakstiem, un pierakstu var piesaistīt vairākiem sūtījumiem. Pēc izveides pārvaldi saistību ar Piesaistīt pierakstus sūtījumam / Atsaistīt pierakstus no sūtījuma. Katra izmaiņa atgriež sūtījuma pierakstu sarakstu pēc izmaiņas. Izmaiņu noteikums ir šāds: saistības var izveidot vai noņemt, ja VAI NU pierakstam jau ir notikusi asins paņemšana (blood_drawn), vai arī sūtījums tika izveidots pirms mazāk nekā 24 stundām. Ārpus šī laika loga saistība ir bloķēta, lai vēsturiskie ieraksti paliktu nemainīgi.

Dzīves cikls

Sūtījumi iziet cauri šādiem statusiem:
Katra statusa maiņa nosūta shipment.* tīmekļa āķi, piemēram, shipment.delivered. shipment.updated nostrādā pie katras izmaiņas, ko vari nolasīt, piemēram, jauna skenējuma.

Paņemšanas grafika noteikumi

Izveidojot vai atjauninot sūtījuma paņemšanas grafiku, ir spēkā šādi noteikumi. pickup_date (YYYY-MM-DD) un pickup_time_from / pickup_time_till (HH:MM, 24 h) ir vietējā pulksteņa vērtības, kas tiek interpretētas izsūtīšanas vietas IANA laika joslā — laika joslu tām līdzi nesūti.

Sūtījumu mainīšana

Sūtījuma paņemšanas grafiku, paku skaitu, svaru un piezīmes vari atjaunināt ar PATCH /api/v1/shipments/{id}. Ja mainās kāds loģistikai būtisks lauks (paņemšanas datums, laiks, paku skaits vai svars), esošais loģistikas pasūtījums tiek automātiski atcelts un tiek izveidots jauns. Lauki, kurus izlaid atjauninājuma saturā, tiek saglabāti no esošā sūtījuma — piemēram, atjauninot tikai weight, pasūtījums tiks izveidots no jauna ar to pašu paņemšanas grafiku. Atjauninātie grafika lauki tiek pārbaudīti pēc tiem pašiem paņemšanas grafika noteikumiem.
Sūtījumus nevar mainīt pēc tam, kad kurjers ir paņēmis paku. Mēģinājums atjaunināt sūtījumu statusā in_transit, delivered vai fault atgriež 409 Conflict.
Ja loģistikas pakalpojumu sniedzējs atjaunināšanas laikā noraida atcelšanu vai atkārtotu izveidi, API atgriež 502 Bad Gateway ar sniedzēja kļūdas ziņojumu.

Sūtījumu atcelšana

Atcel sūtījumu, izmantojot DELETE /api/v1/shipments/{id}. Tas izsauc loģistikas pakalpojumu sniedzēja API, lai atceltu pasūtījumu, un atjaunina statusu uz cancelled.
Sūtījumus nevar atcelt pēc paņemšanas. Mēģinājums atcelt sūtījumu, kas jau ir statusā in_transit, delivered vai fault, atgriež 409 Conflict. Jau cancelled statusā esoša sūtījuma atcelšana neveic nekādas izmaiņas un atgriež 200 ar pašu sūtījumu — skati Idempotence.
Loģistikas pakalpojumu sniedzējs var noraidīt atcelšanu arī savu iemeslu dēļ (piemēram, ir pagājis atcelšanas termiņš). Šādā gadījumā API atgriež 502 Bad Gateway ar sniedzēja kļūdas ziņojumu un kļūdas kodu.

Atpakaļsūtīšanas uzlīmes

DHL atpakaļsūtīšanas uzlīme ir daļa no izejošā pasūtījuma. DHL nevar atcelt uzlīmi atsevišķi, tāpēc tās rindas atcelšana, kas izseko atpakaļsūtīšanas uzlīmi, atgriež 409 Conflict. Tā vietā atcel izejošo paku, kamēr tā ir statusā pending. Tas vienlaikus atceļ arī uzlīmi: katra izejošās pakas atpakaļsūtīšanas rinda statusā pending kļūst par cancelled un saņem RETURN_LEG_CANCELLED ierakstu laukā status_updates. Atpakaļsūtāmā paka, ko pacients jau ir nosūtījis, turpina ceļu. Kad izejošā paka ir izsūtīta, uzlīme paliek derīga, un Aniva aizver atpakaļsūtīšanas rindu manuāli.

Sūtījumu atsauces ID

Katram sūtījumam ir 11 rakstzīmju atsauces ID: burts, datums un četras rakstzīmes, {letter}YYMMDDXXXX (piemēram, P2611194821). Burts norāda, kam sūtījums pieder, bet nekad nenorāda tā virzienu: Sūtījums no 2026. gada 20. līdz 22. novembrim saglabā savu ID ar vārdu priekšā: API, MAN, AUTO vai KIT (piemēram, AUTO261121UWKX). Abas formas paliek derīgas. Nepārbaudi ID garumu vai pirmo burtu. Izmanto šo ID, lai izgūtu, atjauninātu vai atceltu sūtījumu.

Sūtījumu adreses

Sūtījuma atbildes lauki origin un destination satur atrisinātus adrešu objektus ar šādu struktūru:
Prakses pakai origin adrese tiek iegūta no analīžu vietas, ko norādīji izveides laikā, bet destination ir laboratorija, ko norādīji laukā destination_lab. Mājas komplekta pakai pacienta piegādes adrese ir komplekta destination un parauga atpakaļsūtīšanas origin; vieta, kur komplektu iepako, ir tā origin. Adresē nav location_id — prakses paku sasaisti pēc pieraksta, kuram tā ir piesaistīta.

Paņemšanas logs

Sūtījuma atbildes lauks pickup satur ieplānoto kurjera paņemšanas logu. Tas ietver from un till laikspiedolus kā UTC laika punktus (ISO 8601 ar Z sufiksu, piemēram, 2026-04-15T07:00:00Z) un timezone virkni (paņemšanas vietas IANA laika joslu). Vietējā pulksteņa vērtības pickup_date / pickup_time_*, ko nosūtīji izveides vai atjaunināšanas laikā, tiek pārveidotas par šiem absolūtajiem laika punktiem, izmantojot šo laika joslu — izmanto timezone, lai attēlotu from / till atpakaļ paņemšanas vietas vietējā laikā. Lauks ir null, ja paņemšanas logs nav ieplānots.

Statusa atjauninājumu žurnāls

Katram sūtījumam ir status_updates masīvs — visi aprites cikla notikumi, par kuriem loģistikas pakalpojumu sniedzējs ir ziņojis, sākot ar vecāko. Katrs ieraksts satur:
  • state — notikums sūtījumu statusu vārdnīcā (pending, in_transit, delivered, fault), lai tu varētu lasīt laika skalu, nezinot pārvadātāja kodus. null, ja notikumam nav statusa (uzlīmes izveide, pārvadātāja skenējums bez informācijas, ieraksti, kas saglabāti pirms šī lauka ieviešanas). Nekad nav cancelled — atcelšana ir mūsu, nevis pārvadātāja notikums.
  • code — paša pārvadātāja statusa kods (GO! GO10, GO90, GOY001; DHL VA, ZF, LA, ZU). null, ja pārvadātājs to nenorādīja. Nemainās dažādos status valodu tulkojumos.
  • detail_code — pārvadātāja detalizētāks kods, ja tāds pastāv: DHL statusDetailed, piemēram, CNRFC_NRQRD_ZF (novirzīts uz pasta nodaļu), HLDCC_SERPT_LA (gatavs saņemšanai tur), DLVRD_SERPT_ZU (izņemts). Citur — null.
  • status — cilvēkam lasāms pārvadātāja apzīmējums (piemēram, "Shipment picked up", "Die Sendung wurde abgeholt.").
  • description — koda skaidrojums vai pārvadātāja garāks teikums. null, ja nav neviena no tiem.
  • location — vieta, kur notika skenēšana, kā to nosauc pārvadātājs: GO! depo, DHL pilsēta. Brīvs teksts, nevis koordinātas.
  • time — notikuma ISO 8601 laikspiedols, kā to ziņojis pārvadātājs (ar tā nobīdi).
Kad pārvadātājs nosūta paku atpakaļ sūtītājam, laika skalā parādās viens ieraksts ar code RETURNED_TO_SENDER. Tā status satur pārvadātāja norādīto iemeslu. Sūtījums pēc tam paliek statusā fault arī pēc tam, kad pārvadātājs paku ir piegādājis atpakaļ mums. Saraksts var būt tukšs, ja pārvadātājs vēl nav ziņojis ne par vienu notikumu. Pašreizējam kanoniskajam stāvoklim izmanto augstākā līmeņa lauku status. Tas virzās vienā virzienā — no pending uz in_transit un delivered — ar pārklātu fault, kamēr jaunākais notikums par tādu ziņo; pārvadātāji nesakārto notikumus pēc nozīmīguma (DHL pēc nodošanas skenējuma pievieno pāradresācijas paziņojumu ar kodu pre-transit), tāpēc jaunākais ieraksts viens pats nepasaka, kādā posmā paka atrodas.

Sūtījuma piemērs

Mājas komplekta paku piemērs

GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… atgriež komplektu ceļā pie pacienta un paraugu atpakaļceļā kā pāri:
Atpakaļsūtīšanas rinda pastāv no brīža, kad tiek izdrukāta atpakaļsūtīšanas uzlīme, un paliek statusā pending, līdz pacients nosūta paraugu — tas ir patiess stāvoklis, nevis iztrūkums.