API

Tämä sivu kuvaa, miten Shipitin shipment request -payloadin tunnistekentät normalisoidaan ennen validaatiota ja varausta. Sisältö perustuu api-repossa olevaan nykyiseen pipeline-järjestykseen, ei oletettuun käyttäytymiseen.

Suoritusjärjestys

Shipment request käsitellään käytännössä tässä järjestyksessä:

organizationId voi vaihtaa tenant-kontekstin aliorganisaatioon.
senderId ja receiverId yrittävät täyttää sender- ja receiver-objektit.
organizationId voi täyttää sender-objektin organisaation profiilista, jos sender ja senderId puuttuvat.
consignmentTemplateId tai auto-apply-template yhdistetään requestiin.
palvelukohtainen pickup-osoite voi täyttää pickupAddress-kentän.
senderAddressId ja receiverAddressId voivat lopuksi ylikirjoittaa sender- ja receiver-objektit.
freightPayerId tai freightPayer.customerNumber voi täyttää freightPayer-kentän ja carrier contract -kontekstin.

Tästä seuraa tärkeä sääntö: myöhemmin pipelineen tuleva resolveri voittaa aiemmin täytetyn datan.

Yhteenvetotaulukko

Kenttä	Mitä se hyväksyy	Mitä se täyttää	Huomio overwrite-käytöksestä
`organizationId`	aliorganisaation `ulid` tai `quick_id`	tenant-konteksti, joskus `sender`	ei täytä `sender`-kenttää, jos `senderId` tai `sender` on jo annettu
`senderId`	käytännössä sender-osoitteen `quick_id`	`sender`	jos löytyy, korvaa annetun `sender`-objektin kokonaan
`receiverId`	käytännössä receiver-osoitteen `quick_id`	`receiver`	jos löytyy, korvaa annetun `receiver`-objektin kokonaan
`consignmentTemplateId`	template `id` tai `quick_id`	koko request-template	normaalitilassa request voittaa, override-tilassa template voittaa
`senderAddressId`	osoitteen `id` tai `quick_id` address bookista	`sender`	ajetaan myöhään, joten voittaa myös `senderId`- ja `organizationId`-täytöt
`receiverAddressId`	osoitteen `id` tai `quick_id` address bookista	`receiver`	ajetaan myöhään, joten voittaa myös `receiverId`-täytön
`freightPayerId`	osoitteen `id` tai `quick_id` address bookista	`freightPayer` + sopimuskonteksti	toimii vain jos osoitteelta löytyy contract kyseiselle `serviceId`:lle
`organizationMemberId`	olemassa oleva `organization_members.id`	ei hydratoi payloadia	tällä hetkellä vain validoidaan

organizationId

organizationId ei hae sender-osoitetta address bookista. Se tekee ensin organisaatiokontekstin vaihdon, jos nykyisellä tenantilla on oikeus kohdeorganisaatioon.

Toimii näin:

jos arvo on aliorganisaation ulid tai quick_id, tenant vaihtuu siihen organisaatioon
jos arvo on numeerinen tietokanta-id, tenant ei vaihdu
jos käytössä on henkilötoken ilman organisaatiokontekstia, tenant ei vaihdu

Kun tenant on vaihdettu, sender voidaan täyttää valitun organisaation profiilista vain jos:

organizationId on annettu
senderId puuttuu tai on tyhjä
sender puuttuu tai on tyhjä taulukko

Esimerkit:

vain organizationId: tenant vaihtuu ja sender täytetään organisaatioprofiilista
organizationId + senderId: tenant vaihtuu, mutta sender tulee senderId:n kautta
organizationId + sender: tenant vaihtuu, mutta eksplisiittinen sender säilyy

senderId ja receiverId

senderId ja receiverId yrittävät täyttää party-objektit ennen consignment templatea. Jos osoite löytyy, resolveri kirjoittaa sender- tai receiver-taulukon kokonaan uudestaan.

Tärkeät yksityiskohdat:

nykyinen pipe hakee senderId- ja receiverId-kentät vain quick_id:llä
jos arvoa ei löydy, kenttä normalisoidaan null:iksi
jos arvo löytyy, mahdollinen aiemmin annettu sender tai receiver korvataan kokonaan

Esimerkit:

senderId + sender: löytynyt senderId voittaa ja korvaa annetun sender-objektin
receiverId + receiver: löytynyt receiverId voittaa ja korvaa annetun receiver-objektin
virheellinen senderId + sender: senderId muuttuu null:iksi ja annettu sender jää voimaan

