Log ind

nShift Help Center

Forbindelse af Ship Advisor 2.0 til en tredjeparts API

Avatar
Simon Schrader Springer
Opdateret

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:

  

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.

mceclip9.png 

 

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.

mceclip7.png

Det forventede resultat, når en adresse fra Sverige bruges.

mceclip8.png

 

 

Relaterede artikler