transport instruction / e-pod interface documentation€¦ · dokument: interface documentation...

Transport Instruction / e-POD

Interface documentation

Version 3.32

Dokument: Interface documentation Transportinstruction/e-POD

Version: 3.32 Schenker AB, IT Development

Dokumentnamn: interfacedoc_schenker_ti-e-POD_3_32.pdf

Datum: 2015-06-23 Side 2 of 31

2(31)

TABLE OF CONTENTS

1 SERVICE ADDRESS .................................................................................................................... 3

2 INPUT/OUTPUT DATA FORMAT ................................................................................................ 3

3 INPUT/OUTPUT DATA STRUCTURE ......................................................................................... 5

3.1 Request ..................................................................................................... 5

3.2 Response .................................................................................................. 6

3.3 System ...................................................................................................... 6

4 OVERVIEW OF SERVICE METHOD MESSAGES ...................................................................... 7

4.1 get_transport_document ........................................................................... 7

4.2 get_transport_instruction ........................................................................... 7

4.3 get_waybill ................................................................................................ 7

4.4 get_epod ................................................................................................... 8

5 MESSAGE DEFINITIONS ............................................................................................................ 9

5.1 get_transport_document ........................................................................... 9

5.1.1 Input .............................................................................................. 9

5.1.2 Output ......................................................................................... 10

5.2 get_transport_instruction ......................................................................... 11

5.2.1 Input ............................................................................................ 11

5.2.2 Output ......................................................................................... 14

5.3 get_waybill .............................................................................................. 20

5.3.1 Input ............................................................................................ 20

5.3.2 Output ......................................................................................... 24

5.4 get_epod ................................................................................................. 24

5.4.1 Input ............................................................................................ 24

5.4.2 Output ......................................................................................... 29

5.5 Xml output at no hits ............................................................................... 30

5.6 Xml output at error .................................................................................. 30

5.7 Xml output at validation error .................................................................. 31

5.8 Service unique error codes ..................................................................... 31




Datum: 2015-06-23 Side 3 of 31

3(31)

Changes Version histoy:

Version Date Comments

3.32 2015-06-23 Corrected minor errors.

3.31 2014-10-15 Changed link for apply for authorization.

3.30 2014-03-11 Removed chapter about Search transport documents. Renumbering of chapters due to the removal.

3.20 2010-12-06 Added information regarding e-service authentication including link to application form.

3.10 2008-05-20 Added the reference_type value “cw”. Chp. 5.4.1.1 consignor_reference_number added. Chp.5.4.1.3: This is a new chapter.

3.02 2007-06-03 Changed Example-URL for test.

3.01 2007-01-26 Chp. 4.1, 5.1.1.1: Search by pallet balance

1 Service address

The service is found at this URL:

http://was.webtrp.com/trpdocWeb/TrpDocServlet_1?

Transport Instruction/e-POD is a user-authenticated service. Authorization is applied for here (only in Swedish):

http://www.schenker.se/access

2 Input/output data format

The service input parameters and output messages are formated according to the Schenker Web Development Rules v2.2 (WDR) (or 2.1 where 2.2 are not yet complete).

Input parameters are named according to the WDR hqf format. The primary return format of non pdf returns are xml (MIME format text/xml), but the service also supports the WDR format hqf (MIME format text/plain). Images are returned as Base64 encoded pdf embedded in XML.

In this document the input parameters are presented in hqf format (nothing else is supported) while response messages are presented as xml (the usual return format). Consult the WDR for translation to hqf.

http://was.webtrp.com/trpdocWeb/TrpDocServlet_1?

http://www.schenker.se/access




Datum: 2015-06-23 Side 4 of 31

4(31)

The service handles both GET and POST http requests.




Datum: 2015-06-23 Side 5 of 31

5(31)

3 Input/output data structure

According to the WDR, the data structure of the interface is buildt up on four general containers (xml elements) which groups data in logical units. The containers are:

request, consists of information to the service,

response, consists of information from the service,

system, contains error information generated in the system,

data_list, is an array of containers containing the actual message data.

The request, response and system containers have some standard fields which apply to all messages. These are described below. Message dependant values for these fields are described in the message definitions.

Note that a message can contain additional data, not definied in this document. Such data are to be ignored. Also note that the data doesn’t have to be sent in any specific order.

3.1 Request

The hqf fields below are contained inside the request container. Add the prefix “request.” to the fields to get complete hqf path.

Name M Type Standard Explanation

