2BA Deeplink Gebruiksbeschrijving
Document versie: Uitgiftedatum: Status: Auteur:
1.0 SCVN 02 2006-5-1 Conceptueel 2BA
2BA Deeplink / Gebruiksbeschrijving
Inhoudsopgave Inhoudsopgave ...................................................................................................................................... 2 1
Wat is deeplink? ............................................................................................................................ 3
2
Deeplink gebruiken ....................................................................................................................... 4 2.1 2.2 2.3
3
Verwerken van een deeplink URL................................................................................................ 5 3.1 3.2 3.3
4
Deeplinken via een URL.......................................................................................................... 4 Deeplinken via webservice ...................................................................................................... 4 Schematische weergave ......................................................................................................... 4 Binnenkomende deeplink aanvraag ........................................................................................ 5 Relatie is onbekend binnen deeplink tabel.............................................................................. 5 Relatie is bekend binnen de deeplink tabel............................................................................. 5
Zelf deeplink faciliteit bieden ....................................................................................................... 6 4.1 4.2 4.3 4.4
Benodigdheden........................................................................................................................ 6 Deeplink via de standaard (Instalnet Deeplink) methode........................................................ 6 Deeplink via eigen parameters ................................................................................................ 6 Deeplink via 2BA DATA........................................................................................................... 7
http://www.2ba.nl/
Pagina 2 van 7
2BA Deeplink / Gebruiksbeschrijving
1
Wat is deeplink?
Deeplinken is een manier om via een gestandaardiseerde manier te linken naar (extra) informatie over een bepaald product of artikel. Het is bijvoorbeeld mogelijk om bij een bepaald artikel door te verwijzen naar de website van de leverancier om zo extra informatie op te vragen. 2BA maakt zelf ook gebruik van de deeplink om te verwijzen naar de product/artikelinformatie van de betreffende producenten / leveranciers die deeplink aanbieden. Wanneer klanten geïnteresseerd zijn in de afname van een bepaald artikel gevonden via de 2BA website, is het mogelijk dat deze er meer informatie over wil hebben. Het is mogelijk om via de website van de leverancier opnieuw te gaan zoeken op hetzelfde artikel, maar het zou handiger zijn om direct naar de pagina te gaan waar de informatie staat. Door gebruik te maken van het zogenaamde deeplinken is dit proces te vergemakkelijken. Een klant krijgt per artikel of product een snelkoppeling (hyperlink) te zien welke doorverwijst naar de informatie die een klant zoekt. De deeplink methode van 2BA is universeel voor alle aangesloten partijen benaderbaar via de volgende snelkoppeling: http://www.2BA.nl/deeplink.aspx?FROM=###&TO=###&ID=###&IDQ=### Met de 2BA deeplink methode is het ook mogelijk om te linken naar partijen (zoals bijvoorbeeld 2BA1) die meerdere leveranciers in het artikelbestand hebben. Om naar deze partij binnen een CAB (centraal artikel bestand) te verwijzen is de parameter GLN_IN_CAT te gebruiken: http://www.2BA.nl/deeplink.aspx?FROM=###&TO=###&ID=###&IDQ=###&GLN_IN_CAT=### Er zijn geen kosten verbonden aan het gebruik van deeplink
1
Om de juiste pagina binnen 2BA te bereiken na een deeplink, dient u ingelogd te zijn. Bij deeplink naar andere partijen hangt dit af van de betreffende partij.
http://www.2ba.nl/
Pagina 3 van 7
2BA Deeplink / Gebruiksbeschrijving
2
Deeplink gebruiken
Om Deeplink mogelijk te maken zijn er meerde methodes bedacht. Deeplink gebruiken kan op 2 manieren. De webservice voor het deeplinken is gebaseerd op de Instalnet Deeplink standaard.
2.1
Deeplinken via een URL
Waaneer de deeplink URL van 2BA (http://www.2BA.nl/deeplink.aspx) aangeroepen wordt met voldoende parameters zal de deeplink plaats vinden. De parameters die meegegeven moeten worden zijn onder andere de Afzender, de Doelpartij en het betreffende item waarnaartoe gelinkt moet worden. Een deeplink via 2BA is altijd van het formaat: http://www.2BA.nl/deeplink.aspx?FROM=###&TO=###&ID=###&IDQ=### From = afzender / doorlinker (GLN van adrescode afzender) To = geadresseerde / destination (GLN van geadresseerde) GLN_IN_CAT = Leverende partij wanneer geadresseerde een centraal artikelbestand is of meerdere partijeen omvat (GLN van leverende partij) ID = Artikel identificatie IDQ = ID qualifier (één van onderstaande opties) - EN = EAN-artikelcode (van het product of artikel) - SA = Artikelcode leverancier - MF = Productcode fabrikant Bijvoorbeeld: http://www.2BA.nl/deeplink.aspx?From=8711389000001&To=8713386741048&ID=8711500559494&I DQ=EN Na ontvangen van deze URL zoekt het systeem de bijbehorende URL op die voor het betreffende artikel van die partij bekend is bij 2BA. Een voorwaarde voor het doorverwijzen is dat de ontvangende partij (TO) geregistreerd is als deeplink aanbieder bij 2BA (zie hoofdstuk 4 over deeplink aanbieden). Reeds geregistreerde partijen zijn te vinden op 2BA in het menu “extra diensten”.
2.2
Deeplinken via webservice
De feitelijke werking van het deeplinken via een URL verloopt via de webservice die aangeroepen wordt na het klikken. Eventueel is het ook mogelijk om deze webservice direct aan te roepen. 2BA
deeplink
WebService http://ws.2ba.nl/DeeplinkService.asmx
Http://www.2ba.nl/ deeplink.aspx Redirect naar URL
Webpagina van groothandel
http://www.2ba.nl/
SOAP WSDL getDeeplink(FROM, TO, Article. Qualifier)
Voor meer informatie over het direct aanroepen van de “DeeplinkServices” webservice heeft 2BA het document “2BA Webservices – Technische beschrijving” ontwikkeld. Dit document bevat alle gegevens die nodig zijn om van deze (openbare) dienst gebruik te maken.
2.3
Schematische weergave
In de afbeelding hiernaast is de samenhang te zien tussen het deeplinken via een URL of een webservice
Calculatiesoftware van installateur
Pagina 4 van 7
2BA Deeplink / Gebruiksbeschrijving
3
Verwerken van een deeplink URL
Iedere deeplink via 2BA wordt via een vaste methode verwerkt. Op deze manier maakt het voor de gebruiker niet uit welke deeplinkmethode door de aaleverende partij wordt gebruikt.
3.1
Binnenkomende deeplink aanvraag
Wanneer er een deeplink aanvraag ontvangen wordt, worden de meegestuurde parameters uitgelezen. Binnen de deeplink registratie database wordt de partij genoemd in de “TO” parameter van de aanvraag opgezocht.
3.2
Relatie is onbekend binnen deeplink tabel
Wanneer een relatie die aangegeven is in de TO parameter van de aanvraag niet gemeld wordt in de deeplink database is er geen koppeling mogelijk. De URL die teruggeven wordt zal verwijzen naar een website die aangeeft dat er een probleem is opgetreden tijdens het deeplinken.
3.3
Relatie is bekend binnen de deeplink tabel
Voor iedere relatie die voorkomt is een basislink bekend (die eventueel leeg is) waarmee de uiteindelijke URL samengesteld wordt. De URL die hier opgegeven moet worden hangt af van de deeplink methode die door de leverancier gebruikt wordt. 2BA ondersteund 3 deeplink technieken, die alledrie net anders werken. Hoofdstuk 4 geeft meer informatie over de werking van de deeplink methodes.
http://www.2ba.nl/
Pagina 5 van 7
2BA Deeplink / Gebruiksbeschrijving
4
Zelf deeplink faciliteit bieden
Om gebruik te kunnen maken van de voordelen van deeplink zijn er een aantal zaken nodig. In dit hoofdstuk wordt beschreven welke keuze gemaakt moet worden en welke voorbereiding getroffen dienen te worden.
4.1
Benodigdheden
Leveranciers die de gebruik willen maken van de deeplink faciliteiten van 2BA dienen lid te zijn van 2BA en het 2BA Logoproduct af te nemen. Tarieven kunt u terugvinden op de website van 2BA. Op uw website van de relatie waar naartoe gedeeplinkt wordt, dienen faciliteiten aanwezig te zijn zodat de gebruiker ook op de plaats komt waar deze naartoe wil. De locatie waarnaar een gebruiker doorgestuurd wordt is voor een groot deel zelf te kiezen. Voor het activeren van de deeplink functionaliteit dient eerst een keuze gemaakt te worden tussen “Instalnet Deeplink”, “Deeplink via eigen parameters” of “Deeplink via 2BA data”. De eerste twee methodes bieden als voordeel dat: - De link sneller opgehaald kan worden - De link makkelijker aangepast kan worden - De link niet afhankelijk is van gegevens binnen de 2BA database De technische werking van deze deeplink methodes heeft alleen gevolg voor hoe de website van ontvangende partij (de partij waar naartoe gedeeplinkt wordt) aangeroepen wordt. De gebruikte voorbeelden zijn fictief.
4.2
Deeplink via de standaard (Instalnet Deeplink) methode
Deeplink: http://www.2BA.nl/deeplink.aspx?FROM=8714252005929&TO=8712515922594&ID=1822&IDQ=MF Basislink: http://products.mijnbedrijf.nl/catalogus/kw1/productdescription.php? Wordt omgezet naar: http://products.mijnbedrijf.nl/catalogus/kw1/productdescription.php?FROM=8714252005929&ID=1822 &IDQ=MF Met de Instalnet deeplink methode hoeft er geen deeplink aangegeven te worden per artikel of product, maar wordt er aan de hand van 1 deeplink URL per artikel/product een link opgebouwd volgens een vast formaat. Het principe dit het doorlink mechanisme gaat uit van het gebruik van de volgende identificerende codes binnen de branche: -
de GLN voor identificatie van afzender en geadresseerde; de EAN-code van het product of de eigen productcode van de fabrikant; de EAN-artikelcode van het artikel of de eigen artikelcode van de leverancier.
De website van de ontvangende partij moet dus om kunnen gaan met de parameters “FROM”, “ID” en “IDQ” die de Instalnet Deeplink methode biedt. De parameters die doorgeven worden, zijn dus identiek aan die van de binnengekomen deeplink aanvraag. Zie voor een beschrijving van deze parameters hoofdstuk 2.1 “Deeplinken via een URL”.
4.3
Deeplink via eigen parameters
Deeplink: http://www.2BA.nl/deeplink.aspx?FROM=8714252005929&TO=8712515922594&ID=1822&IDQ=MF Basislink: http://products.mijnbedrijf.nl/catalogus/kw1/productdescription.php?productcode=%%productcode%% &referrer=%%FROM%%
http://www.2ba.nl/
Pagina 6 van 7
2BA Deeplink / Gebruiksbeschrijving Wordt omgezet naar: http://products.mijnbedrijf.nl/catalogus/kw1/productdescription.php?productcode=1822&referrer=8714 252005929 Wanneer 2BA in de deeplink tabel een basislink vindt wordt er gecontroleerd of er in deze link dubbele procent symbolen (“%%”) voorkomen. Wanneer dit het geval is betekent dit dat er in de basislink op bepaalde plekken een code geplakt moet worden uit de deeplink aanvraag. Bij het samenstellen van de basislink zijn de volgende codes te gebruiken: Code %%productcode%% %%artikelcode%% %%eancode%% %%SAandorMF%% %%FROM%% %%TO%% %%ID%% %%IDQ%%
4.4
Wordt vervangen met De waarde uit ID (alleen wanneer IDQ “MF” aangeeft) De waarde uit ID (alleen wanneer IDQ “SA” aangeeft) De waarde uit ID (alleen wanneer IDQ “EN” aangeeft) De waarde uit ID (alleen wanneer IDQ “MF” of “SA” aangeeft) De waarde uit FROM De waarde uit TO De waarde uit ID De waarde uit IDQ (“MF”, “SA” of “EN”)
Deeplink via 2BA DATA
Deeplink: http://www.2BA.nl/deeplink.aspx?FROM=8714252005929&TO=8712515922594&ID=1822&IDQ=MF Basislink: {geen} Wordt omgezet naar: http://products.mijnbedrijf.nl/catalogus/kw1/productdescription.php?id=1822 Deze methode houdt in dat er voor ieder artikel en product waarvoor gedeeplinkt moet kunnen worden een eigen link opgegeven moet worden. Voor het gebruik van deze methode dient de data van een aanleverende partij gespecificeerd te worden via het PAB 2 of XML v005 formaat. Daarnaast hoeft er geen basislink aangegeven te worden bij 2BA. Een nadeel van deze methode is dat er een grote overhead is aan gegevens. Omdat er voor iedere link een complete URL opgegeven moet worden staat hier in veel gevallen links die bijna niet van elkaar verschillen, bijvoorbeeld: http://products.mijnbedrijf.nl/catalogus/kw1/productdescription.php?id=1822 http://products.mijnbedrijf.nl/catalogus/kw1/productdescription.php?id=1823 http://products.mijnbedrijf.nl/catalogus/kw1/productdescription.php?id=1824 enz. Deze methode is vooral handig voor partijen met maar een klein aantal producten / artikelen. Een URL mag via deze methode nooit langer zijn den 512 karakters. Wanneer een deeplink request binnenkomt wordt er opgezocht welke deeplink er voor dat betreffende artikel of product (Aangegeven middels de parameters “ID” en “IDQ”) in de 2BA database staat. De link die teruggegeven wordt (bij deeplink via webservices) of waar naartoe iemand doorgestuurd wordt (bij deeplink via URL) is de totale tekst uit het deeplink veld. Bij deze methode zoekt 2BA dus feitelijk de juiste URL op per product of artikel.
http://www.2ba.nl/
Pagina 7 van 7
