Logg på

nShift Help Center

Koble Ship Advisor 2.0 til en tredjeparts-API

Avatar
Simon Schrader Springer
Oppdatert

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:

  

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.

mceclip9.png 

 

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.

mceclip7.png

Forventet resultat når en adresse fra Sverige brukes.

mceclip8.png

 

 

Relaterte artikler