service.action M String WDR Tells the service what to do.

service.method M String WDR Is a specialisation of service.action.

Tells the service what kind of select action to perform.

service.type M String WDR Is a specialization of service.method.

format.mime M String WDR Tells the service which format to use in the response.

Supported formats are:

text/xml for xml returns

text/plain for hqf returns

text/html for html returns

format.type String WDR Is a specialisation of format.mime.

Supported format:

text/xml

application/pdf

user.login_name M String WDR The user name. Used for authorization.

user.password M String WDR The user password. Used for authorization.

M = Mandatory




Datum: 2015-06-23 Side 6 of 31

6(31)

3.2 Response

The xml fields below are contained inside the response container. Add the element <xml><response> to the fields to get complete xml path.


<service><name> M String WDR The name of the service: ‘transport_document’

<service><version> M String WDR The version of the service.

<data_list_count> M Int WDR The number of containers in the ‘data_list’ array.

M = Mandatory

3.3 System

The xml fields below are contained inside the system container. Add the element <xml><system> to the fields to get complete xml path.


<error><id> M Int WDR Error code:

0 means OK (no error) 10 means service closed 210 means validation error See WDR for complete set of error codes.

<error><message> String WDR Error message.

<error><service><error><id> Int WDR Service specific error codes. See Service unique error codes.

<error><validation_list><validation index=”n”><field_name>

M* String WDR Hqf name of invalid input field.

<error><validation_list><validation index=”n”><error><id>

M* Int WDR Validation error code (see WDR).

<error><validation_list><validation index=”n”><old_value>

M* String WDR Value of invalid input field.

<error><validation_list><validation index=”n”><old_value>

M* String WDR The code for the invalid input field.

M = Mandatory M* = Mandatory at validation error (error.id=210)




Datum: 2015-06-23 Side 7 of 31

7(31)

4 Overview of service method messages

These are the available methods

1 get_transport_document

2 get_transport_instruction

3 get_waybill

4 get_epod

4.1 get_transport_document

Gets a specific transport instruction or waybill.

Input (data_list-array size=1):

transport document number or package-id

Output:

if both transport instruction and waybill are found

the transport instruction and notification about available waybill

else if only transport instruction is found

the transport instruction

else if only waybill is found

the associated waybill (as base 64 encoded pdf)

else

standard WDR no hit response (or error message)

4.2 get_transport_instruction

Gets one or many specific transport instruction(s).

Input (data_list-array size=n):

transport document number and optionally response format type specification (mandatory if data_list-array size>1)

Output:

if response format type specification is pdf

the transport instruction for each transport document number in the request data_list-array (one or many) as a merged base 64 encoded pdf (if found, else no hit/error message)

else

the transport instruction for the first transport document number in the request data_list-array (if found, else no hit/error message)

4.3 get_waybill

Gets one or many specific transport waybill(s).




Datum: 2015-06-23 Side 8 of 31

8(31)


transport document number

Output:

the waybill for each transport document number in the request data_list-array (one or many) as a merged base 64 encoded pdf (if found, else no hit/error message)

4.4 get_epod

Gets one or many specific epod(s).


transport document number

Output:

the epod for each transport document number in the request data_list-array (one or many) as a merged base 64 encoded pdf (if found, else no hit/error message)




Datum: 2015-06-23 Side 9 of 31

9(31)

5 Message definitions

In this chapter input hqf parameters and output xml messages are defined for each supported method of the service.

5.1 get_transport_document

5.1.1 Input

5.1.1.1 Parametrar

The table below defines the input hqf parameters to get a specific transport instruction (primary) or waybill (secondary).

Name M Type Standard Value / Explanation

Request container. Add the prefix ‘request.’ to the parameters.

service.action M String WDR Value = ‘select’

service.method M String WDR Value = ‘get_transport_document’

format.mime M String WDR The wanted return format.

user.login_name M String WDR The user name.

user.password M String WDR The user password.

Data container array. Add the prefix ‘data_list.0.’ to the parameters.

Note: The service only handles one data container (the first, index=0). Any additional data containers will be ignored.

reference_number M String RFF Reference number (search argument) defined by a reference function code qualifier (reference_type).

reference_type M String RFF Reference function code qualifier (search argument). Code giving specific meaning to a reference number (sent in ‘reference_number’).

Valid values: aas, cw

RFF 1153 AAS Transport document number

[1188] Reference assigned by the carrier or his agent to the transport document.

Consignment ID

