API

Denne side beskriver, hvordan identifikatorfelter i shipment request bliver normaliseret før validering og booking. Adfærden her er baseret på den nuværende pipeline i api-repoet.

Rækkefølge

Shipment requests bliver normaliseret i denne rækkefølge:

organizationId kan skifte tenant-kontekst til en underorganisation.
senderId og receiverId forsøger at udfylde sender og receiver.
organizationId kan udfylde sender fra den valgte organisations profil, når sender og senderId mangler.
consignmentTemplateId eller auto-apply-template merges ind i requesten.
en servicespecifik pickup-adresse kan udfylde pickupAddress.
senderAddressId og receiverAddressId kan sent i pipelinen overskrive sender og receiver.
freightPayerId eller freightPayer.customerNumber kan udfylde freightPayer og carrier contract-kontekst.

Senere resolvers vinder over tidligere.

Oversigt

Felt	Accepterer	Resolver	Overwrite-adfærd
`organizationId`	underorganisations `ulid` eller `quick_id`	tenant-kontekst, nogle gange `sender`	udfylder ikke `sender`, hvis `senderId` eller `sender` allerede findes
`senderId`	i praksis en sender-adresses `quick_id`	`sender`	hvis den findes, erstatter den inline `sender`
`receiverId`	i praksis en receiver-adresses `quick_id`	`receiver`	hvis den findes, erstatter den inline `receiver`
`consignmentTemplateId`	template `id` eller `quick_id`	template-payload	request vinder i normal mode, template vinder i override mode
`senderAddressId`	address book `id` eller `quick_id`	`sender`	kører sent og overstyrer derfor også `senderId` og organization sender fill
`receiverAddressId`	address book `id` eller `quick_id`	`receiver`	kører sent og overstyrer derfor også `receiverId`
`freightPayerId`	address book `id` eller `quick_id`	`freightPayer` og contract-kontekst	virker kun hvis adressen har contract for det givne `serviceId`
`organizationMemberId`	eksisterende `organization_members.id`	ingenting	valideres kun i øjeblikket

Vigtige kombinationer

kun organizationId: tenant skifter, og sender udfyldes fra organisationsprofilen
organizationId + senderId: tenant skifter, derefter bestemmer senderId værdien af sender
senderId + sender: en vellykket lookup via senderId erstatter hele sender
ugyldig senderId + sender: senderId bliver null, og den eksplicitte sender bliver stående
senderId + senderAddressId: den endelige sender kommer fra senderAddressId

senderId og receiverId

senderId og receiverId kører før consignment templates. Hvis lookupen lykkes, bliver hele party-payloaden skrevet om.

den nuværende fill-pipe resolver disse felter via quick_id
uløste værdier normaliseres til null
en vellykket lookup vinder over tidligere inline-data

Bemærk

Valideringsreglen accepterer numerisk adresse-id eller quick_id for senderId og receiverId, men den nuværende fill-pipe resolver dem via quick_id. I praksis bør disse felter bruge quick_id.

senderAddressId og receiverAddressId

Disse felter er adskilt fra senderId og receiverId.

lookup sker i tenantens address book
lookup accepterer numerisk adresse-id eller quick_id
en vellykket lookup erstatter hele sender eller receiver
receiverAddressId kan også udfylde preNoticeEmail, preNoticeSMS og deliveryInstructions
senderAddressId kan også udfylde pickupInstructions

Fordi de kører senere i pipelinen, vinder de over tidligere party-resolve.

consignmentTemplateId

consignmentTemplateId accepterer template id eller quick_id. Når en template bliver resolved, normaliseres requesten til template'ens rigtige id.

normal mode: request-værdier vinder, og templaten udfylder huller
override mode: template-værdier vinder
items og parcels merges per indeks med samme logik
templaten kan udfylde manglende serviceId

freightPayerId

freightPayerId udfylder ikke sender eller receiver. Det resolver third-party betalingskontrakt-kontekst.

kræver serviceId
slår op i tenantens address book via id eller quick_id
udfylder kun freightPayer, hvis adressen har contract for tjenesten
bygger i praksis freightPayer ud fra receiver-data plus det resolvede customer number

Anbefaling

brug organisationens ulid eller quick_id i organizationId
brug quick_id i senderId og receiverId
brug senderAddressId og receiverAddressId, når address book-posten eksplicit skal vinde sent i pipelinen
brug consignmentTemplateId til defaults eller kontrolleret override
undgå at sende flere resolvers for samme part, medmindre du bevidst vil bruge prioriteringsrækkefølgen ovenfor