Produkte Listenabrufe / Produktsuchen
Abfrage per /products/search gefolgt von Key/Value-Paaren, die den Suchfilter beschreiben.
- jeder Key darf nur einmal vorkommen
- die Reihenfolge der Key/Value-Paare ist egal
- Key und Value sind durch ein Gleichheitszeichen (‚=‘) getrennt
- Key/Value-Paare sind voneinander mit Semikolon (‚;‘) getrennt
- es gibt vordefinierte Keys, andere Einträge machen die URL ungültig
- im Value müssen HTML Request ungültige Zeichen maskiert werden, ein Leerzeichen durch den Code %20, ein Gatter (‚#‘) durch den Code ‚%23‘, ein Slash (‚/‘) durch den Code ‚%2F‘, usw.
- Hinweis: Sollte trotz Maskierung keine Produkte gefunden werden, dann müssten die % Zeichen in den maskierten Codes eventuell nochmal explizit mit %25 kodiert werden (Doppelkodierung), z.B. %2F als %252F.
- für einen Key können bis zu 50 Werte angegeben werden, die per Komma (‚,‘) voneinander getrennt werden
Suchfilter Keys
- keywords: freier Suchtext
- Leerzeichen nicht durch + ersetzen, sondern %20 z.B. eine Suche nach Lenovo Thinkpad I5 entspricht Lenovo%20Thinkpad%20I5 und nicht Lenovo+Thinkpad+I5
- ean: eine Produkt-EAN
- puid: ITscope-ID
- plzid: Bezugsquellennummer
- pid: interne ITscope-ID
- cnetid: 1WorldSync-Produktnummer (ehemals CNET)
- hstpid: Herstellernummer, SKU (sollte zusammen mit manufacturer benutzt werden oder mit keywords , um darüber den Herstellernamen einzuschränken)
- distpid: Produktnummer des Distributors
- id: wird als eine der internen ITscope-IDs interpretiert, mit Rückfalloption auf puid
- manufacturer (MAN): eindeutige Kennung des Hersteller
- producttype (SET): eindeutige Kennung der Produktkategorie
- distributor (PRL): eindeutige Kennung des Lieferanten
- cluster (CLU): eindeutige Kennung des Eigenschafts-Cluster
Die resultierende Liste kann leer sein, genau ein Produkt enthalten oder mehrere bis zu 50.
Query Parameter page
Mit dem Parameter page ist es möglich bei einem Suchergebnis > 50 Produkte, die nächsten 50 Produkte anzufragen.
z.B: page=3, bedeutet zeige mir die Produkte 101 bis 150.
https://api.itscope.com/2.1/products/search/hstpid=MZ-75E250B%252FEU;manufacturer=1015/standard.xml?page=3
Es gibt im Vorfeld in der ersten Anfrage keine Aussage darüber, wie viele Produkte gefunden wurden, d.h. es muss so lange mit page=xx gearbeitet werden, bis es keine Produkte mehr gibt, um das Ende der Liste zu erreichen.
Query Parameter item
Mit dem Parameter item ist es möglich bei einem Suchergebnis exakt den x-ten Datensatz zu erhalten.
z.B: bei page=2, item=3, erhält man aus einer Liste von z.b. 90 Produkten, genau den 3-ten Datensatz auf der 2ten page. Bei 50 Datensätzen pro page, wäre es dann in dem Beispiel der 53 Datensatz.
Die Item Nummer kann nur zwischen 1 und 50 sein, d.h. die Item Nummer ist nicht abhängig von dem Parameter page.
Query Parameter plzproducts
Mit diesem Query Parameter können auch Preislistenzeilen Produkte gefunden und angezeigt werden. Diese Produkte haben in der ITscope Online Plattform die Endung 999. Dieser Parameter ist per Default false, also nicht gesetzt.
Query Parameter realtime
Mit diesem Query Parameter werden Realtime-Abfrage für alle Preise bei den jeweiligen Lieferanten durchgeführt. Vorraustzung für einen Realtime Abruf ist ein erfolgreich eingerichteter Realtime E-Service bei den jeweiligen Lieferanten.
Realtime-Preisabrufe können aus Lastgründen, da diese direkt an die Schnittstelle des Lieferanten weitergeleitet werden, nur für ProduktID-Abfragen mit folgenden Keys ean, puid, plzid, pid, cnetid, hstpid, distpid, id mit höchstens insgesamt 10 IDs verwendet werden.
Realtime-Preisabrufe können auch bis zu 5 Sekunden dauern, da diese direkt an die Schnittstelle des Lieferanten weitergeleitet werden und bis zu 5 Sekunden auf die Antwort des Lieferanten gewartet wird. D.h. es kann auch vorkommen, dass kein Realtime Preis geladen werden kann, wenn das Limit von 5 Sekunden überschritten ist. Dann wird der individuelle Preislisten Preis oder der Standardpreis zurückgeliefert.
Query Parameter sort
Produktsuche können nach bestimmten Kriterien sortiert werden.
Hier eine Liste der Sortierkriterien und deren Bedeutung:
- DEFAULT: nach Relevanz absteigend, ist keine Relevanz vorhanden, dann analog IRANK.
- PRICE_ASC: nach Preis aufsteigend
- PRICE_DESC: nach Preis absteigend
- SOURCES_COUNT: nach Anzahl Bezugsquellen absteigend
- STOCK: nach Lagerbestand absteigend
- MANUFAKTURER_SKU: nach Herstellerartikelnummer absteigend
- NAME_ASC: nach Produktname aufsteigend
- NAME_DESC: nach Produktname absteigend
- QUAL: nach Qualifizierung des Produkts absteigend
- TOPSELLER: nach Top Produkt Rank (Klicks letzte 4 Wochen) absteigend
- EXACT: nach exaktem ProduktId Treffer absteigend
- IRANK: nach allgemeinem Beliebtheitsrang absteigend, siehe Feld rank in Formatbeschreibungen für Produkte
Query Parameter für die Einschränkung nach Produkt-Eintragsdatum Zeitraum
Die entsprechenden Requestparameter stehen erst ab der API 2.1 zur Verfügung. Die Parameter filtern auf dem Exportfeld entryDate beim Produkt, siehe Formatbeschreibungen für Produkte . Das Eintragungsdatum gibt an, wann das Produkt in den ITscope Katalog aufgenommen wurde und nicht wann es zuletzt geändert wurde. Also ist es nicht Möglich über diese Parameter nach geänderten Produkten zu suchen.
- productEntryFrom: Der Startzeitpunkt für die Einschränkung des Produkteintragsdatum Zeitraums im Format yyyy-MM-dd. Nur wenn dieser Parameter gesetzt ist, werden die Produkte nach dem Eintragungsdatum Zeitraum gefiltert. Uhrzeit ist immer 00:00:00.
- productEntryTo: Der Endzeitpunkt für die Einschränkung des Produkteintragsdatum Zeitraums im Format yyyy-MM-dd. Wird kein Wert übermittel ist der Defaultwert das aktuelle Datum. Uhrzeit ist immer 00:00:00. Der Wert darf nicht weniger als productEntryFrom sein.
Query Parameter für historische Daten
Historische Daten und die entsprechenden Request Parameter stehen erst ab der API 2.1 zur Verfügung.
Beispiele – Massenabfragen bis 50 Stück
Suche nach einer Reihe von ITscope ProduktIds:
In diesem Beispiel werden folgende ITscope ProduktIds gesucht:3534638001, 2069677000, 2650828000, 4201083000. Es können bis zu 50 ITscope ProduktIds in einem Request angegeben werden.
Suche nach einer Reihe von EANs:
In diesem Beispiel werden folgende Eans gesucht:5032037044288, 7636490025914, 8806086522977. Es können bis zu 50 Eans in einem Request angegeben werden.
Suche nach einer Reihe von Hersteller Artikelnummern:
In diesem Beispiel werden folgende Hersteller Artikelnummern gesucht: 0553C001AA, N9J71AE#301, CLT-P406B/ELS. Es können bis zu 50 Hersteller Artikelnummern in einem Request angegeben werden.
z.B. das Zeichen # als %23 -> %2523, oder das Zeichen / als %2F -> %252F
Beispiele – Filterkombinationen
Suche nach allen Produkten, die zu einem Hersteller und dessen Herstellerartikelnummer passen:
z.B: Hersteller Samsung ( Id:1015 ermittelbar über Hersteller API Abruf) und Herstellerartikelnummer MZ-75E250B/EU
https://api.itscope.com/2.1/products/search/hstpid=MZ-75E250B%252FEU;manufacturer=1015/standard.xml
In diesem Beispiel mit der Herstellerartikelnummer „MZ-75E250B/EU“ wurde außerdem das /-Zeichen durch ‚%2F‘ maskiert, da das /-Zeichen in der URL eine besondere Bedeutung hat und nicht unmaskiert übertragen werden kann.
Suche nach allen Produkten, die zu einer Herstellerartikelnummer passen:
https://api.itscope.com/2.1/products/search/hstpid=A7E34AA%2523ABB/standard.xml
In diesem Beispiel mit der Herstellerartikelnummer A7E34AA#ABB wurde außerdem das #-Zeichen durch ‚%23‘ maskiert, da das #-Zeichen in der URL eine besondere Bedeutung hat und nicht unmaskiert übertragen werden kann.
Suche nach allen Produkten, die zu einer Kategorie, einem Hersteller und bestimmten Eigenschaftclustern passen:
https://api.itscope.com/2.1/products/search/producttype=114;manufacturer=1032;cluster=2404144;cluster=1061/standard.xml
In diesem Beispiel werden Produkte gesucht, in der Kategorie Festplatten (producttype=114), vom Hersteller Seagate (manufacturer=1032) und den Eigenschaftscluster Baugrösse 2,5″ (cluster=1061) und Speicherkapazität 4TB (cluster=2404144).
Die ITscope Ids der Hersteller kann über die Hersteller Metadaten API geladen werden.
Die ITscope Ids der Kategorie kann über die Kategorien Metadaten API geladen werden.
Die ITscope Ids der Eigenschaftscluster kann, mit der entsprechenden Berechtigung, über einen Export oder Produkt-Request geladen werden. Es werden jedoch nur die Eigenschaftscluster ausgegeben die den im Requestergebnis befindlichen Produkte entsprechen. Es gibt derzeit keine Möglichkeit per API eine komplette Liste von Eigenschaftsclustern zu erhalten.
Suche nach allen Produkten, die zu einer Kategorie, einem Hersteller und bestimmten Eintragsdatum Zeitraum passen:
https://api.itscope.com/2.1/products/search/producttype=114;manufacturer=1032/standard.xml?productEntryFrom=2019-11-01
In diesem Beispiel werden Produkte gesucht, in der Kategorie Festplatten (producttype=114), vom Hersteller Seagate (manufacturer=1032) und dem Eintragungsdatum zwischen 01.11.2019 und dem aktuellen Zeitpunkt des Requests.
https://api.itscope.com/2.1/products/search/producttype=114;manufacturer=1032/standard.xml?productEntryFrom=2019-11-01&productEntryTo=2019-12-01
In diesem Beispiel werden Produkte gesucht, in der Kategorie Festplatten (producttype=114), vom Hersteller Seagate (manufacturer=1032) und dem Eintragungsdatum zwischen 01.11.2019T00:00:00 und dem 01.12.2019T00:00:00.
Die ITscope Ids der Hersteller kann über die Hersteller Metadaten API geladen werden.
Die ITscope Ids der Kategorie kann über die Kategorien Metadaten API geladen werden.
Beispiele – Freitextsuche
Aufruf einer Freitextsuche
https://api.itscope.com/2.1/products/search/keywords=lenovo%20thinkpad%20i5/standard.xml
Im genannten Beispiel wird nach Lenovo Thinkpad I5 gesucht.
Kombinieren einer Kategoriensuche mit einer Freitextsuche
https://api.itscope.com/2.1/products/search/producttype=114;keywords=SATA-600/standard.xml
Kombinieren von Filtern liefert die Schnittmenge der Einzelfilter. Im genannten Beispiel wird nur nach Festplatten mit SATA-600 Schnittstelle gesucht