IFTMBF: RFF+AAS

IFTMIN: RFF+AAS

FS: Waybill number




Datum: 2015-06-23 Side 10 of 31

10(31)

TI: Transport document number

STE: Consignment ID

RFF 1153 CW Package number (7070) Reference number identifying a package or carton within a consignment.

is_include_delivery_note Boolean

Derived from WDR and RFF1153DQ

Boolean flag telling if delivery note information should be included in transport instruction response. If present and value is true do include.

Statistics paramters. Add the prefix ’system.’ to the parameters.

statistics.remote.country_code M String WDR Country code for client, ex. ’se’ or ’us’

statistics.user.language_code M String WDR Language code for the client, ex. ’sv_se’

statistics.remote.send_data_format

M String WDR The clients way to send its Request, ’xml’ or ’hqf’ (Http Query Format)

statistics.remote.access_type M String WDR The clients type of call, ’A’ (browser)

statistics.remote.application_name

M String WDR The name of the client application that makes the call.

statistics.user.return_mime_format

M String WDR The format that the client wants the response to be in. ’text/plain’, ’text/html’ or ’text/xml’

statistics.user.organization_id M String WDR The clients VAT number.

statistics.service.api_version M String WDR 2.0

statistics.remote.admin_e_mail M String WDR The e-mail address to the responsible for the clients application

M = mandatory

5.1.2 Output

If instruction/waybill isn’t found a “no hits” message will be returned. See section ”Xml output at no hits”.

If a validation error occur a validation error message will be returned. See section ”Xml output at validation error”. The validation error codes depends on the error (see WDR).

If any other error occurs a general error message will be returned. See section ”Xml output at error”. The error code depends on the error (see WDR). Note: also service specific error messages may be returned. See ”Service unique error codes”.




Datum: 2015-06-23 Side 11 of 31

11(31)

5.2 get_transport_instruction

5.2.1 Input

5.2.1.1 Parameters

The table below defines the input hqf parameters to get one or many specific transport instruction(s).




service.method M String WDR Value = ‘get_transport_instruction’


format.type M1 String WDR Used when instruction should be returned as base64 encoded pdf embedded in xml.

Valid value = application/pdf or text/xml



Data container array. Add the prefix ‘data_list.n.’ to the parameters.

Note: When request.format.type=application/pdf the service handles multiple containers, otherwise only one data container (the first, index=0) is handled (any additional data containers will be ignored).



Valid values: aas, cw

AAS Transport document number


Consignment ID

IFTMBF: RFF+AAS

IFTMIN: RFF+AAS

FS: Waybill number





Datum: 2015-06-23 Side 12 of 31

12(31)

STE: Consignment ID

RFF1153CW Package number (7070) Reference number identifying a package or carton within a consignment.

is_include_delivery_note Boolean

Derived from RFF1153DQ

Boolean flag telling if delivery note information should be included in response. If present and value is true do include.














M = mandatory

M1 = mandatory when data_list-array size > 1




Datum: 2015-06-23 Side 13 of 31

13(31)

5.2.1.2 Example URI for search by waybill number

Change the folowing parameters to relevant data:

<Service_URL>

<UserID>

<UserPassword>

<ReferenceNumber>

<ClientVATNumber>

<emailAddress>

Example-URL for get_transport_instruction one document as PDF:

<Service_URL>?request.service.action=select&request.service.method=get_transport_instruction&request.format.mime=text/html&request.format.type=application/pdf&request.user.login_name=<UserID>&request.user.password=<UserPassword>&data_list.0.reference_number=<ReferenceNumber>&data_list.0.reference_type=aas&data_list.0.is_include_delivery_note=false&system.statistics.remote.country_code=se&system.statistics.remote.send_data_format=hqf&system.statistics.remote.access_type=A&system.statistics.remote.application_name=Test&system.statistics.user.organization_id=<ClientVATNumber>&system.statistics.user.language_code=sv&system.statistics.user.return_mime_format=xml&system.statistics.remote.send_data_format=web2&system.statistics.service.api_version=2.0&system.statistics.remote.admin_e_mail=<emailAddress>&system.statistics.service.name=TrpDoc

Example-URL for get_transport_instruction one document as XML:

<Service_URL>?request.service.action=select&request.service.method=get_transport_instruction&request.format.mime=text/xml&request.format.type=text/xml&request.user.login_name=<UserID>&request.user.password=<UserPassword>&data_list.0.reference_number=<ReferenceNumber>&data_list.0.reference_type=aas&data_list.0.is_include_delivery_note=false&system.statistics.remote.country_code=se&system.statistics.remote.send_data_format=hqf&system.statistics.remote.access_type=A&system.statistics.remote.application_name=Test&system.statistics.user.organization_id=<ClientVATNumber>&system.statistics.user.language_code=sv&system.statistics.user.return_mime_format=xml&system.statistics.remote.send_data_format=web2&system.statistics.service.api_version=2.0&system.statistics.remote.admin_e_mail=<emailAddress>&system.statistics.service.name=TrpDoc

Example-URL for get_transport_instruction one document as PDF-string in XML:

<Service_URL>?request.service.action=select&request.service.method=get_transport_instruction&request.format.mime=text/xml&request.format.type=application/pdf&request.user.login_name=<UserID>&request.user.password=<UserPassword>&data_list.0.reference_number=<ReferenceNumber>&data_list.0.reference_type=aas&data_list.0.is_include_delivery_note=false&system.statistics.remote.country_code=se&system.statistics.remote.send_data_format=hqf&system.statistics.remote.access_type=A&system.statistics.remote.application_name=Test&system.statistics.user.organization_id=<ClientVATNumber>&system.statistics.user.language_code=sv&system.statistics.user.return_mime_format=xml&system.statistics.remote.send_data_format=web2&system.statistics.service.api_version=2.0&system.statistics.remote.admin_e_mail=<emailAddress>&system.statistics.service.name=TrpDoc




Datum: 2015-06-23 Side 14 of 31

14(31)

5.2.2 Output

Xml example below illustrates response when instruction is found.

If no waybills are found a “no hits” message will be returned. See section Xml output at no hits.

If a validation error occur a validation error message will be returned. See section Xml output at validation error. The validation error codes depends on the error (see WDR).

If any other error occurs a general error message will be returned. See section Xml output at error. The error code depends on the error (see WDR). Note: also service specific error messages may be returned. See Service unique error codes.

When request.format.type!=application/pdf (and data_list-array size == 1)

<?xml version="1.0" encoding="ISO-8859-1" ?>

<xml>

<data_list>

<data index=”0”>

<transport_document_number>123456</transport_document_number>

etc…

<package_details_list>

<package_details index="n">

<package_identification>

etc…

</package_details>

</package_details_list>

<additional_service_list>

<additional_service index="0">

<additional_service_transport_code/>

etc…

<additional_service_details_list>

<additional_service_details index="n">

<additional_service_details/>

</additional_service_details>

</additional_service>

</additional_service_list>

<delivery_instructions_list>

<delivery_instructions index="n">

<delivery_instructions/>

</delivery_instructions>

</delivery_instructions_list>

<senders_instruction_to_carrier_list>

<senders_instruction_to_carrier index="0">

<senders_instruction_to_carrier/>

</senders_instruction_to_carrier>

</senders_instruction_to_carrier_list>

<information_for_consignee_list>

<information_for_consignee index="0">

<information_for_consignee/>




Datum: 2015-06-23 Side 15 of 31

15(31)

</information_for_consignee>

</information_for_consignee_list>

</data>

</data_list>

<system>

<error>

<id>0</id>

</error>

</system>

<response>

<service>

<name>xxx</name>

<version>1.0</version>

</service>

<data_list_count>1</data_list_count>

</response>

</xml>

Complete XML example:

When request.format.type==application/pdf


<xml>

<data_list>


<transport_instruction_pdf>

base64 encoded (multi page) pdf

</transport_instruction_pdf

</data>

</data_list>

<system>

<error>

<id>0</id>

</error>

</system>

<response>

<service>

<name>xxx</name>


</service>


</response>

</xml>




Datum: 2015-06-23 Side 16 of 31

16(31)

5.2.2.1 Parameters

The table below defines the output hqf parameters in the data_list-array. Add the prefix ‘data_list.n.’ to the parameters.

Name Type Standard Value / Explanation

transport_document_number RFF-AAS Reference assigned by the carrier or his agent to the transport document.

acceptance_date Cons-DTM2005-143DE 2380

Acceptance date/time of goods [2126] Date on which the goods are taken over by the carrier at the place of acceptance (CMR 4).

object_update_date_time no standard

Date and time when the record was updated in the database.

consignor_name String (35)

NAD 3035-CZ DE 3036

The name of the consignor (sender) party.

consignor_address String (35)

NAD 3035-CZ DE 3042:1

