Pixi-API-Dokumentation

Inoffiziell · von koempf24.de

Postman-Collection
General Schreiben

pixiImportAddXML

Legt ein Auftrags- oder Artikel-Import-XML im Pixi-XML-Log (`C_XMLLog`) mit Status `XIM` an und liefert den Schlüssel des neuen Log-Eintrags.

Übergibt ein Import-Dokument an den neuen Import-Mechanismus von Pixi, indem es in das XML-Log geschrieben wird.

  1. Ist ParameterXML nicht leer, ersetzt sein Inhalt XML. Ein leerer OperationType oder ein leeres XML wird als NULL behandelt.
  2. OperationType wird ohne Beachtung der Groß-/Kleinschreibung ausgewertet:
    • order ergibt den Operationstyp OrderImport
    • item ergibt den Operationstyp ItemImport
    • jeder andere Wert, auch NULL, wird abgelehnt. Der Schlüssel des Operationstyps wird aus C_OperationTypes gelesen.
  3. ChannelRef wird in C_Channels gesucht.
  4. Danach wird in dieser Reihenfolge geprüft: Kanal ist NULL, Operationstyp unbekannt, XML fehlt. Die erste fehlgeschlagene Prüfung liefert eine Zeile mit ErrorNr = 500 und ErrorMsg.
  5. Sind alle Prüfungen erfolgreich, wird das XML in C_XMLLog geschrieben, mit Source = API, Status = XIM, Benutzer API, dem ermittelten Operationstyp und dem Kanal. Der Text wird bereinigt und in den Datentyp XML konvertiert. Schlägt die Konvertierung fehl, werden der Rohtext sowie Fehlernummer und Fehlermeldung der Konvertierung gespeichert. Der Aufruf meldet das nicht als Fehler.
  6. Zurückgegeben wird der Schlüssel des neuen Log-Eintrags. Der Aufruf importiert den Auftrag oder Artikel nicht selbst. Das geschieht später in der Import-Verarbeitung, die nicht Teil dieses Aufrufs ist.

Hinweise

  • Zwei Ergebnismengen bei Erfolg: Die interne Prozedur Pixi_C_InsertXML liefert den neuen Schlüssel bereits als XMLLogKey (SqlRowSet1). Anschließend liefert der Aufruf denselben Wert noch einmal als XMLKey (SqlRowSet2). Im Fehlerfall wird nur eine Zeile (ErrorNr/ErrorMsg) in SqlRowSet1 geliefert.
  • Schwache Kanalprüfung: Existiert ChannelRef nicht in C_Channels, behält die Variable den übergebenen Wert. Der Fehler Channel not defined tritt daher nur auf, wenn ChannelRef explizit NULL ist. Ein nicht vorhandener Kanal, auch der Standardwert 0, wird ohne Fehler gespeichert.
  • Wird order oder item übergeben, fehlt aber der passende Eintrag (OrderImport/ItemImport) in C_OperationTypes, bleibt der Operationstyp NULL. Der Eintrag wird dann ohne Operationstyp gespeichert statt abgelehnt.
  • Ungültiges XML wird nicht abgelehnt. Eine fehlgeschlagene XML-Konvertierung wird nur in den Log-Spalten XmlResponseCastErrorNr/XmlResponseCastErrorMessage festgehalten. Das XML sollte vor dem Senden geprüft werden.
  • Das XML wird durch fPixi_CleanupXmlText bereinigt. Die Definition dieser Funktion liegt nicht vor.
  • Es wird keine explizite Transaktion verwendet. Die Abfragen auf C_OperationTypes und C_Channels nutzen NOLOCK.
  • Das XML-Dokument muss im SOAP-Element maskiert (oder als CDATA) übergeben werden, da der Parameter ein varchar(max)-String ist.

Parameter

Parameter Typ Standardwert Beschreibung
ChannelRef
int 0

Schlüssel des Kanals (C_Channels.ChannelKey), zu dem der Import gehört. Nur ein explizites NULL wird abgelehnt; unbekannte Schlüssel werden unverändert gespeichert.

Beispiel: 1
OperationType
varchar(20)
string		 NULL

Art des Imports, ohne Beachtung der Groß-/Kleinschreibung. Jeder Wert außer ORDER oder ITEM führt zu einem Fehler.

Erlaubte Werte

  • ORDER – Auftragsimport (Operationstyp `OrderImport`).
  • ITEM – Artikelimport (Operationstyp `ItemImport`).

Beispiel: ORDER
XML
varchar(max)
xml		 NULL

Das Import-Dokument als Text, z. B. ein Auftrag oder ein BMEcat-Artikeldokument. Es wird ignoriert, wenn ParameterXML gefüllt ist. Ist es leer oder fehlt es, liefert der Aufruf einen Fehler.

Beispiel:

<ORDER version="1.0" type="standard">
  <ORDER_HEADER>
    <ORDER_INFO>
      <ORDER_ID>100045</ORDER_ID>
      <ORDER_DATE>2024-03-15T10:22:00</ORDER_DATE>
    </ORDER_INFO>
  </ORDER_HEADER>
  <ORDER_ITEM_LIST>
    <ORDER_ITEM>
      <LINE_ITEM_ID>1</LINE_ITEM_ID>
      <ARTICLE_ID>
        <SUPPLIER_AID>4711</SUPPLIER_AID>
      </ARTICLE_ID>
      <QUANTITY>2</QUANTITY>
    </ORDER_ITEM>
  </ORDER_ITEM_LIST>
