Logga in

nShift Help Center

Ansluta Ship Advisor 2.0 till ett tredjeparts-API

Avatar
Simon Schrader Springer
Uppdaterad

Denna artikel riktar sig till utvecklare som vill ansluta den nya metoden GetShipAdvise till ett annat API.

Även om vi i detta exempel använder e-handelsplattformen Shopify, skulle tillvägagångssättet sannolikt vara liknande på andra plattformar.

Observera: Detta är endast för att visa ett grundläggande sätt att konvertera förfrågningar/svar mellan de två API:erna.
Du behöver tillämpa din egen affärslogik och felhantering.

Du bör inte ställa frågor till nShift Support angående Shopify. 
Använd istället Shopify community-forumet här.

 

Innehåll i denna artikel:

  

Krav 

  • Shipment Server API
    På API:et kommer vi att använda metoden GetShipAdvise
     

  • Shopify Carrier Service API
    Carrier Service API tillåter Shopify-butiker att integrera anpassade fraktmetoder. Det görs genom att skicka en extern API-förfrågan till appen och hämta transportör-/fraktbeskrivningar och priser.

    När en användare initierar en kassa skickas en förfrågan till den URL som Carrier Service pekar på. Förfrågan innehåller information om artiklar, mottagare och avsändare.

    För att lära dig mer om Shopify Carrier Service API, besök den officiella dokumentationen här:
    https://help.shopify.com/en/api/reference/shipping-and-fulfillment/carrierservice

     

  • Fraktregler
    En XML-fil som innehåller produkterna som ska visas i butiken
  • Transportörens prestanda
    En XML-fil som innehåller beräkningen av ETA för de olika produkterna
  • En Shopify utvecklingsbutik
    https://www.shopify.com/partners

 

Registrera en Carrier Service i en Shopify-butik

Skapa en ny privat app.

Appen behöver ha Läs- och skrivbehörighet för avsnittet Fraktpriser, länder och provinser.

Använd metoden som beskrivs här för att registrera en ny tjänst.

Exempelskriptet använder Node.js och node-fetch för att POST:a data till Carrier API.

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 detta bör en ny prisleverantör synas i butiken.

mceclip9.png 

 

Utbyte av data mellan Shopify och Ship Advisor

Förfrågan från Carrier Service behöver översättas till ett format som metoden GetShipAdvise kan förstå. Data förväntas vara formaterad som ett Shipment Object

För att se ett exempel på förfrågningsobjektet från Carrier API, klicka här
Exempelfunktionen nedan kommer att använda detta som indata och returnera ett objekt med en Receiver, Sender & Lines.

Den .filter(x => x.requires_shipping) används för att filtrera bort produkter från Shopify-butiken som inte är markerade för att kräva en leverans. Du kan ta bort denna del om du inte behöver den.

Det finns några sätt att konstruera Lines-arrayen så att den matchar innehållet i kundvagnen.

I detta exempel är det hårdkodat att varje artikel representerar ett paket i leveransen.

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 förväntar sig att svaret ska vara ett rates-objekt.

Exempelfunktionen nedan tar svaret från GetShipAdvise och returnerar det förväntade objektet.

Observera: CustomFields kan innehålla vilket anpassat värde som helst som du också kan behöva returnera med produkterna.

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 hanterar filtreringen av produkter.

Attributet carriervalidation på CSR-noden talar om för motorn om den ska använda standardvalidering för transportör.

I detta exempel är standardvalideringen avstängd och anpassad validering används direkt på produkterna, båda kan användas samtidigt om det behövs.

<?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

Detta är ett mycket grundläggande exempel som visar ETA-beräkningar för produkterna som används 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 förväntade resultatet när en adress från Danmark används.

mceclip7.png

Det förväntade resultatet när en adress från Sverige används.

mceclip8.png

 

 

Relaterade artiklar