The address of the consignor (sender) party.

consignor_address2 String (35)

NAD 3035-CZ DE 3042:2

The address (sub level) of the consignor (sender) party.

consignor_address3 The address (sub level) of the consignor (sender) party.

consignor_zip_number String (9)

NAD 3035-CZ DE 3251

The postal code of the consignor (sender) party.

consignor_city_name String (35)

NAD 3035-CZ DE 3164

The name or IATA-code of the city where the consignor (sender) party is located.

consignor_reference_number String(17)

RFF-1153-CU

Sales order number.

Reference number assigned by a consignor to a particular shipment for his own purposes or for those of the consignee.

Abbreviated as “cu” when used as a reference function code qualifier.

consignor_identification String (17)

NAD 3035-CZ DE 3039

The identifier of the consignor (sender) party.

consignor_pallet_identification The pallet identification of the consignor (sender) party.

consignor_telephone_number String (17)

NAD-CZ 3155-TE

The telephone number of the consignor (sender) party.




Datum: 2015-06-23 Side 17 of 31

17(31)

DE 3148

consignor_telefax_number The telefax number of the consignor (sender) party.

consignee_name String (35)

NAD 3035-CN DE 3036

The name of the consignee party.

consignee_address String (35)

NAD 3035-CN DE 3042:1

The address of the consignee party.

consignee_address2 String (35)

NAD 3035-CN DE 3042:2

The address (sub level) of the consignee party.

consignee_address3 The address (sub level) of the consignee party.

consignee_zip_number String (9)

NAD 3035-CN DE 3251

The postal code of the consignee party.

consignee_city_name String (35)

NAD 3035-CN DE 3164

The name or IATA-code of the city where the consignee party is located.

consignee_shipment_reference_number

The reference number of the shipment for the consignee.

consignee_identification String (17)

NAD 3035-CN DE 3039

The identifier of the consignee party.

consignee_pallet_identification The pallet identification of the consignee party.

consignee_telephone_number String (17)

NAD-CN 3155-TE DE 3148

The telephone number of the consignee party.

consignee_telefax_number The telefax number of the consignee party.

contract_condition_code The product.

freight_payer_identification The identification of the freight payer.

consignment_eur_pallet_count The number of European pallets.

consignment_package_count Int (7) Cons-CNT 6069-11 DE 6066

Total number of packages in the consignment.

consignment_package_count_calculated

Calculated number of packages in the consignment.

consignment_gross_weight

Num (9,3)

Cons-CNT 6069–7 DE 6066 Unit 6411

The total weight (mass) of goods in the consignment, including packing but excluding the carrier's equipment.




Datum: 2015-06-23 Side 18 of 31

18(31)

consignment_gross_weight_calculated

The calculated weight (mass) of goods in the consignment, including packing but excluding the carrier's equipment.

consignment_gross_weight_observed_calculated

The observed calculated weight (mass) of goods in the consignment, including packing but excluding the carrier's equipment.

consignment_cube Num (7,3)

Cons-CNT 6069-15 DE 6066 Unit 6411

Total volume (size or measure in three dimensions) of goods in the consignment.

consignment_cube_calculated Calculated volume (size or measure in three dimensions) of goods in the consignment.

consignment_cube_observed_calculated

Observed calculated volume (size or measure in three dimensions) of goods in the consignment.

_observed is the observed/real value in difference of the value that is given in the edi-message. _calculated is the sum of all included packages.

consignment_loading_meters Loading meters of goods in the consignment.

consignment_loading_meters_calculated

Calculated loading meters of goods in the consignment.

consignment_loading_meters_observed_calculated

Observed calculated loading meters of goods in the consignment.

consignment_item_count Number of item count (styckegods).

consignment_pallet_space Number of pallet space for goods in the consignment.

is_waybill_available no standard

If a waybill is available. Has the value 1 if there is one.

waybill_object_identification The image key in the storage system.

is_epod_available If epod is available.

epod_object_identification The identification of the epod object.

package_details_list Array

package_details Container Details about all the packages.

package_identification The identification of a package.

type_of_packages String (10)

GID DE 7064

The goods type as text. E.g. pallet, box, bottle.

goods_description String (35)

GID DE 7064

Description of a goods item.




Datum: 2015-06-23 Side 19 of 31

19(31)

package_gross_weight Num (9,3)

GID 6313-G DE 6314 Unit 6411

The weight (mass) of one goods item, including packing but excluding the carrier's equipment.

