Aanmelden

Ship Help Center

Ship Advisor 2.0 verbinden met een API van derden

Avatar
Simon Schrader Springer
Bijgewerkt

Dit artikel is gericht op ontwikkelaars die de nieuwe methode GetShipAdvise willen koppelen aan een andere API.

Hoewel we in dit voorbeeld het Shopify e-commerceplatform gebruiken, zal de aanpak waarschijnlijk vergelijkbaar zijn op andere platforms.

Opmerking: Dit is alleen om een basismanier te tonen om verzoeken/antwoorden tussen de twee API's te converteren.
Je moet je eigen bedrijfslogica en foutafhandeling toepassen.

Je moet geen vragen stellen aan nShift Support over Shopify. 
Gebruik in plaats daarvan het Shopify communityforum hier.

 

Inhoud van dit artikel:

  

Vereisten 

  • De Shipment Server API
    In de API gebruiken we de methode GetShipAdvise
     

  • De Shopify Carrier Service API
    De Carrier Service API stelt Shopify-winkels in staat om aangepaste verzendmethoden te integreren. Dit gebeurt door een externe API-aanvraag naar de app te doen en de carrier/verzendbeschrijvingen en prijzen op te halen.

    Wanneer een gebruiker een checkout start, wordt er een verzoek gestuurd naar de URL waar de Carrier Service naar verwijst. Het verzoek bevat informatie over de artikelen, ontvanger & afzender.

    Voor meer informatie over de Shopify Carrier Service API, bezoek de officiële documentatie hier:
    https://help.shopify.com/en/api/reference/shipping-and-fulfillment/carrierservice

     

  • Verzendregels
    Een XML-bestand met de producten die in de winkel worden weergegeven
  • Carrier Performance
    Een XML-bestand met de berekening van de ETA voor de verschillende producten
  • Een Shopify ontwikkelwinkel
    https://www.shopify.com/partners

 

Een Carrier Service registreren in een Shopify-winkel

Maak een nieuwe private app aan.

De app moet Lees- en Schrijfrechten hebben op de sectie Verzendtarief, landen en provincies.

Gebruik de methode beschreven hier om een nieuwe service te registreren.

Het voorbeeldscript gebruikt Node.js en node-fetch om de gegevens te POSTEN naar de 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'
})

Hierna zou een nieuwe tariefprovider zichtbaar moeten zijn in de winkel.

mceclip9.png 

 

Gegevens uitwisselen tussen Shopify en Ship Advisor

Het verzoek van de Carrier Service moet worden vertaald naar een formaat dat de GetShipAdvise methode kan begrijpen. De data wordt verwacht in de vorm van een Shipment Object

Om een voorbeeld van het request-object van de Carrier API te zien, klik hier
De onderstaande voorbeeldfunctie gebruikt dit als input en retourneert een object met een Receiver, Sender & Lines.

De .filter(x => x.requires_shipping) wordt gebruikt om producten uit de Shopify-winkel te filteren die niet gemarkeerd zijn als verzendbaar. Je kunt dit deel verwijderen als je het niet nodig hebt.

Er zijn verschillende manieren om de Lines-array te construeren zodat deze overeenkomt met de inhoud van de winkelwagen.

In dit voorbeeld is het hardcoded dat elk item één pakket in de zending vertegenwoordigt.

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
}

De Shopify Carrier Service API verwacht dat het antwoord een rates object is.

De onderstaande voorbeeldfunctie neemt het antwoord van GetShipAdvise en retourneert het verwachte object.

Opmerking: De CustomFields kunnen elke aangepaste waarde bevatten die je ook met de producten wilt teruggeven.

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

De Shipping Rules zal de filtering van producten afhandelen.

Het attribuut carriervalidation op de CSR-node vertelt de engine of deze de standaard carrier-validatie moet gebruiken.

In dit voorbeeld is de standaardvalidatie uitgeschakeld en wordt er direct aangepaste validatie op de producten gebruikt, beide kunnen indien nodig tegelijk worden gebruikt.

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

Dit is een heel eenvoudig voorbeeld dat de ETA-berekeningen toont voor de producten die in de CSR-configuratie worden gebruikt.

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

Het verwachte resultaat wanneer een adres uit Denemarken wordt gebruikt.

mceclip7.png

Het verwachte resultaat wanneer een adres uit Zweden wordt gebruikt.

mceclip8.png

 

 

Verwante artikelen