</ORDER>
ParameterXML
varchar(max)
xml		 NULL

Alternative zu XML. Ist der Wert nicht leer, ersetzt er den Inhalt von XML.

Beispiel:

<BMECAT version="2005">
  <HEADER>
    <CATALOG>
      <LANGUAGE>deu</LANGUAGE>
      <CATALOG_ID>SHOP1</CATALOG_ID>
      <CATALOG_VERSION>1.0</CATALOG_VERSION>
    </CATALOG>
  </HEADER>
  <T_NEW_CATALOG>
    <PRODUCT>
      <SUPPLIER_PID>4711</SUPPLIER_PID>
      <PRODUCT_DETAILS>
        <DESCRIPTION_SHORT>Beispielartikel</DESCRIPTION_SHORT>
      </PRODUCT_DETAILS>
    </PRODUCT>
  </T_NEW_CATALOG>
</BMECAT>

Antwort

Result-Set 1 · Bei Erfolg (erste Ergebnismenge, geliefert von der internen Prozedur Pixi_C_InsertXML)

Schlüssel des neuen Eintrags in C_XMLLog.

Spalte Typ Beschreibung
XMLLogKey
Kann leer sein
 int

Identity-Wert des neuen XML-Log-Eintrags.

Result-Set 2 · Bei Erfolg (zweite Ergebnismenge)

Derselbe Schlüssel noch einmal, geliefert vom Aufruf selbst.

Spalte Typ Beschreibung
XMLKey
Kann leer sein
 int

Schlüssel des neuen XML-Log-Eintrags (Rückgabewert von Pixi_C_InsertXML).

Result-Set 3 · Anstelle der Erfolgs-Ergebnismengen, wenn eine Prüfung fehlschlägt oder beim Speichern ein Fehler auftritt

Einzelne Fehlerzeile.

Spalte Typ Beschreibung
ErrorNr
Kann leer sein
 int

500 bei Prüfungsfehlern, sonst die SQL-Fehlernummer.
ErrorMsg
Kann leer sein
 nvarchar(4000)
string

Fehlertext.

Beispielantwort

<SqlRowSet1>
  <row>
    <XMLLogKey>58231</XMLLogKey>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status Meldung Ursache
500 Channel not defined `ChannelRef` wurde als `NULL` übergeben. Einen gültigen Kanalschlüssel übergeben.
500 Operation type not found. Please use either ITEM or ORDER `OperationType` fehlt, ist leer oder weder `ITEM` noch `ORDER`.
500 XML was not set Sowohl `XML` als auch `ParameterXML` sind leer oder fehlen.
{ERROR_NUMBER} {ERROR_MESSAGE} Beim Schreiben des XML-Log-Eintrags ist ein unerwarteter SQL-Fehler aufgetreten. Eine fehlgeschlagene XML-Konvertierung löst diesen Fehler nicht aus.

Beispiele

POST https://apigateway.descartes.com/tms/pixi/
Content-Type: text/xml; charset=utf-8
Authorization: Basic BASE64(USERNAME:PASSWORD)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiImportAddXML>
      <!-- <ChannelRef>1</ChannelRef> -->
      <!-- <OperationType>ORDER</OperationType> -->
      <!-- <XML><![CDATA[<?xml version="1.0" encoding="UTF-8"?><ORDER version="1.0" type="standard"><ORDER_HEADER><ORDER_INFO><ORDER_ID>100045</ORDER_ID><ORDER_DATE>2024-03-15T10:22:00</ORDER_DATE></ORDER_INFO></ORDER_HEADER><ORDER_ITEM_LIST><ORDER_ITEM><LINE_ITEM_ID>1</LINE_ITEM_ID><ARTICLE_ID><SUPPLIER_AID>4711</SUPPLIER_AID></ARTICLE_ID><QUANTITY>2</QUANTITY></ORDER_ITEM></ORDER_ITEM_LIST></ORDER>]]></XML> -->
      <!-- <ParameterXML><![CDATA[<?xml version="1.0" encoding="UTF-8"?><BMECAT version="2005"><HEADER><CATALOG><LANGUAGE>deu</LANGUAGE><CATALOG_ID>SHOP1</CATALOG_ID><CATALOG_VERSION>1.0</CATALOG_VERSION></CATALOG></HEADER><T_NEW_CATALOG><PRODUCT><SUPPLIER_PID>4711</SUPPLIER_PID><PRODUCT_DETAILS><DESCRIPTION_SHORT>Beispielartikel</DESCRIPTION_SHORT></PRODUCT_DETAILS></PRODUCT></T_NEW_CATALOG></BMECAT>]]></ParameterXML> -->
    </ns1:pixiImportAddXML>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Verwendete Tabellen

C_OperationTypes · Lesen C_Channels · Lesen C_XMLLog · Schreiben
SQL-Objekt:
dbo.pipiImportAddXML
Prozedur zuletzt geändert am 2026-10-05
Dokumentation von claude-opus-5-5 am 2026-10-30 geschrieben