package_gross_weight_observed

Observed weight.

package_cube Num (9,3)

GID 6311-VOL DE 6314 Unit 6411

Volume (size or measure in three dimensions) of one single package.

New! To be used when implementing packages details.

package_cube_observed Observed volume.

package_loading_meters Num (7,2)

GID 6311-LMT DE 6314 Unit 6411

The length in a vehicle, whereby the complete width and height over that length is needed for the goods item.

package_loading_meters_observed

Observed length in a vehicle.

additional_service_list Array

additional_service Container Additional services.

additional_service_transport_code

The transport code of an additional service.

additional_service_contact_name

TSR

CTA

3139

zzz

The contact name of an additional service.

additional_service_contact_telephone_number

The telephone number of an additional service.

additional_service_details_list Array

additional_service_details Container

TSR

ASD

E959

More details of additional services.

additional_service_details Details of an additional service.

delivery_instructions_list Array

delivery_instructions Container Delivery instructions.

delivery_instructions DIN The delivery instruction.

senders_instruction_to_carrier_list

Array

senders_instruction_to_carrier Container Senders instructions to carrier.

senders_instruction_to_carrier String (999*

FTX 4451-SIC

Self explanatory (free text).




Datum: 2015-06-23 Side 20 of 31

20(31)

70) DE 4440

information_for_consignee_list Array

information_for_consignee Container Information for the consignee.

information_for_consignee ICN The information for the consignee.

5.3 get_waybill

5.3.1 Input

5.3.1.1 Parameters

The table below defines the input hqf parameters to get a single waybill (as base64 encoded pdf embedded in xml).




service.method M String WDR Value = ‘get_waybill’







Valid value: aas, zwoid



Consignment ID

IFTMBF: RFF+AAS

IFTMIN: RFF+AAS

FS: Waybill number




Datum: 2015-06-23 Side 21 of 31

21(31)


STE: Consignment ID

zwoid = no standard waybill object identification














M = mandatory

5.3.1.2 Example URI for search by one waybill number


<Service_URL>

<UserID>

<UserPassword>

<ReferenceNumber>

<ClientVATNumber>

<emailAddress>

Example-URL for get_waybill one document as XML:

<Service_URL>?request.service.action=select&request.service.method=get_waybill&request.format.mime=text/xml&request.user.login_name=<UserID>&request.user.password=<UserPassword>&data_list.0.reference_number=<ReferenceNumber>&data_list.0.reference_type=aas&system.statistics.remote.country_code=se&system.statistics.remote.send_data_format=hqf&system.statistics.remote.access_type=A&system.statistics.remote.application_name=Test&system.statistics.user.organization_id=<ClientVATNumber>&system.statistics.user.language_code=sv&system.statistics.user.return_mime_format=xml&system.statistics.remote.send_data_format=web2&system.statistics.service.api_version=2.0&system.statistics.remote.admin_e_mail=<emailAddress>&system.statistics.service.name=TrpDoc




Datum: 2015-06-23 Side 22 of 31

22(31)

Example-URL for get_waybill one document as PDF:

<Service_URL>?request.service.action=select&request.service.method=get_waybill&request.format.mime=text/html&request.format.type=application/pdf&request.user.login_name=<UserID>&request.user.password=<UserPassword>&data_list.0.reference_number=<ReferenceNumber>&data_list.0.reference_type=aas&system.statistics.remote.country_code=se&system.statistics.remote.send_data_format=hqf&system.statistics.remote.access_type=A&system.statistics.remote.application_name=Test&system.statistics.user.organization_id=<ClientVATNumber>&system.statistics.user.language_code=sv&system.statistics.user.return_mime_format=xml&system.statistics.remote.send_data_format=web2&system.statistics.service.api_version=2.0&system.statistics.remote.admin_e_mail=<emailAddress>&system.statistics.service.name=TrpDoc




Datum: 2015-06-23 Side 23 of 31

23(31)

5.3.1.3 Example URI for search by two waybill numbers


<Service_URL>

<UserID>

<UserPassword>

<Referensnummer_1>

<Referensnummer_2>

<ClientVATNumber>

<emailAddress>

Example-URL for get_waybill two documents as XML:

