SHIPTRACK- (shipment tracking) - WEBSALE Dokumentation

Once a buyer has placed their order, they want to know where the parcel is right now. Shipment tracking fetches this information directly from the shipping service provider and makes it available in the template. Four tags are enough for this, and they build on one another. One tag triggers the request, a second tells you whether it succeeded, a third gives the reason in case of an error, and the fourth returns the provider’s response for further processing.

Guide: DHL shipment tracking
Guide: Post AT shipment tracking

All four tags are permitted on all templates. The feature must be enabled in the shop, and the access credentials for each provider are in the ShipTrack section of the shop configuration. Each entry there has an identifier that you use to address it in the template.

Triggering the request

SHIPTRACK-Get() takes two arguments: the identifier of the configuration entry and the tracking number. Both may come from another tag.

~SHIPTRACK-Get(DHL,$DC-FPtrackingNumber_StripHTML$)~

The tag triggers a request to the shipping service provider and waits for its response. Place it exactly once and only where the result is needed. On an overview page with many shipments, every occurrence becomes a separate request.

SHIPTRACK-Get() is exclusively a single tag and requires both arguments. If one is missing, or if one is empty after tag-in-tag resolution, the whole tag is considered invalid and produces a message in the template.

If you pass a tag as an argument, replace its tilde characters with dollar signs, as in the example.

The shop system supports three providers: DHL, the Austrian Post and the Swiss Post connection. Which one is meant is defined in the configuration entry, not in the tag. In the template, nothing changes apart from the identifier in the first argument.

Was the request successful

SHIPTRACK-OK exists only as a bracketing. It applies if the last request ran without errors.

~SHIPTRACK-Get(DHL,$DC-FPtrackingNumber_StripHTML$)~

{SHIPTRACK-OK}
   <p>Aktueller Status Ihrer Sendung:</p>
   ...
{/SHIPTRACK-OK}

{!SHIPTRACK-OK}
   <p>Zu dieser Sendung liegen derzeit keine Informationen vor.</p>
{/!SHIPTRACK-OK}

The order in the template matters. SHIPTRACK-OK, SHIPTRACK-LastErrorCode and SHIPTRACK-JSONResult refer to the last request and must therefore come after SHIPTRACK-Get(). Before it, no request has taken place yet.

Tracing errors

SHIPTRACK-LastErrorCode outputs the code of the last request.

{!SHIPTRACK-OK}
   <p>Die Sendungsverfolgung ist derzeit nicht erreichbar. Fehlercode ~SHIPTRACK-LastErrorCode~.</p>
{/!SHIPTRACK-OK}

Code	Meaning
0	the request was successful
1	shipment tracking is not enabled in the shop
2	the identifier is empty
3	the tracking number is empty
4	there is no configuration entry for this identifier
5	the configuration entry does not name a known provider
1000 and above	the provider rejected the request or did not respond

Codes 1, 4 and 5 indicate an incomplete configuration, not a problem with the shipment. A code of 1000 or above, on the other hand, comes from the provider itself, for example in the case of an unknown tracking number, a rejected login or a timeout.

In practice, you cannot reach codes 2 and 3 from a template. An empty argument already makes SHIPTRACK-Get() fail as an invalid tag beforehand, so the request never takes place.

As a bracketing, SHIPTRACK-LastErrorCode applies if there is an error, that is, for a code greater than zero. The negative bracketing therefore does not mean “no code available” but “no error”, and is equivalent to SHIPTRACK-OK. The previous documentation describes the corresponding example differently.

Evaluating the response

SHIPTRACK-JSONResult returns the provider’s complete response as JSON. You pass it to the JSON interface and access the individual details there.

{SHIPTRACK-OK}
   ~EJD-SetRawDataInput($SHIPTRACK-JSONResult$)~
   ~EJD-LoadData(intern,rawdatainput,shiptrack)~
{/SHIPTRACK-OK}

The structure of the response comes from the provider and differs from provider to provider. With DHL, the most recently reported status is in the header of the record, followed by the list of individual events.

{
    "data": {
        "data": {
            "-piece-code": "00340435088500530592",
            "-last-event-timestamp": "10.06.2021 09:51",
            "-status": "Die Sendung wurde erfolgreich zugestellt.",
            "-product-name": "Warenpost",
            "data": [
                {
                    "-name": "piece-event",
                    "-event-timestamp": "09.06.2021 14:21",
                    "-event-status": "Die Sendung wurde elektronisch angekündigt.",
                    "-event-location": "",
                    "-standard-event-code": "VA"
                },
                {
                    "-name": "piece-event",
                    "-event-timestamp": "10.06.2021 09:51",
                    "-event-status": "Die Sendung wurde erfolgreich zugestellt.",
                    "-event-location": "",
                    "-standard-event-code": "ZU"
                }
            ]
        }
    }
}

DHL responds in XML. The shop system converts the response to JSON before output. That explains the leading hyphens on the keys: they mark former XML attributes. The Austrian Post already delivers JSON, so these hyphens are absent there.

Only evaluate SHIPTRACK-JSONResult within SHIPTRACK-OK. Without a preceding successful request, the output is not usable.

The field names within the response are defined by the provider, not by the shop system. They can change without anything changing in the shop. Therefore, catch missing fields with the check tags of the JSON interface instead of relying on their presence.

Reference: EJD- (JSON interface)

Tags at a glance

Tag	Single tag	Area tag	Negative area tag	Loop tag
`SHIPTRACK-Get()`	yes	–	–	–
`SHIPTRACK-OK`	–	yes	yes	–
`SHIPTRACK-LastErrorCode`	yes	yes	yes	–
`SHIPTRACK-JSONResult`	yes	yes	yes	–

All four tags are permitted on all templates. The last three require a preceding SHIPTRACK-Get().

Guide: DHL shipment tracking
Guide: Post AT shipment tracking
Reference: EJD- (JSON interface)
Reference: ShipTrack section in the shop configuration

​Triggering the request

​Was the request successful

​Tracing errors

​Evaluating the response

​Tags at a glance

​Related topics

Triggering the request

Was the request successful

Tracing errors

Evaluating the response

Tags at a glance

Related topics