Huomio

Vaikka validointisääntö hyväksyy senderId- ja receiverId-kenttiin myös osoitteen numeerisen id:n, nykyinen täyttöpipe hakee ne vain quick_id:llä. Käytännössä näihin kenttiin kannattaa lähettää quick_id, ei numeerista id:tä.

senderAddressId ja receiverAddressId

senderAddressId ja receiverAddressId ovat eri asia kuin senderId ja receiverId.

Ne toimivat näin:

lookup tehdään tenantin address bookista
lookup hyväksyy sekä osoitteen numeerisen id:n että quick_id:n
jos lookup onnistuu, sender tai receiver korvataan kokonaan
receiverAddressId täyttää lisäksi preNoticeEmail-, preNoticeSMS- ja tarvittaessa deliveryInstructions-kenttiä
senderAddressId täyttää tarvittaessa pickupInstructions-kentän

Koska nämä ajetaan pipeline-järjestyksessä myöhemmin kuin senderId ja receiverId, ne voittavat mahdolliset aiemmat täytöt.

Esimerkit:

senderId + senderAddressId: lopullinen sender tulee senderAddressId:stä
organizationId + senderAddressId: organisaatioprofiilista täytetty sender korvautuu address book -osoitteella

consignmentTemplateId

consignmentTemplateId hyväksyy sekä template id:n että quick_id:n. Jos template löytyy, requestiin kirjoitetaan aina lopuksi template:n oikea id.

Template voidaan aktivoida kahdella tavalla:

eksplisiittisesti consignmentTemplateId:llä
ilman kenttää auto-apply-säännöillä, jotka käyttävät ainakin serviceId:tä, isCompany-arvoa ja joissain tapauksissa receiver.postcode:a

Merge-säännöt:

oletustila: request voittaa, template täydentää puuttuvia kenttiä
override-tila (metadata.override = true): template voittaa
items ja parcels yhdistetään indeksikohtaisesti samalla logiikalla
jos requestilta puuttuu serviceId, template voi täyttää sen

Esimerkit:

consignmentTemplateId + sender.name: oletustilassa requestin sender.name säilyy, mutta template voi täydentää muita sender-kenttiä
consignmentTemplateId override-tilassa + sender.name: template voi ylikirjoittaa requestin arvon
template quick_id: request normalisoidaan lopuksi template:n oikeaan id:hen

freightPayerId

freightPayerId ei täytä lähetyksen sender- tai receiver-osapuolia, vaan ratkoo kolmannen osapuolen maksajasopimusta.

Toimii näin:

vaatii serviceId:n
lookup tehdään tenantin address bookista osoitteen id:llä tai quick_id:llä
jos osoitteella on carrier contract kyseiselle palvelulle, freightPayer.customerNumber täytetään siitä
varsinainen freightPayer-payload rakennetaan receiver-datan päälle

Jos requestissa on jo:

freightPayer.customerNumber
ja freightPayer.type = consignee

niin tämä polku voittaa ennen freightPayerId-lookupia ja freightPayer täytetään receiveristä.

Käytännön prioriteetit

Jos haluat täysin eksplisiittisen lopputuloksen, käytä suoraa sender-/receiver-payloadia ilman ID-resolvereita.

Jos haluat käyttää resolvereita, tärkeimmät prioriteetit ovat:

organizationId vaihtaa kontekstin, mutta ei voita eksplisiittistä sender-objektia
senderId ja receiverId voittavat eksplisiittiset party-objektit, jos lookup onnistuu
senderAddressId ja receiverAddressId voittavat myöhemmin lähes kaiken aiemmin täytetyn party-datan
consignmentTemplateId täydentää tai ylikirjoittaa dataa riippuen template:n override-tilasta

Suositus integraatioille

Suosi näitä käytäntöjä:

käytä organizationId-kenttään organisaation ulid:a tai quick_id:tä
käytä senderId- ja receiverId-kenttiin quick_id:tä
käytä senderAddressId- ja receiverAddressId-kenttiin address bookin id:tä tai quick_id:tä silloin, kun haluat nimenomaan address book -osoitteen voittavan lopputuloksen
käytä consignmentTemplateId-kenttää, kun haluat täydentää requestia oletuksilla tai hallitulla override-logiikalla
älä lähetä samaan osapuoleen montaa eri resolveria ellei tavoite ole nimenomaan hyödyntää yllä kuvattua prioriteettijärjestystä