API

Den här sidan beskriver hur identifierarfält i shipment request normaliseras före validering och bokning. Beteendet här bygger på den nuvarande pipelinen i api-repo:t.

Bearbetningsordning

Shipment requests normaliseras i den här ordningen:

organizationId kan byta tenant-kontekst till en underorganisation.
senderId och receiverId försöker fylla sender och receiver.
organizationId kan fylla sender från den valda organisationens profil när sender och senderId saknas.
consignmentTemplateId eller auto-apply-template mergas in i requesten.
en tjänstespecifik pickup-adress kan fylla pickupAddress.
senderAddressId och receiverAddressId kan sent i pipelinen skriva över sender och receiver.
freightPayerId eller freightPayer.customerNumber kan fylla freightPayer och carrier contract-kontexten.

Senare resolvers vinner över tidigare.

Sammanfattning

Fält	Accepterar	Resolverar	Overwrite-beteende
`organizationId`	underorganisations `ulid` eller `quick_id`	tenant-kontekst, ibland `sender`	fyller inte `sender` om `senderId` eller `sender` redan finns
`senderId`	i praktiken en sender-adress `quick_id`	`sender`	om den hittas ersätter den inline-`sender`
`receiverId`	i praktiken en receiver-adress `quick_id`	`receiver`	om den hittas ersätter den inline-`receiver`
`consignmentTemplateId`	template `id` eller `quick_id`	template-payload	requesten vinner i normalläge, templaten i override-läge
`senderAddressId`	address book-`id` eller `quick_id`	`sender`	körs sent och vinner därför över `senderId` och organization sender fill
`receiverAddressId`	address book-`id` eller `quick_id`	`receiver`	körs sent och vinner därför över `receiverId`
`freightPayerId`	address book-`id` eller `quick_id`	`freightPayer` och contract-kontext	fungerar bara om adressen har contract för aktuellt `serviceId`
`organizationMemberId`	befintlig `organization_members.id`	ingenting	valideras bara just nu

Viktiga kombinationer

endast organizationId: tenant byts och sender fylls från organisationsprofilen
organizationId + senderId: tenant byts, sedan avgör senderIdsender
senderId + sender: en lyckad lookup via senderId ersätter hela sender
ogiltig senderId + sender: senderId blir null och den explicita sender ligger kvar
senderId + senderAddressId: slutlig sender kommer från senderAddressId

senderId och receiverId

senderId och receiverId körs före consignment templates. Om lookupen lyckas skrivs hela party-payloaden om.

den nuvarande fill-pipen resolverar dessa fält med quick_id
olösta värden normaliseras till null
en lyckad lookup vinner över tidigare inline-data

Notera

Valideringen accepterar numeriskt adress-id eller quick_id för senderId och receiverId, men den nuvarande fill-pipen resolverar dem via quick_id. I praktiken bör dessa fält använda quick_id.

senderAddressId och receiverAddressId

De här fälten är separata från senderId och receiverId.

lookup görs i tenantens address book
lookup accepterar adressens numeriska id eller quick_id
en lyckad lookup ersätter hela sender eller receiver
receiverAddressId kan också fylla preNoticeEmail, preNoticeSMS och deliveryInstructions
senderAddressId kan också fylla pickupInstructions

Eftersom de körs senare i pipelinen vinner de över tidigare party-resolve.

consignmentTemplateId

consignmentTemplateId accepterar template id eller quick_id. När en template resolveras normaliseras requesten till template:ns riktiga id.

normalläge: request-värden vinner och templaten fyller luckor
override-läge: template-värden vinner
items och parcels mergas per index med samma prioritet
templaten kan fylla saknad serviceId

freightPayerId

freightPayerId fyller inte sender eller receiver. Det resolverar third-party-betalningskontext.

kräver serviceId
gör lookup i tenantens address book med id eller quick_id
fyller bara freightPayer om adressen har carrier contract för tjänsten
bygger i praktiken freightPayer från receiver-data plus löst customer number

Rekommendation

använd organisationens ulid eller quick_id i organizationId
använd quick_id i senderId och receiverId
använd senderAddressId och receiverAddressId när address book-posten uttryckligen ska vinna sent i pipelinen
använd consignmentTemplateId för defaults eller kontrollerad override
skicka inte flera resolvers för samma part om du inte medvetet vill använda prioriteringsordningen ovan