HPA Logo
API docs by Redocly

transPORT rail JSON API (v1)

Download OpenAPI specification:Download

Introduction

This is the JSON API of transPORT rail (tPr), the traffic management system for rail transport at the port of Hamburg. The message types described below are part of the communication processes between an RTC, Quay and the tPr system.
JSON API means that this is a REST API using standard HTTP verbs, with the content of requests and responses in JSON format.

Please note that this description is a work in progress and we are continuously trying to improve it.

Response messages (not the technical response http 200 or 400)

For every message a Response message has to be sent back, either as a confirmation or as a rejection of the incoming message. For example, when a TransportOrder is received by the tPr system, syntax and consistency check is done. If formal errors are found, a negative response message specifying the errors will be sent as a reply. In this case the tPr has not saved the data of the message and it can be sent again with corrected data using the same order reference and version. If the message has no formal errors, the order will be created. The tPr then sends a positive response message to the sender.

Response Messages by tPr are currently only supported for messages from the RU (former TD04), for messages from the location in the port (former TD01), no response messages are sent.

Authentication

Bearer

The API can be accessed using JSON Web Tokens (JWT), an open standard specified in RFC 7519. In order to make properly authorized requests follow these steps:

  1. Register your service with HPA to obtain a client ID and secret.
  2. Store them on your production system. Make sure the client secret is encrypted!
  3. During runtime you need to use the client ID and client secret to get a token from the HPA IdentityServer.

Then you can use the token in your requests using Bearer Authentication.

LoadingDone

Ursprünglich TD01.VI/VW/VD/VL/VZ Verlade-Ist (in)

Authorizations:
bearer_auth
Request Body schema:

LoadingDone object instance

required
object

Metainfo für die Übertragung.

required
object

Angaben zur Ladestelle an der verladen wurde

taNumber
required
string = 5 characters

Transportauftrags-Nummer

evuOrderReference
string or null [ 0 .. 35 ] characters

Auftragsreferenz des Auftraggebers

typeOfTransport
required
string = 1 characters C|K

Art des Transports

Gültige Werte:

K für Wagenladungsverkehr (konventioneller Verkehr)
C für Kombinierten Verkehr (Container)

euroPalletCount
integer <int32> [ 0 .. 999 ] ^[0-9]*$

Anzahl Europalleten im Tausch - Nur bei typeOfTransport K

boxPalletCount
integer <int32> [ 0 .. 999 ] ^[0-9]*$

Anzahl Boxpalleten im Tausch - Nur bei typeOfTransport K

flaws
string or null [ 0 .. 200 ] characters

Mängelbericht - Nur bei typeOfTransport K

content
string or null [ 0 .. 200 ] characters

Inhalt der Ladung - Nur bei typeOfTransport K

required
Array of objects (TransportUnit)

Liste der Ladeeinheiten, für die VI gesetzt werden soll - bei typeOfTransport = K - Wagen, bei typeOfTransport = C - Container

Responses

Request samples

Content type
{
  • "metainfo": {
    },
  • "location": {
    },
  • "taNumber": "12345",
  • "evuOrderReference": "01010101ABCD",
  • "typeOfTransport": "C",
  • "euroPalletCount": 100,
  • "boxPalletCount": 100,
  • "flaws": "100",
  • "content": "Kohle",
  • "transportUnits": [
    ]
}

Response

Ursprünglich TD04.RE Quittung (in), TD04.RE Quittung (out), TD01.RE Quittung (out)

Authorizations:
bearer_auth
Request Body schema:

Responce object instance

object or null

Metainfo für die Übertragung.

Array of objects or null (Reference) non-empty

Referenzen

messageType
string or null

Art der quittierten Nachricht

generalResponseCode
required
string = 1 characters

Beschreibt die Verarbeitung der der Originalnachricht

"O" = Ok - Nachricht verarbeitet ohne weitere Kommentare
"W" = Warning - Nachricht verarbeitet, Quittung enthält Warnungen
"E" = Error - Nachricht nicht verarbeitet, Quittung enthält Fehlerhinweise