<Service_URL>?request.service.action=select&request.service.method=get_waybill&request.format.mime=text/xml&request.user.login_name=<UserID>&request.user.password=<UserPassword>&data_list.0.reference_number=<Referensnummer_1>&data_list.0.reference_type=aas&data_list.1.reference_number=<Referensnummer_2>&data_list.1.reference_type=aas&system.statistics.remote.country_code=se&system.statistics.remote.send_data_format=hqf&system.statistics.remote.access_type=A&system.statistics.remote.application_name=Test&system.statistics.user.organization_id=<ClientVATNumber>&system.statistics.user.language_code=sv&system.statistics.user.return_mime_format=xml&system.statistics.remote.send_data_format=web2&system.statistics.service.api_version=2.0&system.statistics.remote.admin_e_mail=<emailAddress>&system.statistics.service.name=TrpDoc

Example-URL for get_waybill two documents as PDF:

<Service_URL>?request.service.action=select&request.service.method=get_waybill&request.format.mime=text/html&request.format.type=application/pdf&request.user.login_name=<UserID>&request.user.password=<UserPassword>&data_list.0.reference_number=<Referensnummer_1>&data_list.0.reference_type=aas&data_list.1.reference_number=<Referensnummer_2>&data_list.1.reference_type=aas&system.statistics.remote.country_code=se&system.statistics.remote.send_data_format=hqf&system.statistics.remote.access_type=A&system.statistics.remote.application_name=Test&system.statistics.user.organization_id=<ClientVATNumber>&system.statistics.user.language_code=sv&system.statistics.user.return_mime_format=xml&system.statistics.remote.send_data_format=web2&system.statistics.service.api_version=2.0&system.statistics.remote.admin_e_mail=<emailAddress>&system.statistics.service.name=TrpDoc




Datum: 2015-06-23 Side 24 of 31

24(31)

5.3.2 Output

Xml example below illustrates response when waybill is found.





<xml>

<data_list>


<waybill_pdf>


</waybill_pdf>

</data>

</data_list>

<system>

<error>

<id>0</id>

</error>

</system>

<response>

<service>

<name>xxx</name>


</service>


</response>

</xml>

5.4 get_epod

5.4.1 Input

5.4.1.1 Parameters

The table below defines the input hqf parameters to get a single waybill (as base64 encoded pdf embedded in xml).




Datum: 2015-06-23 Side 25 of 31

25(31)




service.method M String WDR Value = ‘get_epod’







Valid value: aas, zepoid, cw



Consignment ID

IFTMBF: RFF+AAS

IFTMIN: RFF+AAS

FS: Waybill number


STE: Consignment ID

zepoid = no standard epod object identification









statistics.user.return_mime_for M String WDR The format that the client wants the




Datum: 2015-06-23 Side 26 of 31

26(31)

mat response to be in. ’text/plain’, ’text/html’ or ’text/xml’




M = mandatory




Datum: 2015-06-23 Side 27 of 31

27(31)

5.4.1.2 Example URL for search by waybill numberr


<Service_URL>

<UserID>

<UserPassword>

<ReferenceNumber>

<ClientVATNumber>

<emailAddress>

Example-URL for get_epod one document as XML:

<Service_URL>?request.service.action=select&request.service.method=get_epod&request.format.mime=text/xml&request.user.login_name=<UserID>&request.user.password=<UserPassword>&data_list.0.reference_number=<ReferenceNumber>&data_list.0.reference_type=aas&system.statistics.remote.country_code=se&system.statistics.remote.send_data_format=hqf&system.statistics.remote.access_type=A&system.statistics.remote.application_name=Test&system.statistics.user.organization_id=<ClientVATNumber>&system.statistics.user.language_code=sv&system.statistics.user.return_mime_format=xml&system.statistics.remote.send_data_format=web2&system.statistics.service.api_version=2.0&system.statistics.remote.admin_e_mail=<emailAddress>&system.statistics.service.name=TrpDoc

Example-URL for get_epod one document as PDF:

<Service_URL>?request.service.action=select&request.service.method=get_epod&request.format.mime=text/html&request.format.type=application/pdf&request.user.login_name=<UserID>&request.user.password=<UserPassword>&data_list.0.reference_number=<ReferenceNumber>&data_list.0.reference_type=aas&system.statistics.remote.country_code=se&system.statistics.remote.send_data_format=hqf&system.statistics.remote.access_type=A&system.statistics.remote.application_name=Test&system.statistics.user.organization_id=<ClientVATNumber>&system.statistics.user.language_code=sv&system.statistics.user.return_mime_format=xml&system.statistics.remote.send_data_format=web2&system.statistics.service.api_version=2.0&system.statistics.remote.admin_e_mail=<emailAddress>&system.statistics.service.name=TrpDoc

