Denne artikel henvender sig til udviklere, der ønsker at forbinde den nye metode GetShipAdvise til en anden API.
Selvom vi i dette eksempel bruger Shopify e-handelsplatformen, vil tilgangen sandsynligvis være lignende på andre platforme.
Bemærk: Dette viser kun en grundlæggende måde at konvertere forespørgsler/svar mellem de to API'er.
Du skal anvende din egen forretningslogik og fejlhåndtering.
Du bør ikke stille spørgsmål til nShift Support vedrørende Shopify.
Men brug i stedet Shopify community-forummet her.
Indhold i denne artikel:
- Registrering af en Carrier Service i en udviklingsbutik
- Udveksling af data mellem Shopify og ShipAdvisor
- Forsendelsesregler
- Carrier Performance
Krav
-
Shipment Server API
På API'en vil vi bruge metoden GetShipAdvise
-
Shopify Carrier Service API
Carrier Service API'en tillader Shopify-butikker at inkorporere brugerdefinerede forsendelsesmetoder. Det gør det ved at lave en ekstern API-forespørgsel til appen og hente carrier-/forsendelsesbeskrivelser og priser.Når en bruger påbegynder en checkout, sendes en forespørgsel til den URL, som Carrier Service peger på. Forespørgslen indeholder information om varer, modtager og afsender.
For at lære mere om Shopify Carrier Service API, besøg de officielle dokumenter her:
https://help.shopify.com/en/api/reference/shipping-and-fulfillment/carrierservice
-
Forsendelsesregler
En XML-fil, der indeholder produkterne, som vil blive vist i butikken -
Carrier Performance
En XML-fil, der indeholder beregningen af ETA for de forskellige produkter -
En Shopify udviklingsbutik
https://www.shopify.com/partners
Registrer en Carrier Service i en Shopify-butik
Opret en ny privat app.
Appen skal have Læs og Skriv tilladelse i sektionen Forsendelsespris, lande og provinser.
Brug metoden beskrevet her til at registrere en ny service.
Eksempelscriptet bruger Node.js og node-fetch til at sende data til Carrier API'en med 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'
})Efter dette bør en ny prisudbyder være synlig i butikken.
Udveksling af data mellem Shopify og Ship Advisor
Forespørgslen fra Carrier Service skal oversættes til et format, som GetShipAdvise-metoden kan forstå. Data forventes at være formateret som et Shipment Object
For at se et eksempel på forespørgselsobjektet fra Carrier API, klik her
Eksempelfunktionen nedenfor vil bruge dette som input og returnere et objekt med en Receiver, Sender & Lines.
Den .filter(x => x.requires_shipping) bruges til at filtrere produkter fra Shopify-butikken, som ikke er markeret til at kræve forsendelse. Du kan fjerne denne del, hvis du ikke har brug for det.
Der er flere måder, hvorpå du kan konstruere Lines-arrayet, så det matcher indholdet i indkøbskurven.
I dette eksempel er det hårdkodet, at hver vare repræsenterer 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 er et rates-objekt.
Eksempelfunktionen nedenfor tager svaret fra GetShipAdvise og returnerer det forventede objekt.
Bemærk: CustomFields kan indeholde enhver brugerdefineret værdi, som du også måtte have brug for at returnere med produkterne.
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
}
Shipping Rules
Shipping Rules vil håndtere filtreringen af produkter.
Attributten carriervalidation på CSR-noden fortæller motoren, om den skal bruge standardvalidering af carrier.
I dette eksempel er standardvalidering deaktiveret, og brugerdefineret validering bruges direkte på produkterne. Begge kan bruges samtidigt, hvis nødvendigt.
<?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>
Carrier Performance
Dette er et meget grundlæggende eksempel, der viser ETA-beregningerne for de produkter, der bruges i CSR-konfigurationen.
<?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>
Det forventede resultat, når en adresse fra Danmark bruges.
Det forventede resultat, når en adresse fra Sverige bruges.