Spendint API - POST /sn_spend_intg/spendint/catalog
Ermöglicht Lieferanten, mehrere Kataloge zum Erstellen von Lieferantenprodukten, Modellprodukten, Verträgen und Preisdatensätzen zu veröffentlichen.
Wenn Sie in der Integration der Katalog-API Daten aus dem Katalog einer Drittpartei erhalten, können Sie folgende Schritte ausführen:
- Erstellen Sie neue Drittpartei-Kategorien und ordnen Sie diese Kategorien Modellkategorien zu.
- Wenn verfügbar, verwenden Sie den United Nations Standard Products and Services Code (UNSPSC) und dann den Kategorienamen.
- Wenn der UNSPSC nicht verfügbar ist, verwenden Sie nur den Kategorienamen.
- Nachdem Sie einer Modellkategorie eine Drittpartei-Kategorie zugeordnet haben, verwenden Sie die Teilenummer des Herstellers (Manufacturer Part Number, MPN) für die Suche nach einem vorhandenen Produktmodell, sofern eines verfügbar ist.
- Wenn ein Produktmodell für die MPN gefunden wird, aktualisieren Sie das Produktmodell mit allen Änderungen und erstellen oder aktualisieren anschließend alle Lieferantenprodukte, die sich auf das Produktmodell beziehen.
- Wenn für die MPN kein Produktmodell vorhanden ist, gehen Sie folgendermaßen vor:
- Eine Produktmodellklasse ist normalerweise für die Modellkategorie verfügbar, auf die die Drittpartei-Kategorie für das Produkt verweist. Verwenden Sie diese Produktmodellklasse, um die Produktmodelltabelle abzurufen, in der das Produktmodell erstellt werden soll, z. B. Hardware, Software, Verbrauchsmaterialien usw. Wenn keine Produktmodellklasse verfügbar ist, erstellen Sie das Produktmodell in der Produktmodell-Basistabelle.
- Nachdem Sie die richtige Produktmodellklasse ermittelt haben, erstellen Sie folgendermaßen ein neues Produktmodell in der richtigen Klasse:
- Hersteller, Herausgeber oder Anbieter sind dem Hersteller im Produktmodell zuzuordnen.
- Der Produktname aus der API muss dem Namen im Produktmodell zugeordnet werden.
- Die MPN aus der API muss die Modellnummer aktualisieren.
- Die Produktbeschreibung aus der API muss die Beschreibung im Produktmodell aktualisieren.
- Die Modellkategorie muss mit der Produktkategorie aktualisiert werden, auf die im Datensatz der Drittpartei-Kategorie verwiesen wird.
- Die Produktkategorie muss mit der Produktkategorie aktualisiert werden, auf die im Datensatz der Drittpartei-Kategorie verwiesen wird.
- Wenn die Ersatzprodukte in der API Werte enthalten, erstellen Sie die Ersatzproduktdatensätze zwischen dem aktuellen Produktmodell und den anderen Produktmodellen.
- Wenn die kompatiblen Produkte in der API Werte enthalten, erstellen Sie die Datensätze der kompatiblen Produkte zwischen dem aktuellen Produktmodell und den anderen Produktmodellen.
- Produktattribute aus der API müssen in der zugehörigen Liste der Produktattribute für das Produktmodell erstellt oder aktualisiert werden.
- Wenn ein Produktmodell verfügbar ist, verwenden Sie die Teilenummer des Lieferanten, um die Lieferantenprodukte zu erstellen oder zu aktualisieren, die sich auf das Produktmodell beziehen.
Drittpartei-Zuordnung
Verwenden Sie die folgenden Tabellen für die Zuordnungen von Drittpartei-Kategorien, Modellen und Einheiten:
- Drittpartei-Kategorien: Speichert alle Datensätze der Drittpartei-Kategorien für den ShoppingHub-Administrator, um sie den vorhandenen internen Modellkategorien zuzuordnen.
- Drittpartei/Modell-Zuordnungen: Speichert alle Informationen zu Zuordnungen zwischen Produktmodellen und Drittpartei-Modellkategorien.
- Drittpartei-Einheiten: Speichert alle Datensätze von Drittpartei-Einheiten, die der ShoppingHub-Administrator den Produkteinheiten des Lieferanten zuordnen soll.
- Drittpartei/Einheit-Zuordnungen: Speichert alle Informationen zu Zuordnungen zwischen Produktmodellen und Drittpartei-Einheiten.
Hinweis:
Das Produkt einer Drittpartei-Integration wird automatisch veröffentlicht, wenn sowohl die Drittpartei-Kategorie als auch die Drittpartei-Einheit entsprechend zugeordnet wurden.
Verkaufsdaten des Lieferantenprodukts
Ein Lieferantenprodukt wird eingestellt und nicht mehr im Katalog veröffentlicht, wenn es sein Enddatum für den Verkauf erreicht hat. Die Felder Startdatum für Verkauf und Enddatum für Verkauf im Formular „Lieferantenprodukt“ werden durch die Drittpartei-Integration aus der Katalog-API ausgefüllt.
Statustabellen
Um den Status der Anforderung für den Massenimport eines Produkts zu erfahren, führen Sie mithilfe der Tabelle „REST-APIs“ einen REST-Aufruf in der ServiceNow-Datenbank durch. Die Antwort der API listet die Datensätze auf, bei denen die Massenimportanforderung fehlgeschlagen ist. Um die Antwort auf den Massenimport eines Produkts zu erhalten, fragen Sie die Tabelle „Katalogfehler“ mit dem folgenden Parameter ab:
sysparm_query=outbound_error.supplier_id=<supplier_id>^outbound_error.state=20
Detailinformationen zu Kunden-ID, Lieferanten-ID, Fehlertyp, eindeutiger Import Set-ID und Status finden Sie in der Tabelle „Ausgehender Status“, der übergeordneten Fehlertabelle.
URL-Format
/api/sn_spend_intg/spendint/catalog
Unterstützte Anforderungsparameter
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| Modus | Unterstützung des asynchronen und des synchronen Modus für die Drittanbieterintegration. Datentyp: Zeichenfolge Gültige Werte:
Standard: async |
| Name | Beschreibung |
|---|---|
| customer_id | Bezeichner für den Kunden. Datentyp: Zeichenfolge Maximale Länge: 100 |
| catalog_id | Bezeichner für den Kataloginhalt, der von einem Kunden erworben werden kann. Datentyp: Zeichenfolge Maximale Länge: 100 |
| products | Liste der Objekte, die Produkte zu erstellende oder zu aktualisierende Produkte definieren. Jede Transaktion hat ein Limit von 1.000 Produkten. Datentyp: Array |
| products.available_units | Erforderlich für Produkte, die auf Lager gehalten werden. Dieser Wert gibt die Anzahl der Einheiten an, die für dieses Produkt verfügbar sind. Datentyp: Zeichenfolge Maximale Länge: 40 |
| products.available_for_country | Liste mit den Codes der Länder, in denen das Lieferantenprodukt erworben werden kann. Wenn kein Land angegeben ist, kann das Produkt von Benutzern aus beliebigen Ländern erworben werden. Datentyp: Array |
| products.bundled_components | Gilt nur für Szenarien, in denen ein Produktpaket als Teil der Katalognutzlast gesendet wird, und gilt nur für die Nutzlasten des übergeordneten Pakets. Dieser Wert enthält den Verweis auf die untergeordneten Paketkomponenten. Hier werden die Liste der Herstellerteilenummern und die Mengen für die untergeordneten Paketkomponenten verwaltet. Hinweis: Die untergeordneten Paketkomponenten und ihre Details (Herstellerteilenummern und Mengen) sind demselben Lieferanten zuzuordnen.Da dieselbe untergeordnete Paketkomponente innerhalb eines Pakets mehrmals hinzugefügt werden kann, ist die eingegebene Menge das Unterscheidungsmerkmal zwischen identischen untergeordneten Paketkomponenten. Datentyp: Array |
| products.contract_agreement | Details des Vertrags für ein Produkt. Hinweis:
Dies ist für untergeordnete Paketkomponenten nicht erforderlich. Datentyp: Objekt |
| products.contract_agreement.contract_end_date | Datum, an dem die Vertragslaufzeit endet. Datentyp: Zeichenfolge Maximale Länge: 40 Format: JJJJ-MM-TT |
| products.contract_agreement.contract_number | Erforderlich. Nummer des aktiven Vertrags, der dem Produkt zugeordnet ist. Datentyp: Zeichenfolge Maximale Länge: 100 |
| products.contract_agreement.contract_start_date | Datum, an dem die Vertragslaufzeit beginnt. Datentyp: Zeichenfolge Maximale Länge: 40 Format: JJJJ-MM-TT |
| products.contract_agreement.negotiated_currency | Erforderlich. Währung des ausgehandelten Preises. Datentyp: Zeichenfolge Maximale Länge: 40 |
| products.contract_agreement.negotiated_price | Erforderlich. Stückpreis eines Produkts, wie vertraglich mit dem Lieferanten oder Reseller ausgehandelt. Datentyp: Zeichenfolge Maximale Länge: 40 |
| products.delivery_time | Geschätzte Anzahl der Tage, die der Versand eines Produkts an einen Kunden dauert. Dieser Wert muss der Anzahl an Tagen entsprechen und eine ganze Zahl sein. Datentyp: Zeichenfolge Maximale Länge: 40 |
| products.images | Liste der Zeichenfolgen, die die Bild-URLs für das Lieferantenprodukt angeben. Datentyp: Array |
| products.manufacturer | Erforderlich. Unternehmen, das das Produkt herstellt, veröffentlicht oder bereitstellt. Dies ist nicht der Lieferant oder Reseller des Produkts. Datentyp: Zeichenfolge Maximale Länge: 100 |
| products.mpn | Erforderlich. Bezeichner für ein Produkt, der vom Hersteller, Herausgeber oder Anbieter bereitgestellt wird. Hinweis:
Dies ist für übergeordnete Reseller-Pakete nicht erforderlich, wenn der SKU-Wert verfügbar ist. Datentyp: Zeichenfolge Maximale Länge: 100 |
| products.parent_bundle | Gilt nur für Szenarien, in denen ein Produktpaket als Teil der Katalognutzlast gesendet wird, und gilt nur für die Nutzlasten der untergeordneten Paketkomponente. Bei einer untergeordneten Paketkomponente wird hier der Verweis auf das übergeordnete Element beibehalten. Der übergeordnete MPN- und der übergeordnete SKU-Wert werden hier ebenfalls festgelegt. Datentyp: Zeichenfolge Maximale Länge: 100 |
| products.product_attributes | Liste der Schlüssel/Wert-Paare, die Produktattribute definieren, z. B. „Farbe“: „Space Grey“. Für jedes Produkt sind jeweils mehrere Attribute zulässig. Über die API sollten jedoch nur die Attribute bereitgestellt werden, die sich auf die Preisgestaltung oder die Lagerverfügbarkeit auswirken.Datentyp: Objekt |
| products.product_category_name | Erforderlich. Name, den Sie eingeben, wenn Sie die Eigenschaft unspsc nicht festlegen. Dieser Name entspricht der Kategorie, zu der ein Produkt gehört. Dieser Kategoriename kann in einem Commerce-Szenario verwendet werden, um das Produkt zu kaufen. Zum Beispiel könnte das Produkt „Steckdosenleiste“ zu einer Kategorie „Büroausstattung“ gehören. Datentyp: Zeichenfolge Maximale Länge: 100 |
| products.product_description | Vollständige Beschreibung des Produkts, die dem Käufer in einer Einkaufs-Experience angezeigt wird. Hinweis:
Der Lieferant sollte das Produkt hier so genau wie möglich beschreiben, insbesondere, wenn es sich bei den Katalogelementen um Produktpakete handelt, für die untergeordnete Paketkomponenten verfügbar sind. Datentyp: Zeichenfolge Maximale Länge: 65.000 |
| products.product_name | Erforderlich. Name des Produkts. Datentyp: Zeichenfolge Maximale Länge: 1.000 |
| products.sku | Erforderlich. Nummer, die von einem Lieferanten generiert wird und ein Produkt eindeutig identifiziert, das von diesem Lieferanten verkauft wird. Datentyp: Zeichenfolge Maximale Länge: 100 |
| products.unit | Erforderlich. Einheit oder Tarif für den Verkauf dieses Produktes durch den Lieferanten. Beispiele: Stücke, Stunden usw. Datentyp: Zeichenfolge Maximale Länge: 40 |
| products.unspsc | Erforderlich. Bezeichner, den Sie eingeben, wenn Sie die Eigenschaft product_category_name nicht festlegen. Dieser Bezeichner entspricht dem UNSPSC für die Kategorie, zu der ein Produkt gehört. Zum Beispiel ist der UNSPSC-Code 43210000 der Bezeichner für die Produktkategorie „Computer“. Datentyp: Zeichenfolge Maximale Länge: 100 |
| supplier_id | Erforderlich. Bezeichner für den Reseller oder Lieferanten, bei dem der Kunde Bestellungen aufgeben kann. Datentyp: Zeichenfolge Maximale Länge: 100 |
| third_party_import_id | Bezeichner, der es einer Drittpartei ermöglicht, einen Zeichenfolgenwert zu übergeben, um einen Satz importierter Daten eindeutig zu identifizieren. Datentyp: Zeichenfolge Maximale Länge: 100 |
Header
Die folgenden Anforderungs- und Antwort-Header gelten nur für diese HTTP-Aktion oder sie gelten für diese Aktion auf besondere Weise.
| Kopfzeile | Beschreibung |
|---|---|
| Akzeptieren | Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json |
Hinweis:
Für Procurement Integration Framework wird nur das Datenformat application/json unterstützt.
| Kopfzeile | Beschreibung |
|---|---|
| Keine |
Statuscodes
Die folgenden Statuscodes gelten für diese HTTP-Aktion.
| Statuscode | Beschreibung |
|---|---|
| Erfolg | Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet. |
| Fehler | Nicht erfolgreich. Die Anforderung wurde mit Fehlern verarbeitet. |
Parameter des Antwort-Haupttexts (JSON)
Diese Antworttextparameter werden bei einer Abfrage im synchronen Modus empfangen.| Name | Beschreibung |
|---|---|
| error_response_body | Beschreibung der Fehler, aufgelistet nach SKU, MPN und Fehlermeldung. Datentyp: Array |
| error_response_body.error_message | Detaillierte Fehlermeldung. Datentyp: Zeichenfolge |
| status_code | Antwortstatus wie „Erfolg“ oder „Fehler“. Datentyp: Zeichenfolge |
cURL-Anforderung
curl "https://instance.service-now.com/api/sn_spend_intg/spendint/catalog" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
{"root": [{
"customer_id": "AB-1234323",
"catalog_id": "ACME CORP-12347898",
"supplier_id": "SUP-123456",
"third_party_import_id": "DELL1234567",
"products": [
{
"product_name": "Apple MacBook Pro 13 Core i7",
"mpn": "Z0WQ-20004301931",
"sku": "55788741",
"manufacturer": "Apple",
"product_category_name": "Computer",
"parent_bundle": "920-0045362002",
"bundled_components": {
"mpn": "Z0WQ-20004301931",
"quantity": "4",
},
"unspsc": "43211500",
"product_description": "Apple MacBook Pro 13 Core i7 2.8GHz 16GB 512GB - Touch Bar - Space Gray",
"product_attributes": {
"Color": "Space Grey",
"RAM": "16GB",
"Screen Size": "13inch"
},
"images": ["http://test123.image1.png", "http://test123.image2.jpeg"],
"unit": "Each",
"available_units": "4",
"available_for_country": ["US","IN","GB"],
"delivery_time": "4",
"contract_agreement": {
"contract_number": "34567892",
"contract_start_date": "YYYY-MM-DD",
"contract_end_date": "YYYY-MM-DD",
"negotiated_price": "456",
"negotiated_currency ": "USD"
}
}
]
}
]}
Mögliche Antworten:
// Success response:
{
"result": {
"response": "success"
}
}
// Error response:
{
"result": {
"response": [
{
"customer_id": "AB-1234323",
"supplier_id": "SUP-123456",
"third_party_import_id": "DELL1234567",
"status_code": "failure",
"error_response_body": [
{
"sku": "55788741",
"mpn": "Z0WQ-20004301931",
"error_message": "Field Value empty/Formatting issue Negotiated currency \n"
}
]
}
]
}
}