5.4.1.3 Exempel URL for search by packet number


<Service_URL>

<UserID>

<UserPassword>

<ReferenceNumber>

<ClientVATNumber>

<emailAddress>




Datum: 2015-06-23 Side 28 of 31

28(31)

Example-URL for get_epod one document as XML:

<service_URI>?request.service.action=select&request.service.method=get_epod&request.format.mime=text/xml&request.user.login_name=<UserID>&request.user.password=<UserPassword>&data_list.0.reference_number=<packet_number>&data_list.0.reference_type=cw&system.statistics.remote.country_code=se&system.statistics.remote.send_data_format=hqf&system.statistics.remote.access_type=A&system.statistics.remote.application_name=Test&system.statistics.user.organization_id=<ClientVATnumber>&system.statistics.user.language_code=sv&system.statistics.user.return_mime_format=xml&system.statistics.remote.send_data_format=web2&system.statistics.service.api_version=2.0&system.statistics.remote.admin_e_mail=<emailAddress>&system.statistics.service.name=TrpDoc

Example-URL for get_epod one document as PDF:

<ServiceURL>?request.service.action=select&request.service.method=get_epod&request.format.mime=text/html&request.format.type=application/pdf&&request.user.login_name=<UserID>&request.user.password=<UserPassword>&data_list.0.reference_number=<packet_number>&data_list.0.reference_type=cw&system.statistics.remote.country_code=se&system.statistics.remote.send_data_format=hqf&system.statistics.remote.access_type=A&system.statistics.remote.application_name=Test&system.statistics.user.organization_id=<ClientVATnumber>&system.statistics.user.language_code=sv&system.statistics.user.return_mime_format=xml&system.statistics.remote.send_data_format=web2&system.statistics.service.api_version=2.0&system.statistics.remote.admin_e_mail=<emailAddress>&system.statistics.service.name=TrpDoc




Datum: 2015-06-23 Side 29 of 31

29(31)

5.4.2 Output

Xml example below illustrates response when epod is found.





<xml>

<data_list>


<proof_of_delivery_pdf>


</proof_of_delivery_pdf>

</data>

</data_list>

<system>

<error>

<id>0</id>

</error>

</system>

<response>

<service>

<name>xxx</name>


</service>


</response>

</xml>

5.4.2.1 Parameters

The table below defines the output hqf parameters in the data_list-array. Add the prefix ‘data_list.n.’ to the parameters.

Name Type Standard Value / Explanation

proof_of_delivery_pdf Base64 encoded binary pdf

Proof of delivery as PDF.




Datum: 2015-06-23 Side 30 of 31

30(31)

5.5 Xml output at no hits

When a select action doesn’t find anything to return (no error, but no hits) by means of the supplied search arguments, a standard no hit message (defined in the WDR) is returned. The xml version of this message is found below:


<xml>

<system>

<error>

<id>0</id>

</error>

</system>

<response>

<service>

<name>xxx</name>


</service>


</response>

</xml>

5.6 Xml output at error

When an error (other than validation error) occurs, a standard error message (defined in the WDR) is returned. The structure is always the same, only error code/message will differ (error codes/messages are found in the WDR). An xml example is found below:


<xml>

<system>

<error>

<id>507</id>

</error>

</system>

<response>

<service>

<name>xxx</name>


</service>


</response>

</xml>




Datum: 2015-06-23 Side 31 of 31

31(31)

5.7 Xml output at validation error

When the service is given an invalid input a validation error message would be returned. The structure of this message if always the same (defined in the WDR). An xml example is given below (the mandatory parameters “request.service.action” and “request.service.method” was missing in request):


<xml>

<system>

<error>

<id>210</id>

<message>invalid data</message>

<validation_list>

<validation index="0">

<field_name>request.service.action</field_name>

<old_value />

<error>

<id>304</id>

</error>

</validation>

<validation index="1">

<field_name>request.service.method </field_name>

<old_value />

<error>

<id>304</id>

</error>

</validation>

</validation_list>

</error>

</system>

<response>

<service>

<name>xxx</name>


</service>


</response>

</xml>

5.8 Service unique error codes

system.error.service.error.id/message are new parameters in WDR v 2.2. They are for application specific codes. Not only for errors, it can also be used for warnings etc.

Valid values for these parameters are not specified in the WDR, they are specified for each service.

transport instruction / e-pod interface documentation€¦ · dokument: interface documentation...

Documents