Invoices Lesen

pixiGetInvoicePublicLink

Liefert einen öffentlichen Download-Link mit Ablaufdatum für das gespeicherte Dokument einer Rechnung, ermittelt über Rechnungs-ID und/oder Rechnungsnummer.

Ermittelt eine Rechnung und liefert einen öffentlichen Download-Link für das zugehörige gespeicherte Dokument.

InvoiceNr wird getrimmt. Ein leerer Wert gilt als nicht angegeben.
Mindestens einer der Parameter InvoiceId oder InvoiceNr muss angegeben sein, sonst wird eine Fehlerzeile geliefert.
Beide angegeben: Die Rechnung muss sowohl InvoiceKey = InvoiceId als auch InvoiceNr erfüllen.
- Passt keine Rechnung zu beiden Werten, existiert aber eine Rechnung mit der ID oder mit der Nummer, wird der Fehler InvoiceId and InvoiceNr do not match. geliefert.
- Existiert keine von beiden, wird Invoice Not Found. geliefert.
Nur ein Wert angegeben: Die Rechnung wird über diesen Wert gesucht. Wird keine gefunden, wird Invoice Not Found. geliefert.
Ist der Rechnung kein Dokument zugeordnet (DocumentStorageId leer), wird Document Not Found. geliefert.
Link und Ablaufdatum werden von der internen Prozedur pixi.DocumentPublicLink_Get erzeugt. Meldet diese einen Status ungleich 0, wird Failed to generate invoice download link. geliefert.
Bei Erfolg wird eine Zeile mit Rechnungs-ID, ermittelter Rechnungsnummer, Download-Link und Ablaufdatum des Links geliefert.

Hinweise

Der Link wird von pixi.DocumentPublicLink_Get erzeugt. Deren Definition liegt nicht vor, daher ist aus diesem Code nicht ersichtlich:
- das Format des Links,
- die Gültigkeitsdauer,
- ob Link-Datensätze in der Datenbank gespeichert werden.
Fehler werden als normale Zeile mit Status = Error und Message geliefert, nicht als SQL-Fehler ausgelöst. Der Rückgabewert der Prozedur ist 1 bei Fehler und 0 bei Erfolg.
Rechnungen werden mit NOLOCK gelesen; nicht festgeschriebene Daten können sichtbar sein.
Die Suche verwendet TOP (1) ohne ORDER BY. Teilen sich mehrere Rechnungen dieselbe InvoiceNr, ist die gelieferte Rechnung bei Suche nur über die Nummer zufällig. Für ein eindeutiges Ergebnis InvoiceId angeben.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`InvoiceId`	int	NULL	Interner Rechnungsschlüssel (`InvoiceKey`). Optional, wenn `InvoiceNr` angegeben ist. Sind beide angegeben, müssen sie zur selben Rechnung gehören. Beispiel: `104523`
`InvoiceNr`	varchar(20) string	NULL	Rechnungsnummer. Wird getrimmt; ein leerer Wert gilt als nicht angegeben. Optional, wenn `InvoiceId` angegeben ist. Beispiel: `RE2024-001234`

Antwort

Result-Set 1 · Bei Fehler (fehlende Parameter, Rechnung nicht gefunden, keine Übereinstimmung, kein Dokument, Link-Erzeugung fehlgeschlagen)

Statuszeile mit Fehlerbeschreibung. Es folgt keine weitere Ergebnismenge.

Spalte	Typ	Beschreibung
`Status`	varchar(5) string	Immer `Error`.
`Message`	varchar(100) string	Text der Fehlermeldung.

Result-Set 2 · Bei Erfolg

Eine Zeile mit der ermittelten Rechnung und ihrem öffentlichen Download-Link.

Spalte	Typ	Beschreibung
`InvoiceId`	int	Interner Rechnungsschlüssel (`Invoices.InvoiceKey`).
`InvoiceNr` Kann leer sein	varchar(20) string	Rechnungsnummer laut Rechnungsdatensatz.
`DownloadLink` Kann leer sein	varchar(8000) string	Öffentlicher Download-Link für das Rechnungsdokument, wie von `pixi.DocumentPublicLink_Get` geliefert.
`LinkExpirationDate` Kann leer sein	datetime dateTime	Zeitpunkt, zu dem der Download-Link abläuft.

Beispielantwort

<SqlRowSet1>
  <row>
    <InvoiceId>104523</InvoiceId>
    <InvoiceNr>RE2024-001234</InvoiceNr>
    <DownloadLink>https://documents.example.com/public/3f2a9c1e-7b4d-4e8a-9f10-2c6d5e8b1a77</DownloadLink>
    <LinkExpirationDate>2024-06-15T14:30:00</LinkExpirationDate>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
Error	Either InvoiceId or InvoiceNr must be provided.	Weder `InvoiceId` noch eine nicht leere `InvoiceNr` wurde übergeben. Mindestens einen der Werte angeben.
Error	InvoiceId and InvoiceNr do not match.	Beide Parameter wurden übergeben, und zu mindestens einem existiert eine Rechnung, aber keine Rechnung hat sowohl die angegebene ID als auch die angegebene Nummer.
Error	Invoice Not Found.	Zur angegebenen `InvoiceId` und/oder `InvoiceNr` existiert keine Rechnung.
Error	Document Not Found.	Die Rechnung existiert, hat aber kein gespeichertes Dokument (`DocumentStorageId` ist NULL), z. B. weil noch kein Rechnungs-PDF erzeugt wurde.
Error	Failed to generate invoice download link.	Die interne Prozedur `pixi.DocumentPublicLink_Get` lieferte einen Status ungleich 0. Die Ursache ist aus diesem Code nicht ersichtlich.

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:pixiGetInvoicePublicLink>
      <!-- <InvoiceId>104523</InvoiceId> -->
      <!-- <InvoiceNr>RE2024-001234</InvoiceNr> -->
    </ns1:pixiGetInvoicePublicLink>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

curl -X POST 'https://apigateway.descartes.com/tms/pixi/' \
  --user 'USERNAME:PASSWORD' \
  --header 'Content-Type: text/xml; charset=utf-8' \
  --data-binary @- <<'XML'
<?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:pixiGetInvoicePublicLink>
      <!-- <InvoiceId>104523</InvoiceId> -->
      <!-- <InvoiceNr>RE2024-001234</InvoiceNr> -->
    </ns1:pixiGetInvoicePublicLink>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML

<?php

$soapClient = new SoapClient(null, [
    'login' => 'USERNAME',
    'password' => 'PASSWORD',
    'location' => 'https://apigateway.descartes.com/tms/pixi/',
    'uri' => 'https://apigateway.descartes.com/tms/pixi/',
]);

$arguments = [
    // 'InvoiceId' => '104523',
    // 'InvoiceNr' => 'RE2024-001234',
];

$soapArguments = [];
foreach ($arguments as $name => $value) {
    $soapArguments[] = new SoapVar($value, XSD_STRING, '', '', $name);
}

$response = $soapClient->__soapCall('pixiGetInvoicePublicLink', $soapArguments);

Verwendete Tabellen

Invoices · Lesen

SQL-Objekt:: dbo.pipiGetInvoicePublicLink