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:anivavaiexternal. Tikaianivasūtījumiem darbojas Atjaunināt un Atcelt;externalpaka tiek izsekota tajā pašā sarakstā, bet abos gadījumos atgriež501.
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ā.
appointmentsunhome_kit_ordersuzskaita 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 iestatasynced_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ākumpunktulocation_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ā
appointmentsmasīvs ar{ id, added_at }ierakstiem; - pierakstā kā
shipmentsmasīvs ar{ id, added_at }ierakstiem.
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 arPATCH /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.
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, izmantojotDELETE /api/v1/shipments/{id}. Tas izsauc loģistikas pakalpojumu sniedzēja API, lai atceltu pasūtījumu, un atjaunina statusu uz cancelled.
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 laukiorigin un destination satur atrisinātus adrešu objektus ar šādu struktūru:
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 laukspickup 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 irstatus_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 navcancelled— atcelšana ir mūsu, nevis pārvadātāja notikums.code— paša pārvadātāja statusa kods (GO!GO10,GO90,GOY001; DHLVA,ZF,LA,ZU).null, ja pārvadātājs to nenorādīja. Nemainās dažādosstatusvalodu tulkojumos.detail_code— pārvadātāja detalizētāks kods, ja tāds pastāv: DHLstatusDetailed, 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).
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:
pending, līdz pacients nosūta paraugu — tas ir patiess stāvoklis, nevis iztrūkums.