Denne artikkelen retter seg mot utviklere som ønsker å koble den nye metoden GetShipAdvise til en annen API.
Selv om vi i dette eksempelet bruker Shopify e-handelsplattform, vil tilnærmingen sannsynligvis være lik på andre plattformer.
Merk: Dette er kun for å vise en grunnleggende måte å konvertere forespørsler/svar mellom de to API-ene.
Du må implementere din egen forretningslogikk og feilhåndtering.
Du bør ikke stille spørsmål til nShift Support angående Shopify.
Bruk i stedet Shopify-fellesskapsforumet her.
Innhold i denne artikkelen:
- Registrere en Carrier Service i en utviklingsbutikk
- Utveksling av data mellom Shopify og ShipAdvisor
- Fraktregler
- Transportørens ytelse
Krav
-
Shipment Server API
I API-et vil vi bruke metoden GetShipAdvise
-
Shopify Carrier Service API
Carrier Service API lar Shopify-butikker integrere tilpassede fraktmetoder. Dette gjøres ved å sende en ekstern API-forespørsel til appen og hente transportør-/fraktbeskrivelser og priser.Når en bruker starter en utsjekk, sendes en forespørsel til URL-en som Carrier Service peker til. Forespørselen inneholder informasjon om varene, mottaker og avsender.
For å lære mer om Shopify Carrier Service API, besøk de offisielle dokumentene her:
https://help.shopify.com/en/api/reference/shipping-and-fulfillment/carrierservice
-
Fraktregler
En XML-fil som inneholder produktene som skal vises i butikken -
Transportørens ytelse
En XML-fil som inneholder beregning av forventet leveringstid (ETA) for de forskjellige produktene -
En Shopify utviklingsbutikk
https://www.shopify.com/partners
Registrere en Carrier Service i en Shopify-butikk
Opprett en ny privat app.
Appen må ha lese- og skrive tillatelse på Fraktrate, land og provinser-seksjonen.
Bruk metoden beskrevet her for å registrere en ny tjeneste.
Eksempelskriptet bruker Node.js og node-fetch for å sende data til Carrier API via POST.
fetch('https://YOUR_STORE.myshopify.com/admin/api/2019-07/carrier_services.json',{
headers: {
'X-Shopify-Access-Token':'YOUR_PASSWORD_FROM_THE_PRIVATE_APP',
'Content-Type':'application/json'
},
body: JSON.stringify({
"carrier_service": {
"name": "SA Shipping Rate Provider",
"callback_url": "URL_TO_YOUR_WEB_SERVICE_THAT_THE_CARRIER_SERVICE_CONNECTS_TO",
"service_discovery": true
}
}),
method: 'POST'
})Etter dette skal en ny prisleverandør være synlig i butikken.
Utveksling av data mellom Shopify og Ship Advisor
Forespørselen fra Carrier Service må oversettes til et format som GetShipAdvise-metoden kan forstå. Dataene forventes å være formatert som et Shipment Object
For å se et eksempel på forespørselsobjektet fra Carrier API, klikk her
Eksempelfunksjonen nedenfor bruker dette som input og returnerer et objekt med Receiver, Sender og Lines.
Filteret .filter(x => x.requires_shipping) brukes for å filtrere ut produkter fra Shopify-butikken som ikke er merket til å kreve frakt. Du kan fjerne denne delen hvis du ikke trenger den.
Det finnes flere måter å konstruere Lines-arrayen slik at den samsvarer med innholdet i handlekurven.
I dette eksempelet er det hardkodet at hvert element representerer en pakke i forsendelsen.
const translateShopifyRequest = ({origin, destination, items}, output = {}) = {
let tmpLineObject = items.filter(x = x.requires_shipping).map((item) = {
return {
"References": [{
"Kind": 23,
"Value": item.vendor || ""
}],
"PkgWeight": item.grams,
"Number": 1
}
})
output = {
"Addresses": [{
"Kind": 1,
"Name1": destination.name,
"Street1": destination.address1,
"PostCode": destination.postal_code,
"City": destination.city,
"CountryCode": destination.country
}, {
"Kind": 2,
"Name1": origin.name,
"Street1": origin.address1,
"PostCode": origin.postal_code,
"City": origin.city,
"CountryCode": origin.country
}],
"Lines": tmpLineObject
}
return output
}Shopify Carrier Service API forventer at svaret skal være et rates-objekt.
Eksempelfunksjonen nedenfor tar responsen fra GetShipAdvise og returnerer det forventede objektet.
Merk: CustomFields kan inneholde hvilken som helst egendefinert verdi som du også måtte trenge å returnere med produktene.
const translateShipAdvisorResponse = ({Products}, output = {"rates": []}) = {
output.rates = Products.map((product) = {
let startDate = new Date(Date.parse(product.DeliveryDate))
let serviceName = (product.CustomFields && product.CustomFields.type) ? product.CustomFields.type : "",
let serviceCode = (product.CustomFields && product.CustomFields.servicecode) ? product.CustomFields.servicecode : "",
return {
"service_name": serviceName,
"service_code": serviceCode,
"total_price": product.Price,
"description": product.ProdName,
"currency": product.PriceCurrency,
"min_delivery_date": startDate.toISOString(),
"max_delivery_date": startDate.toISOString()
}
}) || []
return output
}
Fraktregler
CSR håndterer filtreringen av produkter.
Attributtet carriervalidation på CSR-noden forteller motoren om den skal bruke standard transportørvalidering.
I dette eksempelet er standardvalidering deaktivert, og tilpasset validering brukes direkte på produktene. Begge kan brukes samtidig om nødvendig.
<?xml version="1.0" encoding="utf-8"?>
<CSR carriervalidation="0" defaultservicelevel="Service_Level_Configured_For_SA">
<Prices>
<Price name="fixed59" currency="DKK">
<Exceptions>
<Exception price="5900">
<ValidationRules>
</ValidationRules>
</Exception>
</Exceptions>
<Fees>
<Fee price="1900">
<ValidationRules>
</ValidationRules>
</Fee>
</Fees>
</Price>
<Price name="fixed39" currency="DKK">
<Exceptions>
<Exception price="3900">
<ValidationRules>
</ValidationRules>
</Exception>
</Exceptions>
</Price>
</Prices>
<ServiceLevels>
<ServiceLevel name="Service_Level_Configured_For_SA">
<Products>
<Product adviseprice="fixed39" name="GLS DK - Pakkeshop med Drop Points" conceptid="1551">
<ProductGoodsType goodstypeid="0"/>
<CustomFields type="Pickup Point" servicecode="P1"/>
<ValidationRules>
<ValidationRule name="country" allowcountries="DK" field="fld_AdrCountry"/>
</ValidationRules>
</Product>
<Product adviseprice="fixed59" name="GLS DK - Normal erhvervspakke" conceptid="113">
<ProductGoodsType goodstypeid="0"/>
<CustomFields type="Home Delivery" servicecode="P2"/>
<ValidationRules>
<ValidationRule name="country" allowcountries="DK" field="fld_AdrCountry"/>
</ValidationRules>
<Services>
<Service serviceid="11020" name="Private Delivery Service"/>
</Services>
</Product>
<Product adviseprice="fixed59" name="GLS DK - Export" conceptid="189">
<ProductGoodsType goodstypeid="0"/>
<CustomFields type="Home Delivery" servicecode="P3"/>
<ValidationRules>
<ValidationRule name="country" allowcountries="SE" field="fld_AdrCountry"/>
</ValidationRules>
</Product>
</Products>
</ServiceLevel>
</ServiceLevels>
</CSR>
Transportørens ytelse
Dette er et veldig enkelt eksempel som viser ETA-beregningene for produktene brukt i CSR-konfigurasjonen.
<?xml version="1.0" encoding="utf-8"?>
<ConsignorETA>
<Areas>
<Area name="Nordic" type="countries">
<AreaItem countries="DK,SE"/>
</Area>
</Areas>
<PickupSchedules>
<PickupSchedule name="default" pickingtime="00:10" weekstartsonsunday="0">
<Pickup time="11:00" days="1,2,3,4,5"/>
</PickupSchedule>
</PickupSchedules>
<TransitTimes>
<TransitTime name="profile1" pickupschedule="default" trigger="submit" initiatedays="1,2,3,4,5" deliverydays="1,2,3,4,5" transportdays="1,2,3,4,5" weekstartsonsunday="0">
<Products>
<Product id="1551" name="GLS DK - Pakkeshop med Drop Points"/>
</Products>
<TimeTable>
<From area="Nordic">
<To area="Nordic" days="1" earliest="07:00" latest="18:00"/>
</From>
</TimeTable>
</TransitTime>
<TransitTime name="profile2" pickupschedule="default" trigger="submit" initiatedays="1,2,3,4,5" deliverydays="1,2,3,4,5" transportdays="1,2,3,4,5" weekstartsonsunday="0">
<Products>
<Product id="113" name="GLS DK - Normal erhvervspakke"/>
</Products>
<TimeTable>
<From area="Nordic">
<To area="Nordic" days="2" earliest="07:00" latest="18:00"/>
</From>
</TimeTable>
</TransitTime>
<TransitTime name="profile3" pickupschedule="default" trigger="submit" initiatedays="1,2,3,4,5" deliverydays="1,2,3,4,5" transportdays="1,2,3,4,5" weekstartsonsunday="0">
<Products>
<Product id="189" name="GLS DK - Export"/>
</Products>
<TimeTable>
<From area="Nordic">
<To area="Nordic" days="3" earliest="07:00" latest="18:00"/>
</From>
</TimeTable>
</TransitTime>
</TransitTimes>
</ConsignorETA>
Forventet resultat når en adresse fra Danmark brukes.
Forventet resultat når en adresse fra Sverige brukes.