ResponseDateTime
required
string non-empty ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$...

Zeitpunkt der Quittierung

ISO 8601 Format: YYYY-MM-DDThh:mm:ss.SSSZ

Array of objects or null (ResponseTexts)

Text zur Antwort

Responses

Request samples

Content type
{
  • "metainfo": {
    },
  • "references": [
    ],
  • "messageType": "TransportOrder",
  • "generalResponseCode": "O",
  • "ResponseDateTime": "2020-05-27T12:14:15.562Z",
  • "texts": [
    ]
}

Create Example Response

Authorizations:
bearer_auth

Responses

TransportOrder

TD04.TO Transportauftrag, TD01 - (EB, EV, TC, TK, TL, TV, TW)

Authorizations:
bearer_auth
Request Body schema:

TransportOrder object instance

required
object

Metainfo für die Übertragung.

operatorCode
string or null [ 0 .. 5 ] characters

Bei der HPA registrierter Teilnehmer-Code des Operateurs

processingInstructions
string or null [ 0 .. 1 ] characters

Verarbeitungskennzeichen

typeOfTransport
required
string = 1 characters C|K

Art des Transports

Gültige Werte:
K für Wagenladungsverkehr (konventioneller Verkehr)
C für Kombinierten Verkehr (Container)

direction
required
string = 1 characters I|O

Transportrichtung

Gültige Werte: 
I = Inbound 
O = Outbound

transportOrderVersion
required
integer <int32> [ 1 .. 99 ] ^[0-9]*$

Version des Transportauftrags

required
Array of objects (References)

Array von Referenzen

Externe Referenzen zur Zuordnung des Transportauftrags. Es muss mindestens ein Eintrag mit Typ "CTOREF" vorhanden sein.

required
object

Verladedetails

required
object

Entladedetails

object or null

Details zum grenzüberschreitendem Verkehr

wagonDisposalCategory
string or null [ 0 .. 1 ] characters

Verfügungsart lt. Schlüsseltabelle

Schlüsselverzeichnis Verfuegungsart

clearanceStation
string or null [ 0 .. 32 ] characters

Bahnhof an dem die Verzollung vorgenommen werden soll

railwayBillType
string or null [ 0 .. 4 ] characters

Frachtbrief-Art (CIM, EVO etc.)

klvIndicator
integer <int32> ^[0-9]*$

Kennzeichen für KLV-Verkehr Import/Export per Zug(7) oder LKW(8)

overloadLicenceNumber
string or null [ 0 .. 6 ] characters

Genehmigungsnummer für Schwerwagen bzw. Lademaß-Überschreitung

overloadLicenceYear
integer <int32> ^[0-9]*$

Jahr der Genehmigung für Schwerwagen / Lademaß-Überschreitung

required
object

Versender, Pflichtangabe - es muss mindestens das Feld customerName geliefert werden

required
object

Empfänger, Pflichtangabe - es muss mindestens das Feld customerName geliefert werden

object or null

Verkehrsführer

object or null

Kunde des EVU

referenceIdSec
string or null [ 0 .. 35 ] characters

Sekundärreferenznummer

invoiceRecipient
string or null [ 0 .. 10 ] characters

Rechnungsempfänger (Langtext)

required
Array of objects (ToTransportUnit)

Responses

Request samples

Content type
{
  • "metainfo": {
    },
  • "operatorCode": "ABCD",
  • "processingInstructions": "1",
  • "typeOfTransport": "C",
  • "direction": "O",
  • "transportOrderVersion": 1,
  • "references": [
    ],
  • "dispatchDetail": {
    },
  • "dischargeDetail": {
    },
  • "transitDetail": {
    },
  • "wagonDisposalCategory": "s",
  • "clearanceStation": "",
  • "railwayBillType": "",
  • "klvIndicator": 0,
  • "overloadLicenceNumber": "",
  • "overloadLicenceYear": 2025,
  • "consignor": {
    },
  • "consignee": {
    },
  • "shippingDirector": {
    },
  • "customer": {
    },
  • "referenceIdSec": "",
  • "invoiceRecipient": "",
  • "transportUnits": [
    ]
}

