Invoices Read

pixiGetInvoicePublicLink

Returns a public download link with expiration date for the stored document of an invoice, identified by invoice ID and/or invoice number.

Resolves an invoice and returns a public download link for its stored document.

InvoiceNr is trimmed. An empty value is treated as not provided.
At least one of InvoiceId or InvoiceNr must be given. Otherwise an error row is returned.
Both given: the invoice must match both InvoiceKey = InvoiceId and InvoiceNr.
- If no invoice matches both, but an invoice exists with either the ID or the number, the call returns the error InvoiceId and InvoiceNr do not match.
- If neither exists, it returns Invoice Not Found.
Only one given: the invoice is looked up by that value. If nothing is found, it returns Invoice Not Found.
If the invoice has no linked document (DocumentStorageId is empty), it returns Document Not Found.
The download link and its expiration date are generated by the internal procedure pixi.DocumentPublicLink_Get. If that procedure reports a non-zero status, it returns Failed to generate invoice download link.
On success, one row is returned with the invoice ID, the resolved invoice number, the download link and the link expiration date.

Notes

The link itself is produced by pixi.DocumentPublicLink_Get. Its definition is not attached, so the following is not visible from this code:
- the link format,
- the validity period,
- whether link records are stored in the database.
Errors are returned as a normal row with Status = Error and Message. They are not raised as SQL errors. The procedure return code is 1 on error and 0 on success.
Invoices are read with NOLOCK, so uncommitted data may be seen.
The lookup uses TOP (1) without ORDER BY. If several invoices share the same InvoiceNr, the invoice returned for a lookup by number alone is arbitrary. Pass InvoiceId to get a deterministic result.

Parameters

Parameter	Type	Default	Description
`InvoiceId`	int	NULL	Internal invoice key (`InvoiceKey`). Optional if `InvoiceNr` is given. If both are given, they must belong to the same invoice. Example: `104523`
`InvoiceNr`	varchar(20) string	NULL	Invoice number. It is trimmed, and an empty value is treated as not provided. Optional if `InvoiceId` is given. Example: `RE2024-001234`

Response

Result set 1 · On error (missing parameters, invoice not found, mismatch, no document, link generation failed)

Status row describing the error. No further result set follows.

Column	Type	Description
`Status`	varchar(5) string	Always `Error`.
`Message`	varchar(100) string	Error message text.

Result set 2 · On success

One row with the resolved invoice and its public download link.

Column	Type	Description
`InvoiceId`	int	Internal invoice key (`Invoices.InvoiceKey`).
`InvoiceNr` Nullable	varchar(20) string	Invoice number as stored in the invoice record.
`DownloadLink` Nullable	varchar(8000) string	Public download link for the invoice document, as returned by `pixi.DocumentPublicLink_Get`.
`LinkExpirationDate` Nullable	datetime dateTime	Date and time when the download link expires.

Response example

<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>

Error messages

Status	Message	Cause
Error	Either InvoiceId or InvoiceNr must be provided.	Neither `InvoiceId` nor a non-empty `InvoiceNr` was passed. Provide at least one of them.
Error	InvoiceId and InvoiceNr do not match.	Both parameters were passed, and an invoice exists for at least one of them, but no invoice has both the given ID and the given number.
Error	Invoice Not Found.	No invoice exists for the given `InvoiceId` and/or `InvoiceNr`.
Error	Document Not Found.	The invoice exists but has no stored document (`DocumentStorageId` is NULL), for example because no invoice PDF has been generated yet.
Error	Failed to generate invoice download link.	The internal procedure `pixi.DocumentPublicLink_Get` returned a non-zero status. The reason is not visible from this code.

Examples

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);

Tables used

Invoices · Read

SQL object:: dbo.pipiGetInvoicePublicLink