WagonSequence

Ursprünglich TD04DB.WS Wagenreihung Ankunft/Abfahrt der Zuführung/Abholung (out)

Authorizations:
bearer_auth
Request Body schema:
required
object

Metainfo für die Übertragung.

operatorCode
string or null [ 0 .. 5 ] characters

Bei der HPA registrierter Teilnehmer-Code des Operateurs

processingInstructions
string or null [ 0 .. 1 ] characters

Verarbeitungskennzeichen

direction
required
string = 1 characters I|O

Transportrichtung

Gültige Werte: 
I = Inbound 
O = Outbound

typeOfSequence
required
string = 1 characters LD|PL|TF|DP

Im Bahnversand wird "LD" für die Verlade-Daten gesendet.

In Reihungen wird "PL" für Soll-Reihungen, "TF" für Zugbildungs-Ende, "DP" für Abfahrt benutzt.

sequenceVersion
required
integer <int32> [ 1 .. 99 ] ^[0-9]*$

Version der Reihung (1-99)

object or null

Zuginformationen

trainCompositionCheck
required
string = 1 characters Y|N

Kennzeichen Reihungskontrolle Y|N

departureDate
string or null^\d{4}-\d{2}-\d{2}$

Abfahrtsdatum

ISO 8601 Format: YYYY-MM-DD

departureTime
string or null^(?:[01]\d|2[0-3]):[0-5]\d$

Abfahrtszeit

ISO 8601 Format: hh:mm (UTC)

arrivalDate
string or null^\d{4}-\d{2}-\d{2}$

Ankunftsdatum

ISO 8601 Format: YYYY-MM-DD

arrivalTime
string or null^(?:[01]\d|2[0-3]):[0-5]\d$

Ankunftszeit

ISO 8601 Format: hh:mm (UTC)

required
object

Bahnhofsangabe des aktuellen Standorts

required
object

Bahnhofsangabe des Abfahrtsortes

required
object

Bahnhofsangabe des Ankunftsortes

trainCategory
string or null

Zuggattungsnummer

grossLoadWeight
integer <int32> [ 0 .. 999999 ] ^[0-9]*$

Gesamtgewicht der Ladung in kg inklusive Lademittel

grossBrakingPower
integer <int32> [ 0 .. 999999 ] ^[0-9]*$

Wagenzugbremsgewicht in kg

grossTrailingLoad
integer <int32> [ 0 .. 999999 ] ^[0-9]*$

Wagenzuggewicht in kg

axlesEmpty
integer <int32> ^[0-9]*$

Anzahl Achsen Leerwagen

axlesLoaded
integer <int32> ^[0-9]*$

Anzahl Achsen beladene Wagen

required
Array of objects (Vehicle)

Fahrzeugliste

Responses

Request samples

Content type
{
  • "metainfo": {
    },
  • "operatorCode": "ABCD",
  • "processingInstructions": "1",
  • "direction": "O",
  • "typeOfSequence": "LD",
  • "sequenceVersion": 1,
  • "train": {
    },
  • "trainCompositionCheck": "N",
  • "departureDate": "2020-05-27",
  • "departureTime": "16:30",
  • "arrivalDate": "2020-05-27",
  • "arrivalTime": "16:30",
  • "currentStation": {
    },
  • "departureStation": {
    },
  • "arrivalStation": {
    },
  • "trainCategory": "string",
  • "grossLoadWeight": 99999,
  • "grossBrakingPower": 99999,
  • "grossTrailingLoad": 99999,
  • "axlesEmpty": 300,
  • "axlesLoaded": 300,
  • "vehicles": [
    ]
}