Shipping API Technical Reference

From Infranet Wiki
Jump to: navigation, search

Here you can find complete technical reference needed to consume Shipping API with the list of available methods, their descriptions, method invoke examples and example request/response JSON objects used in communication.

Shipping API process

ShippingAPIprocess.jpg
In order to better understand the Shipping API proces, developer should consult following flowchart. The depicted shipping API process describes what the Shipping API is designed for. This sample flowchart explains major process flows and major API methods used by all users of Shipping APIs. However, Shipping API can be used in may different cases However, if you require any help determining if Shipping API fits your need, do not hesitate contacting your couriers support.







Important notes

  1. All Byte[] fields are transported over the network as Base64 strings and need to be decoded client-side. Base64 Wikipedia article.
  2. Store your API Key securely server-side. Do not, by any means, use it from client-side (javascript) code.


List of API methods

Depending on HTTP method, API method is invoked either with URL query parameters for GET HTTP method or JSON in request body for POST HTTP method. Each method description below indicates which HTTP method is used.

GetShipmentStatusByShipmentId

HTTP method: GET

Method will return the status of the shipment with the passed in id. Shipment statuses are defined and described in ShipmentStatusEnum.

Request

Field name Field type Max length Description Is required
ShipmentId Int32 / True
ApiKey Guid / True

Response

Field name Field type Description
Shipment ResponseShipment /
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "Shipment": {
    "ShipmentId": 1,
    "Status": 1,
    "DateCreated": "2014-09-08T14:41:51.9190163+02:00",
    "StatusDate": "2014-09-08T14:41:51.9190163+02:00",
    "ReturnDocument": false,
    "CargoNetShipmentId": "Text value",
    "PriceInformation": {
      "Net": 0.0,
      "Gross": 0.0
    },
    "Collies": [
      {
        "ColliId": 1,
        "Status": 1,
        "CargoNetColliId": "Text value",
        "BarCode": "Text value",
        "Ref1": "Text value",
        "Ref2": "Text value",
        "Ref3": "Text value",
        "RefInt": "Text value",
        "MultifunctionalBarcode": "Text value",
        "Services": "Text value"
      }
    ],
    "Traces": [
      {
        "ParcelNumber": "Text value",
        "ScanDate": "2014-09-08T14:41:51.9220166+02:00",
        "ScanTime": "2014-09-08T14:41:51.9220166+02:00",
        "StatusNumber": 1,
        "StatusDescription": "Text value",
        "CenterName": "Text value",
        "Remark": "Text value"
      }
    ],
    "DeliveryCenterAbbreviation": "ZA",
    "TourNumber": 12
  },
  "IsValid": false,
  "ModelErrors": null,
  "ValidationErrors": null
}

GetShipmentStatusByRef1AndPickupDate

HTTP method: GET

Method will return the status of the shipment with the REF1 field and shipping date passed in. The REF1 field must be unique for any given date so the data must be passed in. Shipment statuses are defined and described in ShipmentStatusEnum.

Request

Field name Field type Max length Description Is required
Ref1 String 35 / True
PickupDate DateTime / True
ApiKey Guid / True

Response

Field name Field type Description
Shipment ResponseShipment /
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "Shipment": {
    "ShipmentId": 1,
    "Status": 1,
    "DateCreated": "2014-09-08T14:41:52.1320376+02:00",
    "StatusDate": "2014-09-08T14:41:52.1320376+02:00",
    "ReturnDocument": false,
    "CargoNetShipmentId": "Text value",
    "PriceInformation": {
      "Net": 0.0,
      "Gross": 0.0
    },
    "Collies": [
      {
        "ColliId": 1,
        "Status": 1,
        "CargoNetColliId": "Text value",
        "BarCode": "Text value",
        "Ref1": "Text value",
        "Ref2": "Text value",
        "Ref3": "Text value",
        "RefInt": "Text value",
        "MultifunctionalBarcode": "Text value",
        "Services": "Text value"
      }
    ],
    "Traces": [
      {
        "ParcelNumber": "Text value",
        "ScanDate": "2014-09-08T14:41:52.1320376+02:00",
        "ScanTime": "2014-09-08T14:41:52.1320376+02:00",
        "StatusNumber": 1,
        "StatusDescription": "Text value",
        "CenterName": "Text value",
        "Remark": "Text value"
      }
    ],
    "DeliveryCenterAbbreviation": "ZA",
    "TourNumber": 12
  },
  "IsValid": false,
  "ModelErrors": null,
  "ValidationErrors": null
}

GetShipmentStatusByAnyRef

HTTP method: GET

Method used to return shipment statuses containing information in the REF fields. The fields can be freely used for any customer need. Shipment statuses are defined and described in ShipmentStatusEnum.

Request

Field name Field type Max length Description Is required
RefType Int32 1, 2 or 3 for Ref1, Ref2 or Ref3 True
SearchParameter String 35 Ref field value to search for True
ApiKey Guid / True

Response

Field name Field type Description
Shipments List of ResponseShipment /
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "Shipments": [
    {
      "ShipmentId": 1,
      "Status": 1,
      "DateCreated": "2014-09-08T14:41:52.1350379+02:00",
      "StatusDate": "2014-09-08T14:41:52.1350379+02:00",
      "ReturnDocument": false,
      "CargoNetShipmentId": "Text value",
      "PriceInformation": {
        "Net": 0.0,
        "Gross": 0.0
      },
      "Collies": [
        {
          "ColliId": 1,
          "Status": 1,
          "CargoNetColliId": "Text value",
          "BarCode": "Text value",
          "Ref1": "Text value",
          "Ref2": "Text value",
          "Ref3": "Text value",
          "RefInt": "Text value",
          "MultifunctionalBarcode": "Text value",
          "Services": "Text value"
        }
      ],
      "Traces": [
        {
          "ParcelNumber": "Text value",
          "ScanDate": "2014-09-08T14:41:52.1350379+02:00",
          "ScanTime": "2014-09-08T14:41:52.1350379+02:00",
          "StatusNumber": 1,
          "StatusDescription": "Text value",
          "CenterName": "Text value",
          "Remark": "Text value"
        }
      ],
      "DeliveryCenterAbbreviation": "ZA",
      "TourNumber": 12,
    }
  ],
  "IsValid": false,
  "ModelErrors": null,
  "ValidationErrors": null
}

CreateShipmentPlain

HTTP method: POST

Method used to create shipments without listing colli data, the method requires just the number of collies to be sent. In the case of OverseasPrintsShippingLabels set to true a pickup order is immediately created, if the OverseasPrintsShippingLabels is set to false the sender is expected to print the shipping labels.

Request

Field name Field type Max length Description Is required
NumberOfCollies Int32 Number of collies contained in this shipment. Must be greater than 0. True
Weight Double? Weight of the whole shipment in kilograms. False
ShipperPrintsLabels Boolean Flag indicating whether shipper or sender prints shipping labels. True
Ref1 String 35 Value of this field must be unique on a single date. It is printed on a shipping label. True
Ref2 String 35 Value is printed on a shipping label. True
Ref3 String 35 Value is printed on a shipping label. True
RemarkGoods String 150 Description of goods being sent. False
CountOfBillingUnits Double? Count of billing units (e.g if shipment containes 3 small boxes value of this field is 3 and the value of BillingUnit is SBX). False
ConsigneeName String 35 / True
ConsigneePostalCode String 10 / True
ConsigneeStreet String 70 / True
ConsigneeCity String 35 / True
ConsigneeCountryPrefix String 3 HR, AT, BE, CZ, DK, FR, DE, HU, IE, IT, LU, NL, PL, PT, RO, SK, SI, ES, CH, BG, ... True
ConsigneeTelephoneNumber String 30 / False
ConsigneeFaxNumber String 30 / False
ConsigneeGsmNumber String 30 / False
ConsigneeEmailAddress String 70 / False
SenderName String 35 / True
SenderPostalCode String 10 / True
SenderStreet String 70 / True
SenderCity String 35 / True
SenderCountryPrefix String 3 HR, RS, BA, ... True
SenderTelephoneNumber String 30 / False
SenderFaxNumber String 30 / False
SenderGsmNumber String 30 / False
SenderEmailAddress String 70 / False
ExpressType Int32 Indicates until when the shipment should be delivered. See ExpressTypeEnum for allowed values. True
ExWorksType Int32? Null value means that the sender pays for shipping. See ExWorksTypeEnum for allowed values. False
NotificationType Int32 See NotificationTypeEnum for allowed values. True
AllowSaturdayDelivery Boolean / True
PickupStart DateTime? If both date and time are passed the time value should be looked up by calling GetPossibleDateTimesForShipments method. It is possible to pass only date value (with 00:00:00 time) in both pickupStart and pickupEnd fields. In that case shipment will be created with 1st available interval for pickup for the given postal code. False
PickupEnd DateTime? If both date and time are passed the time value should be looked up by calling GetPossibleDateTimesForShipments method. It is possible to pass only date value (with 00:00:00 time) in both pickupStart and pickupEnd fields. In that case shipment will be created with 1st available interval for pickup for the given postal code. False
DeliveryStart DateTime? Date part of this field is ignored. Only time is important. If the value is not null, DeliveryEnd must be set as well. Combination of DeliveryStart and DeliveryEnd indicate delivery time frame. Time value for this field should be looked up by calling GetPossibleDateTimesForShipments method. If the value is null shipment will be created with 1st available interval for delivery for the given postal code. False
DeliveryEnd DateTime? Date part of this field is ignored. Only time is important. If the value is not null, DeliveryStart must be set as well. Combination of DeliveryStart and DeliveryEnd indicate delivery time frame. Time value for this field should be looked up by calling GetPossibleDateTimesForShipments method. If the value is null shipment will be created with 1st available interval for delivery for the given postal code. False
CodAmount Double? Cash on delivery amount. False
CodCurrency Int32? Currency for the cash on delivery. If CodAmount is null, this field is ignored. See CurrencyEnum for allowed values. False
InsuranceAmount Double? If shipment is insured this field contains amount of insurance. False
Currency Int32? Currency for insurance. If InsuranceAmount is null, this field is ignored. See CurrencyEnum for allowed values. False
RemarkDelivery String 150 Description of delivery usually printed on shipping label. True
RemarkPickup String 150 Description of pickup usually printed on shipping label. True
IsCargo Boolean Flag indicating if the shipment is consisted of pallets instead of boxes. True
ReturnDocument Boolean Flag indicating whether return document exists that is collected upon delivery. True
BillingUnit Int32? If CustomerBillingUnitOverride is set, this field is ignored. See BillingUnitEnum for allowed values and their descriptions. False
ShipmentDocumentData Byte[] PDF document that is merged with the shipping label PDF as a new page. When shipping labels are fetched with later API calls this document is returned as a part of the shipping label. False
ShipmentDocumentExtension String 10 Extension of the document. For now only "PDF" value is allowed. Must be "PDF" if ShipmentDocumentData is not null. False
ApiKey Guid Authentication API key. True

JSON example:

{
  "NumberOfCollies": 1,
  "Weight": null,
  "OverseasPrintsShippingLabels": false,
  "Ref1": "Text value",
  "Ref2": "Text value",
  "Ref3": "Text value",
  "RemarkGoods": "Text value",
  "CountOfBillingUnits": null,
  "ConsigneeName": "Text value",
  "ConsigneePostalCode": "Text value",
  "ConsigneeStreet": "Text value",
  "ConsigneeCity": "Text value",
  "ConsigneeCountryPrefix": "HR",
  "ConsigneeTelephoneNumber": "Text value",
  "ConsigneeFaxNumber": "Text value",
  "ConsigneeGsmNumber": "Text value",
  "ConsigneeEmailAddress": "Text value",
  "SenderName": "Text value",
  "SenderPostalCode": "Text value",
  "SenderStreet": "Text value",
  "SenderCity": "Text value",
  "SenderCountryPrefix": "HR",
  "SenderTelephoneNumber": "Text value",
  "SenderFaxNumber": "Text value",
  "SenderGsmNumber": "Text value",
  "SenderEmailAddress": "Text value",
  "ExpressType": 100,
  "ExWorksType": null,
  "NotificationType": 3,
  "AllowSaturdayDelivery": false,
  "PickupStart": null,
  "PickupEnd": null,
  "DeliveryStart": null,
  "DeliveryEnd": null,
  "CodAmount": null,
  "CodCurrency": null,
  "InsuranceAmount": null,
  "Currency": null,
  "RemarkDelivery": "Text value",
  "RemarkPickup": "Text value",
  "IsCargo": false,
  "ReturnDocument": false,
  "BillingUnit": null,
  "ShipmentDocumentData": null,
  "ShipmentDocumentExtension": null,
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
CreatedShipmentId Int32? Identifier of the created shipment. Value is not null only if the request was valid
Collies List of ResponseColli Value is not null only if the request was valid
PickupStart DateTime? Value is not null only if the request was valid
PickupEnd DateTime? Value is not null only if the request was valid
DeliveryStart DateTime? Value is not null only if the request was valid
DeliveryEnd DateTime? Value is not null only if the request was valid
PriceInformation PriceInformation Value is not null only if the request was valid
ValidPickupIntervals List of TimeInterval Value is not null only if the request was valid
ValidDeliveryIntervals List of TimeInterval Value is not null only if the request was valid
AdditionalInfo AdditionalInfo Value is not null only if the request was valid
ExpectedSenderAddress ExpectedSenderAddress Value is not null only if the request was valid
DeliveryCenterAbbreviation String Delivery center for created shipment. Represents routing information. This must be printed if for some reason client creates own shipping labels and not API's built-in functionality for fetching shipping labels.
TourNumber Int32? Tour number for created shipment. Represents routing information. This must be printed if for some reason client creates own shipping labels and not API's built-in functionality for fetching shipping labels.
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "CreatedShipmentId": 153,
  "Collies": [
    {
      "ColliId": 1,
      "Status": 1,
      "CargoNetColliId": "Text value",
      "BarCode": "Text value",
      "Ref1": "Text value",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RefInt": "Text value"
    }
  ],
  "PickupStart": "2014-09-08T12:00:00+02:00",
  "PickupEnd": "2014-09-08T118:00:00+02:00",
  "DeliveryStart": "2014-09-09T12:00:00+02:00",
  "DeliveryEnd": "2014-09-09T18:00:00+02:00",
  "PriceInformation": {
    "Net": 100.0,
    "Gross": 150.0
  },
  "ValidPickupIntervals": [
    {
      "From": "2014-09-08T12:00:00+02:00",
      "To": "2014-09-08T18:00:00+02:00"
    }
  ],
  "ValidDeliveryIntervals": [
    {
      "From": "2014-09-09T12:00:00+02:00",
      "To": "2014-09-09T18:00:00+02:00"
    }
  ],
  "AdditionalInfo": {
    "DeliveryBefore0830": false,
    "DeliveryBefore1030": false,
    "SaturdayDelivery": false
  },
  "ExpectedSenderAddress": {
    "PostalCode": "Text value",
    "City": "Text value",
    "Street": "Text value"
  },
  "DeliveryCenterAbbreviation": "ZA",
  "TourNumber": 12,
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

UpdateShipmentPlain

HTTP method: POST

Method used to update an existing shipment. This method can not be used in the case of the OverseasPrintsShippingLabels set to true.

Request

Field name Field type Max length Description Is required
ShipmentId Int32 Identifier of the shipment being updated. / True
NumberOfCollies Int32 Number of collies contained in this shipment. Must be greater than 0. True
Weight Double? Weight of the whole shipment in kilograms. False
ShipperPrintsLabels Boolean Flag indicating whether shipper or sender prints shipping labels. True
Ref1 String 35 Value of this field must be unique on a single date. It is printed on a shipping label. True
Ref2 String 35 Value is printed on a shipping label. True
Ref3 String 35 Value is printed on a shipping label. True
RemarkGoods String 150 Description of goods being sent. False
CountOfBillingUnits Double? Count of billing units (e.g if shipment containes 3 small boxes value of this field is 3 and the value of BillingUnit is SBX). False
ConsigneeName String 35 / True
ConsigneePostalCode String 10 / True
ConsigneeStreet String 70 / True
ConsigneeCity String 35 / True
ConsigneeCountryPrefix String 3 HR, AT, BE, CZ, DK, FR, DE, HU, IE, IT, LU, NL, PL, PT, RO, SK, SI, ES, CH, BG True
ConsigneeTelephoneNumber String 30 / False
ConsigneeFaxNumber String 30 / False
ConsigneeGsmNumber String 30 / False
ConsigneeEmailAddress String 70 / False
SenderName String 35 / True
SenderPostalCode String 10 / True
SenderStreet String 70 / True
SenderCity String 35 / True
SenderCountryPrefix String 3 HR True
SenderTelephoneNumber String 30 / False
SenderFaxNumber String 30 / False
SenderGsmNumber String 30 / False
SenderEmailAddress String 70 / False
ExpressType Int32 Indicates until when the shipment should be delivered. See ExpressTypeEnum for allowed values. True
ExWorksType Int32? Null value means that the sender pays for shipping. See ExWorksTypeEnum for allowed values. False
NotificationType Int32 See NotificationTypeEnum for allowed values. True
AllowSaturdayDelivery Boolean / True
PickupStart DateTime? If both date and time are passed the time value should be looked up by calling GetPossibleDateTimesForShipments method. It is possible to pass only date value (with 00:00:00 time) in both pickupStart and pickupEnd fields. In that case shipment will be created with 1st available interval for pickup for the given postal code. False
PickupEnd DateTime? If both date and time are passed the time value should be looked up by calling GetPossibleDateTimesForShipments method. It is possible to pass only date value (with 00:00:00 time) in both pickupStart and pickupEnd fields. In that case shipment will be created with 1st available interval for pickup for the given postal code. False
DeliveryStart DateTime? Date part of this field is ignored. Only time is important. If the value is not null, DeliveryEnd must be set as well. Combination of DeliveryStart and DeliveryEnd indicate delivery time frame. Time value for this field should be looked up by calling GetPossibleDateTimesForShipments method. If the value is null shipment will be created with 1st available interval for delivery for the given postal code. False
DeliveryEnd DateTime? Date part of this field is ignored. Only time is important. If the value is not null, DeliveryStart must be set as well. Combination of DeliveryStart and DeliveryEnd indicate delivery time frame. Time value for this field should be looked up by calling GetPossibleDateTimesForShipments method. If the value is null shipment will be created with 1st available interval for delivery for the given postal code. False
CodAmount Double? Cash on delivery amount. False
CodCurrency Int32? Currency for the cash on delivery. If CodAmount is null, this field is ignored. See CurrencyEnum for allowed values. False
InsuranceAmount Double? If shipment is insured this field contains amount of insurance. False
Currency Int32? Currency for insurance. If InsuranceAmount is null, this field is ignored. See CurrencyEnum for allowed values. False
RemarkDelivery String 150 Description of delivery usually printed on shipping label. True
RemarkPickup String 150 Description of pickup usually printed on shipping label. True
IsCargo Boolean Flag indicating if the shipment is consisted of pallets instead of boxes. True
ReturnDocument Boolean Flag indicating whether return document exists that is collected upon delivery. True
BillingUnit Int32? If CustomerBillingUnitOverride is set, this field is ignored. See BillingUnitEnum for allowed values and their descriptions. False
ShipmentDocumentData Byte[] PDF document that is merged with the shipping label PDF as a new page. When shipping labels are fetched with later API calls this document is returned as a part of the shipping label. False
ShipmentDocumentExtension String 10 Extension of the document. For now only "PDF" value is allowed. Must be "PDF" if ShipmentDocumentData is not null. False
ApiKey Guid Authentication API key. True

JSON example:

{
  "NumberOfCollies": 1,
  "Weight": null,
  "OverseasPrintsShippingLabels": false,
  "Ref1": "Text value",
  "Ref2": "Text value",
  "Ref3": "Text value",
  "RemarkGoods": "Text value",
  "CountOfBillingUnits": null,
  "ConsigneeName": "Text value",
  "ConsigneePostalCode": "Text value",
  "ConsigneeStreet": "Text value",
  "ConsigneeCity": "Text value",
  "ConsigneeCountryPrefix": "HR",
  "ConsigneeTelephoneNumber": "Text value",
  "ConsigneeFaxNumber": "Text value",
  "ConsigneeGsmNumber": "Text value",
  "ConsigneeEmailAddress": "Text value",
  "SenderName": "Text value",
  "SenderPostalCode": "Text value",
  "SenderStreet": "Text value",
  "SenderCity": "Text value",
  "SenderCountryPrefix": "HR",
  "SenderTelephoneNumber": "Text value",
  "SenderFaxNumber": "Text value",
  "SenderGsmNumber": "Text value",
  "SenderEmailAddress": "Text value",
  "ExpressType": 100,
  "ExWorksType": null,
  "NotificationType": 3,
  "AllowSaturdayDelivery": false,
  "PickupStart": null,
  "PickupEnd": null,
  "DeliveryStart": null,
  "DeliveryEnd": null,
  "CodAmount": null,
  "CodCurrency": null,
  "InsuranceAmount": null,
  "Currency": null,
  "RemarkDelivery": "Text value",
  "RemarkPickup": "Text value",
  "IsCargo": false,
  "ReturnDocument": false,
  "BillingUnit": null,
  "ShipmentDocumentData": null,
  "ShipmentDocumentExtension": null,
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
CreatedShipmentId Int32? Identifier of the created shipment. Value is not null only if the request was valid
Collies List of ResponseColli Value is not null only if the request was valid
PickupStart DateTime? Value is not null only if the request was valid
PickupEnd DateTime? Value is not null only if the request was valid
DeliveryStart DateTime? Value is not null only if the request was valid
DeliveryEnd DateTime? Value is not null only if the request was valid
PriceInformation PriceInformation Value is not null only if the request was valid
ValidPickupIntervals List of TimeInterval Value is not null only if the request was valid
ValidDeliveryIntervals List of TimeInterval Value is not null only if the request was valid
AdditionalInfo AdditionalInfo Value is not null only if the request was valid
ExpectedSenderAddress ExpectedSenderAddress Value is not null only if the request was valid
DeliveryCenterAbbreviation String Delivery center for created shipment. Represents routing information. This must be printed if for some reason client creates own shipping labels and not API's built-in functionality for fetching shipping labels.
TourNumber Int32? Tour number for created shipment. Represents routing information. This must be printed if for some reason client creates own shipping labels and not API's built-in functionality for fetching shipping labels.
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "CreatedShipmentId": 153,
  "Collies": [
    {
      "ColliId": 1,
      "Status": 1,
      "CargoNetColliId": "Text value",
      "BarCode": "Text value",
      "Ref1": "Text value",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RefInt": "Text value"
    }
  ],
  "PickupStart": "2014-09-08T12:00:00+02:00",
  "PickupEnd": "2014-09-08T118:00:00+02:00",
  "DeliveryStart": "2014-09-09T12:00:00+02:00",
  "DeliveryEnd": "2014-09-09T18:00:00+02:00",
  "PriceInformation": {
    "Net": 100.0,
    "Gross": 150.0
  },
  "ValidPickupIntervals": [
    {
      "From": "2014-09-08T12:00:00+02:00",
      "To": "2014-09-08T18:00:00+02:00"
    }
  ],
  "ValidDeliveryIntervals": [
    {
      "From": "2014-09-09T12:00:00+02:00",
      "To": "2014-09-09T18:00:00+02:00"
    }
  ],
  "AdditionalInfo": {
    "DeliveryBefore0830": false,
    "DeliveryBefore1030": false,
    "SaturdayDelivery": false
  },
  "ExpectedSenderAddress": {
    "PostalCode": "Text value",
    "City": "Text value",
    "Street": "Text value"
  },
  "DeliveryCenterAbbreviation": "ZA",
  "TourNumber": 12,
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

CreateShipment

HTTP method: POST

Method used to create shipments containing the list of collies. When using this method the sender infomation must match the data for the API key since it is expected of the sender to print the shipping labels.

Request

Field name Field type Max length Description Is required
ShipmentWeight Double? Weight of the whole shipment in kilograms. False
Collies List of ComplexShipmentColli List of collies contained in this shipment. True
Ref1 String 35 Value of this field must be unique on a single date. It is printed on a shipping label. True
Ref2 String 35 Value is printed on a shipping label. True
Ref3 String 35 Value is printed on a shipping label. True
RemarkGoods String 150 Description of goods being sent. False
CountOfBillingUnits Double? Count of billing units (e.g if shipment containes 3 small boxes value of this field is 3 and the value of BillingUnit is SBX). False
ConsigneeName String 35 / True
ConsigneePostalCode String 10 / True
ConsigneeStreet String 70 / True
ConsigneeCity String 35 / True
ConsigneeCountryPrefix String 3 HR, AT, BE, CZ, DK, FR, DE, HU, IE, IT, LU, NL, PL, PT, RO, SK, SI, ES, CH, BG True
ConsigneeTelephoneNumber String 30 / False
ConsigneeFaxNumber String 30 / False
ConsigneeGsmNumber String 30 / False
ConsigneeEmailAddress String 70 / False
SenderName String 35 / True
SenderPostalCode String 10 / True
SenderStreet String 70 / True
SenderCity String 35 / True
SenderCountryPrefix String 3 HR True
SenderTelephoneNumber String 30 / False
SenderFaxNumber String 30 / False
SenderGsmNumber String 30 / False
SenderEmailAddress String 70 / False
ExpressType Int32 Indicates until when the shipment should be delivered. See ExpressTypeEnum for allowed values. True
ExWorksType Int32? Null value means that the sender pays for shipping. See ExWorksTypeEnum for allowed values. False
NotificationType Int32 See NotificationTypeEnum for allowed values. True
AllowSaturdayDelivery Boolean / True
PickupStart DateTime? If both date and time are passed the time value should be looked up by calling GetPossibleDateTimesForShipments method. It is possible to pass only date value (with 00:00:00 time) in both pickupStart and pickupEnd fields. In that case shipment will be created with 1st available interval for pickup for the given postal code. False
PickupEnd DateTime? If both date and time are passed the time value should be looked up by calling GetPossibleDateTimesForShipments method. It is possible to pass only date value (with 00:00:00 time) in both pickupStart and pickupEnd fields. In that case shipment will be created with 1st available interval for pickup for the given postal code. False
DeliveryStart DateTime? Date part of this field is ignored. Only time is important. If the value is not null, DeliveryEnd must be set as well. Combination of DeliveryStart and DeliveryEnd indicate delivery time frame. Time value for this field should be looked up by calling GetPossibleDateTimesForShipments method. If the value is null shipment will be created with 1st available interval for delivery for the given postal code. False
DeliveryEnd DateTime? Date part of this field is ignored. Only time is important. If the value is not null, DeliveryStart must be set as well. Combination of DeliveryStart and DeliveryEnd indicate delivery time frame. Time value for this field should be looked up by calling GetPossibleDateTimesForShipments method. If the value is null shipment will be created with 1st available interval for delivery for the given postal code. False
CodAmount Double? Cash on delivery amount. False
CodCurrency Int32? Currency for the cash on delivery. If CodAmount is null, this field is ignored. See CurrencyEnum for allowed values. False
InsuranceAmount Double? If shipment is insured this field contains insurance amount. False
Currency Int32? Currency for the insurance. If InsuranceAmount is null, this field is ignored. See CurrencyEnum for allowed values. False
RemarkDelivery String 150 Description of delivery usually printed on shipping label. True
RemarkPickup String 150 Description of pickup usually printed on shipping label. True
IsCargo Boolean Flag indicating if the shipment is consisted of pallets instead of boxes. True
ReturnDocument Boolean Flag indicating whether return document exists that is collected upon delivery. True
BillingUnit Int32? If CustomerBillingUnitOverride is set, this field is ignored. See BillingUnitEnum for allowed values and their description. False
ShipmentDocumentData Byte[] PDF document that is merged with the shipping label PDF as a new page. When shipping labels are fetched with later API calls this document is returned as a part of the shipping label. False
ShipmentDocumentExtension String 10 Extension of the document. For now only "PDF" value is allowed. Must be "PDF" if ShipmentDocumentData is not null. False
DropOffParcelShopId String If shipment is to be picked up at Parcel shop, Parcel shop id is passed in this field. False
DeliveryParcelShopId String If shipment is to be delivered to Parcel shop, Parcel shop id is passed in this field. False
ApiKey Guid Authentication API key. True

JSON example:

{
  "ShipmentWeight": null,
  "Collies": [
    {
      "ColliWeight": null,
      "Ref1": "Text value",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RemarkGoods": "Text value",
      "ColliDocumentData": null,
      "ColliDocumentExtension": null
    }
  ],
  "Ref1": "Text value",
  "Ref2": "Text value",
  "Ref3": "Text value",
  "RemarkGoods": "Text value",
  "CountOfBillingUnits": null,
  "ConsigneeName": "Text value",
  "ConsigneePostalCode": "Text value",
  "ConsigneeStreet": "Text value",
  "ConsigneeCity": "Text value",
  "ConsigneeCountryPrefix": "HR",
  "ConsigneeTelephoneNumber": "Text value",
  "ConsigneeFaxNumber": "Text value",
  "ConsigneeGsmNumber": "Text value",
  "ConsigneeEmailAddress": "Text value",
  "SenderName": "Text value",
  "SenderPostalCode": "Text value",
  "SenderStreet": "Text value",
  "SenderCity": "Text value",
  "SenderCountryPrefix": "HR",
  "SenderTelephoneNumber": "Text value",
  "SenderFaxNumber": "Text value",
  "SenderGsmNumber": "Text value",
  "SenderEmailAddress": "Text value",
  "ExpressType": 100,
  "ExWorksType": null,
  "NotificationType": 3,
  "AllowSaturdayDelivery": false,
  "PickupStart": null,
  "PickupEnd": null,
  "DeliveryStart": null,
  "DeliveryEnd": null,
  "CodAmount": null,
  "CodCurrency": null,
  "InsuranceAmount": null,
  "Currency": null,
  "RemarkDelivery": "Text value",
  "RemarkPickup": "Text value",
  "IsCargo": false,
  "ReturnDocument": false,
  "BillingUnit": null,
  "ShipmentDocumentData": null,
  "ShipmentDocumentExtension": null,
  "DropOffParcelShopId": null,
  "DeliveryParcelShopId": null,
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
CreatedShipmentId Int32? Identifier of the created shipment. Value is not null only if the request was valid
Collies List of ResponseColli Value is not null only if the request was valid
PickupStart DateTime? Value is not null only if the request was valid
PickupEnd DateTime? Value is not null only if the request was valid
DeliveryStart DateTime? Value is not null only if the request was valid
DeliveryEnd DateTime? Value is not null only if the request was valid
PriceInformation PriceInformation Value is not null only if the request was valid
ValidPickupIntervals List of TimeInterval Value is not null only if the request was valid
ValidDeliveryIntervals List of TimeInterval Value is not null only if the request was valid
AdditionalInfo AdditionalInfo Value is not null only if the request was valid
ExpectedSenderAddress ExpectedSenderAddress Value is not null only if the request was valid
DeliveryCenterAbbreviation String Delivery center for created shipment. Represents routing information. This must be printed if for some reason client creates own shipping labels and not API's built-in functionality for fetching shipping labels.
TourNumber Int32? Tour number for created shipment. Represents routing information. This must be printed if for some reason client creates own shipping labels and not API's built-in functionality for fetching shipping labels.
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum
ReturnShipment Same as return object for CreateShipment (this method) Used in Shipments with returns (contains examples).

JSON example:

{
  "CreatedShipmentId": 153,
  "Collies": [
    {
      "ColliId": 1,
      "Status": 1,
      "CargoNetColliId": "Text value",
      "BarCode": "Text value",
      "Ref1": "Text value",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RefInt": "Text value"
    }
  ],
  "PickupStart": "2014-09-08T12:00:00+02:00",
  "PickupEnd": "2014-09-08T118:00:00+02:00",
  "DeliveryStart": "2014-09-09T12:00:00+02:00",
  "DeliveryEnd": "2014-09-09T18:00:00+02:00",
  "PriceInformation": {
    "Net": 100.0,
    "Gross": 150.0
  },
  "ValidPickupIntervals": [
    {
      "From": "2014-09-08T12:00:00+02:00",
      "To": "2014-09-08T18:00:00+02:00"
    }
  ],
  "ValidDeliveryIntervals": [
    {
      "From": "2014-09-09T12:00:00+02:00",
      "To": "2014-09-09T18:00:00+02:00"
    }
  ],
  "AdditionalInfo": {
    "DeliveryBefore0830": false,
    "DeliveryBefore1030": false,
    "SaturdayDelivery": false
  },
  "ExpectedSenderAddress": {
    "PostalCode": "Text value",
    "City": "Text value",
    "Street": "Text value"
  },
  "DeliveryCenterAbbreviation": "ZA",
  "TourNumber": 12,
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

UpdateShipment

HTTP method: POST

Method will update shipment information if no labels have been printed for this shipment.

Request

Field name Field type Max length Description Is required
ShipmentId Int32 Identifier of the shipment being updated True
ShipmentWeight Double? Weight of the whole shipment in kilograms. False
Collies List of ComplexShipmentColli List of collies contained in this shipment. True
Ref1 String 35 Value of this field must be unique on a single date. It is printed on a shipping label. True
Ref2 String 35 Value is printed on a shipping label. True
Ref3 String 35 Value is printed on a shipping label. True
RemarkGoods String 150 Description of goods being sent. False
CountOfBillingUnits Double? Count of billing units (e.g if shipment containes 3 small boxes value of this field is 3 and the value of BillingUnit is SBX). False
ConsigneeName String 35 / True
ConsigneePostalCode String 10 / True
ConsigneeStreet String 70 / True
ConsigneeCity String 35 / True
ConsigneeCountryPrefix String 3 HR, AT, BE, CZ, DK, FR, DE, HU, IE, IT, LU, NL, PL, PT, RO, SK, SI, ES, CH, BG True
ConsigneeTelephoneNumber String 30 / False
ConsigneeFaxNumber String 30 / False
ConsigneeGsmNumber String 30 / False
ConsigneeEmailAddress String 70 / False
SenderName String 35 / True
SenderPostalCode String 10 / True
SenderStreet String 70 / True
SenderCity String 35 / True
SenderCountryPrefix String 3 HR True
SenderTelephoneNumber String 30 / False
SenderFaxNumber String 30 / False
SenderGsmNumber String 30 / False
SenderEmailAddress String 70 / False
ExpressType Int32 Indicates until when the shipment should be delivered. See ExpressTypeEnum for allowed values. True
ExWorksType Int32? Null value means that the sender pays for shipping. See ExWorksTypeEnum for allowed values. False
NotificationType Int32 See NotificationTypeEnum for allowed values. True
AllowSaturdayDelivery Boolean / True
PickupStart DateTime? If both date and time are passed the time value should be looked up by calling GetPossibleDateTimesForShipments method. It is possible to pass only date value (with 00:00:00 time) in both pickupStart and pickupEnd fields. In that case shipment will be created with 1st available interval for pickup for the given postal code. False
PickupEnd DateTime? If both date and time are passed the time value should be looked up by calling GetPossibleDateTimesForShipments method. It is possible to pass only date value (with 00:00:00 time) in both pickupStart and pickupEnd fields. In that case shipment will be created with 1st available interval for pickup for the given postal code. False
DeliveryStart DateTime? Date part of this field is ignored. Only time is important. If the value is not null, DeliveryEnd must be set as well. Combination of DeliveryStart and DeliveryEnd indicate delivery time frame. Time value for this field should be looked up by calling GetPossibleDateTimesForShipments method. If the value is null shipment will be created with 1st available interval for delivery for the given postal code. False
DeliveryEnd DateTime? Date part of this field is ignored. Only time is important. If the value is not null, DeliveryStart must be set as well. Combination of DeliveryStart and DeliveryEnd indicate delivery time frame. Time value for this field should be looked up by calling GetPossibleDateTimesForShipments method. If the value is null shipment will be created with 1st available interval for delivery for the given postal code. False
CodAmount Double? Cash on delivery amount. False
CodCurrency Int32? Currency for the cash on delivery. If CodAmount is null, this field is ignored. See CurrencyEnum for allowed values. False
InsuranceAmount Double? If shipment is insured this field contains insurance amount. False
Currency Int32? Currency for the insurance. If InsuranceAmount is null, this field is ignored. See CurrencyEnum for allowed values. False
RemarkDelivery String 150 Description of delivery usually printed on shipping label. True
RemarkPickup String 150 Description of pickup usually printed on shipping label. True
IsCargo Boolean Flag indicating if the shipment is consisted of pallets instead of boxes. True
ReturnDocument Boolean Flag indicating whether return document exists that is collected upon delivery. True
BillingUnit Int32? If CustomerBillingUnitOverride is set, this field is ignored. See BillingUnitEnum for allowed values and their description. False
ShipmentDocumentData Byte[] PDF document that is merged with the shipping label PDF as a new page. When shipping labels are fetched with later API calls this document is returned as a part of the shipping label. False
ShipmentDocumentExtension String 10 Extension of the document. For now only "PDF" value is allowed. Must be "PDF" if ShipmentDocumentData is not null. False
DropOffParcelShopId String If shipment is to be picked up at Parcel shop, Parcel shop id is passed in this field. False
DeliveryParcelShopId String If shipment is to be delivered to Parcel shop, Parcel shop id is passed in this field. False
ApiKey Guid Authentication API key. True

JSON example:

{
  "ShipmentWeight": null,
  "Collies": [
    {
      "ColliWeight": null,
      "Ref1": "Text value",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RemarkGoods": "Text value",
      "ColliDocumentData": null,
      "ColliDocumentExtension": null
    }
  ],
  "Ref1": "Text value",
  "Ref2": "Text value",
  "Ref3": "Text value",
  "RemarkGoods": "Text value",
  "CountOfBillingUnits": null,
  "ConsigneeName": "Text value",
  "ConsigneePostalCode": "Text value",
  "ConsigneeStreet": "Text value",
  "ConsigneeCity": "Text value",
  "ConsigneeCountryPrefix": "HR",
  "ConsigneeTelephoneNumber": "Text value",
  "ConsigneeFaxNumber": "Text value",
  "ConsigneeGsmNumber": "Text value",
  "ConsigneeEmailAddress": "Text value",
  "SenderName": "Text value",
  "SenderPostalCode": "Text value",
  "SenderStreet": "Text value",
  "SenderCity": "Text value",
  "SenderCountryPrefix": "HR",
  "SenderTelephoneNumber": "Text value",
  "SenderFaxNumber": "Text value",
  "SenderGsmNumber": "Text value",
  "SenderEmailAddress": "Text value",
  "ExpressType": 100,
  "ExWorksType": null,
  "NotificationType": 3,
  "AllowSaturdayDelivery": false,
  "PickupStart": null,
  "PickupEnd": null,
  "DeliveryStart": null,
  "DeliveryEnd": null,
  "CodAmount": null,
  "CodCurrency": null,
  "InsuranceAmount": null,
  "Currency": null,
  "RemarkDelivery": "Text value",
  "RemarkPickup": "Text value",
  "IsCargo": false,
  "ReturnDocument": false,
  "BillingUnit": null,
  "ShipmentDocumentData": null,
  "ShipmentDocumentExtension": null,
  "DropOffParcelShopId": null,
  "DeliveryParcelShopId": null,
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
CreatedShipmentId Int32? Identifier of the created shipment. Value is not null only if the request was valid
Collies List of ResponseColli Value is not null only if the request was valid
PickupStart DateTime? Value is not null only if the request was valid
PickupEnd DateTime? Value is not null only if the request was valid
DeliveryStart DateTime? Value is not null only if the request was valid
DeliveryEnd DateTime? Value is not null only if the request was valid
PriceInformation PriceInformation Value is not null only if the request was valid
ValidPickupIntervals List of TimeInterval Value is not null only if the request was valid
ValidDeliveryIntervals List of TimeInterval Value is not null only if the request was valid
AdditionalInfo AdditionalInfo Value is not null only if the request was valid
ExpectedSenderAddress ExpectedSenderAddress Value is not null only if the request was valid
DeliveryCenterAbbreviation String Delivery center for created shipment. Represents routing information. This must be printed if for some reason client creates own shipping labels and not API's built-in functionality for fetching shipping labels.
TourNumber Int32? Tour number for created shipment. Represents routing information. This must be printed if for some reason client creates own shipping labels and not API's built-in functionality for fetching shipping labels.
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "CreatedShipmentId": 153,
  "Collies": [
    {
      "ColliId": 1,
      "Status": 1,
      "CargoNetColliId": "Text value",
      "BarCode": "Text value",
      "Ref1": "Text value",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RefInt": "Text value"
    }
  ],
  "PickupStart": "2014-09-08T12:00:00+02:00",
  "PickupEnd": "2014-09-08T118:00:00+02:00",
  "DeliveryStart": "2014-09-09T12:00:00+02:00",
  "DeliveryEnd": "2014-09-09T18:00:00+02:00",
  "PriceInformation": {
    "Net": 100.0,
    "Gross": 150.0
  },
  "ValidPickupIntervals": [
    {
      "From": "2014-09-08T12:00:00+02:00",
      "To": "2014-09-08T18:00:00+02:00"
    }
  ],
  "ValidDeliveryIntervals": [
    {
      "From": "2014-09-09T12:00:00+02:00",
      "To": "2014-09-09T18:00:00+02:00"
    }
  ],
  "AdditionalInfo": {
    "DeliveryBefore0830": false,
    "DeliveryBefore1030": false,
    "SaturdayDelivery": false
  },
  "ExpectedSenderAddress": {
    "PostalCode": "Text value",
    "City": "Text value",
    "Street": "Text value"
  },
  "DeliveryCenterAbbreviation": "ZA",
  "TourNumber": 12,
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

CreateShipmentWithCustomerBarcode

HTTP method: POST

Method used to create shipments containing the list of collies with customer barcode on each. When using this method the sender infomation must match the data for the API key since it is expected of the sender to print the shipping labels.

Request

Field name Field type Max length Description Is required
ShipmentWeight Double? Weight of the whole shipment in kilograms. False
Collies List of ComplexShipmentColli List of collies contained in this shipment. True
Ref1 String 35 Value of this field must be unique on a single date. It is printed on a shipping label. True
Ref2 String 35 Value is printed on a shipping label. True
Ref3 String 35 Value is printed on a shipping label. True
RemarkGoods String 150 Description of goods being sent. False
CountOfBillingUnits Double? Count of billing units (e.g if shipment containes 3 small boxes value of this field is 3 and the value of BillingUnit is SBX). False
ConsigneeName String 35 / True
ConsigneePostalCode String 10 / True
ConsigneeStreet String 70 / True
ConsigneeCity String 35 / True
ConsigneeCountryPrefix String 3 HR, AT, BE, CZ, DK, FR, DE, HU, IE, IT, LU, NL, PL, PT, RO, SK, SI, ES, CH, BG True
ConsigneeTelephoneNumber String 30 / False
ConsigneeFaxNumber String 30 / False
ConsigneeGsmNumber String 30 / False
ConsigneeEmailAddress String 70 / False
SenderName String 35 / True
SenderPostalCode String 10 / True
SenderStreet String 70 / True
SenderCity String 35 / True
SenderCountryPrefix String 3 HR True
SenderTelephoneNumber String 30 / False
SenderFaxNumber String 30 / False
SenderGsmNumber String 30 / False
SenderEmailAddress String 70 / False
ExpressType Int32 Indicates until when the shipment should be delivered. See ExpressTypeEnum for allowed values. True
ExWorksType Int32? Null value means that the sender pays for shipping. See ExWorksTypeEnum for allowed values. False
NotificationType Int32 See NotificationTypeEnum for allowed values. True
AllowSaturdayDelivery Boolean / True
PickupStart DateTime? If both date and time are passed the time value should be looked up by calling GetPossibleDateTimesForShipments method. It is possible to pass only date value (with 00:00:00 time) in both pickupStart and pickupEnd fields. In that case shipment will be created with 1st available interval for pickup for the given postal code. False
PickupEnd DateTime? If both date and time are passed the time value should be looked up by calling GetPossibleDateTimesForShipments method. It is possible to pass only date value (with 00:00:00 time) in both pickupStart and pickupEnd fields. In that case shipment will be created with 1st available interval for pickup for the given postal code. False
DeliveryStart DateTime? Date part of this field is ignored. Only time is important. If the value is not null, DeliveryEnd must be set as well. Combination of DeliveryStart and DeliveryEnd indicate delivery time frame. Time value for this field should be looked up by calling GetPossibleDateTimesForShipments method. If the value is null shipment will be created with 1st available interval for delivery for the given postal code. False
DeliveryEnd DateTime? Date part of this field is ignored. Only time is important. If the value is not null, DeliveryStart must be set as well. Combination of DeliveryStart and DeliveryEnd indicate delivery time frame. Time value for this field should be looked up by calling GetPossibleDateTimesForShipments method. If the value is null shipment will be created with 1st available interval for delivery for the given postal code. False
CodAmount Double? Cash on delivery amount. False
CodCurrency Int32? Currency for the cash on delivery. If CodAmount is null, this field is ignored. See CurrencyEnum for allowed values. False
InsuranceAmount Double? If shipment is insured this field contains insurance amount. False
Currency Int32? Currency for the insurance. If InsuranceAmount is null, this field is ignored. See CurrencyEnum for allowed values. False
RemarkDelivery String 150 Description of delivery usually printed on shipping label. True
RemarkPickup String 150 Description of pickup usually printed on shipping label. True
IsCargo Boolean Flag indicating if the shipment is consisted of pallets instead of boxes. True
ReturnDocument Boolean Flag indicating whether return document exists that is collected upon delivery. True
BillingUnit Int32? If CustomerBillingUnitOverride is set, this field is ignored. See BillingUnitEnum for allowed values and their description. False
ShipmentDocumentData Byte[] PDF document that is merged with the shipping label PDF as a new page. When shipping labels are fetched with later API calls this document is returned as a part of the shipping label. False
ShipmentDocumentExtension String 10 Extension of the document. For now only "PDF" value is allowed. Must be "PDF" if ShipmentDocumentData is not null. False
DropOffParcelShopId String If shipment is to be picked up at Parcel shop, Parcel shop id is passed in this field. False
DeliveryParcelShopId String If shipment is to be delivered to Parcel shop, Parcel shop id is passed in this field. False
ApiKey Guid Authentication API key. True

JSON example:

{
  "ShipmentWeight": null,
  "Collies": [
    {
      "ColliWeight": null,
      "Ref1": "Text value",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "BarcodeCustomer": "Text value",
      "RemarkGoods": "Text value",
      "ColliDocumentData": null,
      "ColliDocumentExtension": null
    }
  ],
  "Ref1": "Text value",
  "Ref2": "Text value",
  "Ref3": "Text value",
  "RemarkGoods": "Text value",
  "CountOfBillingUnits": null,
  "ConsigneeName": "Text value",
  "ConsigneePostalCode": "Text value",
  "ConsigneeStreet": "Text value",
  "ConsigneeCity": "Text value",
  "ConsigneeCountryPrefix": "HR",
  "ConsigneeTelephoneNumber": "Text value",
  "ConsigneeFaxNumber": "Text value",
  "ConsigneeGsmNumber": "Text value",
  "ConsigneeEmailAddress": "Text value",
  "SenderName": "Text value",
  "SenderPostalCode": "Text value",
  "SenderStreet": "Text value",
  "SenderCity": "Text value",
  "SenderCountryPrefix": "HR",
  "SenderTelephoneNumber": "Text value",
  "SenderFaxNumber": "Text value",
  "SenderGsmNumber": "Text value",
  "SenderEmailAddress": "Text value",
  "ExpressType": 100,
  "ExWorksType": null,
  "NotificationType": 3,
  "AllowSaturdayDelivery": false,
  "PickupStart": null,
  "PickupEnd": null,
  "DeliveryStart": null,
  "DeliveryEnd": null,
  "CodAmount": null,
  "CodCurrency": null,
  "InsuranceAmount": null,
  "Currency": null,
  "RemarkDelivery": "Text value",
  "RemarkPickup": "Text value",
  "IsCargo": false,
  "ReturnDocument": false,
  "BillingUnit": null,
  "ShipmentDocumentData": null,
  "ShipmentDocumentExtension": null,
  "DropOffParcelShopId": null,
  "DeliveryParcelShopId": null,
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
CreatedShipmentId Int32? Identifier of the created shipment. Value is not null only if the request was valid
Collies List of ResponseColli Value is not null only if the request was valid
PickupStart DateTime? Value is not null only if the request was valid
PickupEnd DateTime? Value is not null only if the request was valid
DeliveryStart DateTime? Value is not null only if the request was valid
DeliveryEnd DateTime? Value is not null only if the request was valid
PriceInformation PriceInformation Value is not null only if the request was valid
ValidPickupIntervals List of TimeInterval Value is not null only if the request was valid
ValidDeliveryIntervals List of TimeInterval Value is not null only if the request was valid
AdditionalInfo AdditionalInfo Value is not null only if the request was valid
ExpectedSenderAddress ExpectedSenderAddress Value is not null only if the request was valid
DeliveryCenterAbbreviation String Delivery center for created shipment. Represents routing information. This must be printed if for some reason client creates own shipping labels and not API's built-in functionality for fetching shipping labels.
TourNumber Int32? Tour number for created shipment. Represents routing information. This must be printed if for some reason client creates own shipping labels and not API's built-in functionality for fetching shipping labels.
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum
ReturnShipment Same as return object for CreateShipment (this method) Used in Shipments with returns (contains examples).

JSON example:

{
  "CreatedShipmentId": 153,
  "Collies": [
    {
      "ColliId": 1,
      "Status": 1,
      "CargoNetColliId": "Text value",
      "BarcodeCustomer": "Text value",
      "BarCode": "Text value",
      "Ref1": "Text value",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RefInt": "Text value"
    }
  ],
  "PickupStart": "2014-09-08T12:00:00+02:00",
  "PickupEnd": "2014-09-08T118:00:00+02:00",
  "DeliveryStart": "2014-09-09T12:00:00+02:00",
  "DeliveryEnd": "2014-09-09T18:00:00+02:00",
  "PriceInformation": {
    "Net": 100.0,
    "Gross": 150.0
  },
  "ValidPickupIntervals": [
    {
      "From": "2014-09-08T12:00:00+02:00",
      "To": "2014-09-08T18:00:00+02:00"
    }
  ],
  "ValidDeliveryIntervals": [
    {
      "From": "2014-09-09T12:00:00+02:00",
      "To": "2014-09-09T18:00:00+02:00"
    }
  ],
  "AdditionalInfo": {
    "DeliveryBefore0830": false,
    "DeliveryBefore1030": false,
    "SaturdayDelivery": false
  },
  "ExpectedSenderAddress": {
    "PostalCode": "Text value",
    "City": "Text value",
    "Street": "Text value"
  },
  "DeliveryCenterAbbreviation": "ZA",
  "TourNumber": 12,
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

CancelShipment

HTTP method: POST

Method will cancel the shipment with the passed in shipment id. In order to cancel a shipment a pickup list containing it must not exist.

Request

Field name Field type Max length Description Is required
ShipmentId Int32 / True
ApiKey Guid / True

JSON example:

{
  "ShipmentId": 1,
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
CanceledShipmentId Int32? Identifier of the canceled shipment. Value is not null only if the request was valid
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "CanceledShipmentId": 1,
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

GetShippingLabelsForSingleShipment

HTTP method: POST

Method will return the shipping labels for the passed in shipment id.

Request

Field name Field type Max length Description Is required
ShipmentId Int32 / True
ApiKey Guid / True

JSON example:

{
  "ShipmentId": 1,
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
ShipmentIds List of Int32 Will contain only 1 shipment id
LabelInfo LabelResponse Contains information about shipping labels and the page size used
NumberOfLabels Int32 Number of labels contained on the returned PDF document
PdfDocument Byte[] PDF document that contains all the shipping labels
InvalidShipmentIds List of Int32 Array is not empty if the request wasn't valid. Contains shipment Ids for which shipping labels cannot be returned. Can contain maximum 1 shipment Id for this request
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "ShipmentIds": [
    1
  ],
  "LabelInfo": {
    "PageWidth": 0.0,
    "PageHeight": 0.0,
    "LabelWidth": 0.0,
    "LabelHeight": 0.0,
    "TopMargin": 0.0,
    "SideMargin": 0.0,
    "HorizontalPitch": 0.0,
    "VerticalPitch": 0.0,
    "MaxHorizontalLabels": 1,
    "MaxVerticalLabels": 1
  },
  "NumberOfLabels": 1,
  "PdfDocument": [BYTE ARRAY DATA (ommited because it's not human readable)],
  "InvalidShipmentIds": [
  ],
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

GetShippingLabelsForAllShipments

HTTP method: POST

Method will return the shipping labels document for all the available shipments.

Request

Field name Field type Max length Description Is required
ApiKey Guid / True

JSON example:

{
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
ShipmentIds List of Int32 Shipment Ids of returned shipping labels
LabelInfo LabelResponse Contains information about shipping labels and page size used
NumberOfLabels Int32 Number of labels contained on the returned PDF document
PdfDocument Byte[] PDF document that contains all the shipping labels
InvalidShipmentIds List of Int32 Will always be empty for this request
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "ShipmentIds": [
    4, 
    32,
    58
  ],
  "LabelInfo": {
    "PageWidth": 0.0,
    "PageHeight": 0.0,
    "LabelWidth": 0.0,
    "LabelHeight": 0.0,
    "TopMargin": 0.0,
    "SideMargin": 0.0,
    "HorizontalPitch": 0.0,
    "VerticalPitch": 0.0,
    "MaxHorizontalLabels": 1,
    "MaxVerticalLabels": 1
  },
  "NumberOfLabels": 1,
  "PdfDocument": [BYTE ARRAY],
  "InvalidShipmentIds": [
  ],
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

GetShippingLabelsForShipments

HTTP method: GET

Method will return the shipping labels document for the shipment ids passed to the method.

Request

Field name Field type Max length Description Is required
ShipmentIds List of Int32 Array of shipment Ids to get shipping labels for True
ApiKey Guid / True

JSON example:

{
  "ShipmentIds": [
    1,
    5
  ],
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
ShipmentIds List of Int32 Shipment Ids of returned shipping labels
LabelInfo LabelResponse Contains information about shipping labels and page size used
NumberOfLabels Int32 Number of labels contained on the returned PDF document
PdfDocument Byte[] PDF document that contains all the shipping labels
InvalidShipmentIds List of Int32 Array is not empty if the request wasn't valid. Contains shipment Ids for which shipping labels cannot be returned. Can contain 1 or more shipment Ids. No shipping labels will be returned if this array is not empty
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "ShipmentIds": [
    1,
    5
  ],
  "LabelInfo": {
    "PageWidth": 0.0,
    "PageHeight": 0.0,
    "LabelWidth": 0.0,
    "LabelHeight": 0.0,
    "TopMargin": 0.0,
    "SideMargin": 0.0,
    "HorizontalPitch": 0.0,
    "VerticalPitch": 0.0,
    "MaxHorizontalLabels": 1,
    "MaxVerticalLabels": 1
  },
  "NumberOfLabels": 2,
  "PdfDocument": [BYTE ARRAY],
  "InvalidShipmentIds": [
  ],
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

RequestPickup

HTTP method: POST

Method will return the pickup list identifier along with the pickup list document for all shipments that are available for pickup.

Request

Field name Field type Max length Description Is required
ApiKey Guid / True

JSON example:

{
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
PickupId Int32? Identifier of pickup in Shipping API
PickupListDocument Byte[] PDF document that contains pickup list
ColliInfo List of ColliInfoForPickupResponse /
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "PickupId": null,
  "PickupListDocument": [BYTE ARRAY],
  "ColliInfo": [
    {
      "ColliId": 1,
      "CargoNetColliId": "Text value",
      "Ref1": "Text value",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RefInt": "Text value"
    }
  ],
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

RequestPickupForShipments

HTTP method: POST

Method will return the pickup list identifier along with the pickup list document for all shipment ids passed to the method.

Request

Field name Field type Max length Description Is required
ShipmentIds List of Int32 / True
ApiKey Guid / True

JSON example:

{
  "ShipmentIds": [
    1,
    5
  ],
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
PickupId Int32? Identifier of pickup in Shipping API
PickupListDocument Byte[] PDF document that contains pickup list
ColliInfo List of ColliInfoForPickupResponse /
InvalidShipmentIds List of Int32 Array is not empty if the request wasn't valid. Contains shipment Ids for which shipping labels cannot be returned. Can contain 1 or more shipment Ids. No shipping labels will be returned if this object is not empty
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "PickupId": 652,
  "PickupListDocument": [BYTE ARRAY],
  "ColliInfo": [
    {
      "ColliId": 1,
      "CargoNetColliId": "Text value",
      "Ref1": "Text value",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RefInt": "Text value"
    }
  ],
  "InvalidShipmentIds": [
  ],
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

GetPickupListContainingColli

HTTP method: GET

Method will return the pickup list identifier along with the pickup list document containing the colli id passed to the method.

Request

Field name Field type Max length Description Is required
ColliId Int32 / True
ApiKey Guid / True

Response

Field name Field type Description
PickupId Int32? If response is valid, this field contains Shipping API pickup identifier
PickupListDocument Byte[] PDF document containing pickup list
ColliInfo List of ColliInfoForPickupResponse /
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "PickupId": 231,
  "PickupListDocument": [BYTE ARRAY],
  "ColliInfo": [
    {
      "ColliId": 1,
      "CargoNetColliId": "Text value",
      "Ref1": "Text value",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RefInt": "Text value"
    }
  ],
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

GetPossibleDateTimesForShipments

HTTP method: GET

Method will return the possible pickup and delivery times for shipment data. One of these intervals should be used when creating shipment through the API.

Request

Field name Field type Max length Description Is required
PickupDate DateTime? Date of pickup. Time part is ignored. If null is passed, first possible date is taken. False
PickupCountryPrefix String 3 Local country prefix (e.g HR). If null is passed, default value from system config is used False
PickupPostalCode String 10 / True
PickupCity String 35 / False
DeliveryCountryPrefix String 3 If null is passed, default value from system config is used False
DeliveryPostalCode String 10 / True
DeliveryCity String 35 / False
OverseasPrintsShippingLabels Boolean Flag indicating whether shipper prints shipping labels. If true, PickupDate field should be at least one day in the future if it was not passed as null. True
ApiKey Guid / True

Response

Field name Field type Description
PossibleDateTimes List of PossibleDateTimeForShipment /
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "PossibleDateTimes": [
    {
      "PickupPostalCode": "Text value",
      "PickupCity": "Text value",
      "DeliveryPostalCode": "Text value",
      "DeliveryCity": "Text value",
      "AvailablePickupIntervals": [
        {
          "From": "2014-09-08T15:07:59.7947882+02:00",
          "To": "2014-09-08T15:07:59.7947882+02:00"
        }
      ],
      "AvailableDeliveryIntervals": [
        {
          "From": "2014-09-08T15:07:59.7947882+02:00",
          "To": "2014-09-08T15:07:59.7947882+02:00"
        }
      ],
      "AdditionalInfo": {
        "DeliveryBefore0830": false,
        "DeliveryBefore1030": false,
        "SaturdayDelivery": false
      }
    }
  ],
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

GetLocations

HTTP method: GET

Method will return all postal codes containing the passed in string. The string can be either the postal code or city name.

Request

Field name Field type Max length Description Is required
PostalCodeOrName String 35 City or postal code have to be passed here True
ApiKey Guid / True

Response

Field name Field type Description
PostalLocations List of ResponsePostalLocation /
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "PostalLocations": [
    {
      "Name": "Text value",
      "PostalCode": "Text value"
    }
  ],
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

GetAllPickupAndDeliveryIntervals

HTTP method: GET

Method will return all the pickup and delivery postal codes along with the available time intervals. Should be used if this data wants to be stored locally, this information is not volatile and an update interval of one day is recommended.

Request

Field name Field type Max length Description Is required
ApiKey Guid / True

Response

Field name Field type Description
Intervals List of PostalLocationInfo /
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "Intervals": [
    {
      "Name": "Text value",
      "PostalCode": "Text value",
      "PickupTimeIntervals": [
        {
          "From": "2014-09-08T15:07:59.8137901+02:00",
          "To": "2014-09-08T15:07:59.8137901+02:00"
        }
      ],
      "DeliveryTimeIntervals": [
        {
          "From": "2014-09-08T15:07:59.8147902+02:00",
          "To": "2014-09-08T15:07:59.8147902+02:00"
        }
      ]
    }
  ],
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

GetParcelShops

HTTP method: GET

Method will return all parcel shops.

Request

Field name Field type Max length Description Is required
ApiKey Guid / True

Response

Field name Field type Description
ParcelShops List of ResponseParcelShop /
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "ParcelShops": [
    {
      "Id": 123,
      "Name": "MyShop MS646",
      "Latitude": "32.908017",
      "Longitude": "12.983954",
      "Address": "Some street 22",
      "PostalCode": "99999",
      "City": "MS646",
      "Description": "",
      "GlobalLocationNumber": "MS646",
      "LocationId": "99999999",
      "WorkingHoursDescription": "Work days: 6:30 do 20:30\r\nSaturdays: 7:00 do 14:30"
    }
  ],
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

GetPriceInformation

HTTP method: POST

Method used to check for shipment price information. Can easily be used to preview the shipping costs for a customer.

Request

Field name Field type Max length Description Is required
PickupDate DateTime Only date part is relevant True
SenderPostalCode String 10 / True
SenderCountryPrefix String 3 / True
ConsigneePostalCode String 10 / True
ConsigneeCountryPrefix String 3 / True
BillingUnit Int32? See BillingUnitEnum for available values. If CustomerBillingUnitOverride is set, this field is ignored False
ShipmentWeight Double? / False
CountOfBillingUnits Double? / False
CodAmount Double? / False
ExWorksType Int32? null value means sender is paying for shipping False
InsuranceAmount Double? / False
ReturnDocument Boolean? / False
ExpressType Int32? See ExpressTypeEnum for available values False
AllowSaturdayDelivery Boolean? / False
IsCargo Boolean? Flag indicating whether the shipment is consisted of pallets False
NumberOfCollies Int32? / False
Collies List of PriceInformationColli / True
ApiKey Guid / True

Response

Field name Field type Description
PriceInformation PriceInformation /
BillingUnit Int32? See BillingUnitEnum for available values
CountOfBillingUnits Double? /
NumberOfCollies Int32? /
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "PriceInformation": {
    "Net": 0.0,
    "Gross": 0.0
  },
  "BillingUnit": null,
  "CountOfBillingUnits": null,
  "NumberOfCollies": null,
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

GetActiveShipments

HTTP method: GET

Method that returns all non failed, non picked up shipments for an API key.

Request

Field name Field type Max length Description Is required
ApiKey Guid / True

Response

Field name Field type Description
Shipments List of ResponseShipment /
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "Shipments": [
    {
      "ShipmentId": 1,
      "Status": 1,
      "DateCreated": "2014-09-08T15:07:59.8287916+02:00",
      "StatusDate": "2014-09-08T15:07:59.8287916+02:00",
      "ReturnDocument": false,
      "CargoNetShipmentId": "Text value",
      "PriceInformation": {
        "Net": 0.0,
        "Gross": 0.0
      },
      "Collies": [
        {
          "ColliId": 1,
          "Status": 1,
          "CargoNetColliId": "Text value",
          "BarCode": "Text value",
          "Ref1": "Text value",
          "Ref2": "Text value",
          "Ref3": "Text value",
          "RefInt": "Text value"
        }
      ],
      "Traces": [
        {
          "ParcelNumber": "Text value",
          "ScanDate": "2014-09-08T15:07:59.8287916+02:00",
          "ScanTime": "2014-09-08T15:07:59.8287916+02:00",
          "StatusNumber": 1,
          "StatusDescription": "Text value",
          "CenterName": "Text value",
          "Remark": "Text value"
        }
      ]
    }
  ],
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

CreateApiKey

HTTP method: POST

Method to create new API keys. The API key used to call this method must have the CanAdministrateApiKeys permission, also the field CanAdministrateApiKeys sets this permission for the newly created API key.

Request

Field name Field type Max length Description Is required
LogoImageExtension_S String 10 Only picture formats are allowed (PNG, JPG, BMP). Required if LogoImageData_S is not null False
LogoImageData_S Byte[] Small logo image for the new api key. If parameter is null, new api key will inherit the logo image of the current api key False
LogoImageExtension_M String 10 Only picture formats are allowed (PNG, JPG, BMP). Required if LogoImageData_M is not null False
LogoImageData_M Byte[] Medium logo image for the new api key. If parameter is null, new api key will inherit the logo image of the current api key False
LogoImageExtension_L String 10 Only picture formats are allowed (PNG, JPG, BMP). Required if LogoImageData_L is not null False
LogoImageData_L Byte[] Large logo image for the new api key. If parameter is null, new api key will inherit the logo image of the current api key True
IsActive Boolean Indicates whether the api key is allowed to make requests True
Description String 150 / True
PickupPostalCode String 10 / True
PickupCity String 10 / True
PickupStreet String 10 / True
CanAdministrateApiKeys Boolean Indicates if the api key will have administrative privileges (create/edit other keys) True
ApiKey Guid / True

JSON example:

{
  "LogoImageExtension_S": "Text value",
  "LogoImageData_S": [BYTE_ARRAY],
  "LogoImageExtension_M": "Text value",
  "LogoImageData_M": [BYTE_ARRAY],
  "LogoImageExtension_L": "Text value",
  "LogoImageData_L": [BYTE_ARRAY],
  "IsActive": false,
  "Description": "Text value",
  "PickupPostalCode": "Text value",
  "PickupCity": "Text value",
  "PickupStreet": "Text value",
  "CanAdministrateApiKeys": false,
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
CreatedApiKeyId Int32? Newly created api key id. Null if request is not valid
CreatedApiKeyValue Guid? Newly created api key value. Null if request is not valid
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "CreatedApiKeyId": 512,
  "CreatedApiKeyValue": 00000000-0000-0000-0000-000000000000,
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

UpdateApiKey

HTTP method: POST

Method to update values of an existing API key. The API key used to call this method must have the CanAdministrateApiKeys permission.

Request

Field name Field type Max length Description Is required
UpdatedApiKeyValue Guid Api key value being updated True
LogoImageExtension_S String 10 Only picture formats are allowed (PNG, JPG, BMP). Required if LogoImageData_S is not null False
LogoImageData_S Byte[] Small logo image for the new api key. If parameter is null, new api key will inherit the logo image of the current api key False
LogoImageExtension_M String 10 Only picture formats are allowed (PNG, JPG, BMP). Required if LogoImageData_M is not null False
LogoImageData_M Byte[] Medium logo image for the new api key. If parameter is null, new api key will inherit the logo image of the current api key False
LogoImageExtension_L String 10 Only picture formats are allowed (PNG, JPG, BMP). Required if LogoImageData_L is not null False
LogoImageData_L Byte[] Large logo image for the new api key. If parameter is null, new api key will inherit the logo image of the current api key True
IsActive Boolean Indicates whether the api key is allowed to make requests True
Description String 150 / True
PickupPostalCode String 10 / True
PickupCity String 10 / True
PickupStreet String 10 / True
CanAdministrateApiKeys Boolean Indicates if the api key will have administrative privileges (create/edit other keys) True
ApiKey Guid / True

JSON example:

{
  "LogoImageExtension_S": "Text value",
  "LogoImageData_S": [BYTE_ARRAY],
  "LogoImageExtension_M": "Text value",
  "LogoImageData_M": [BYTE_ARRAY],
  "LogoImageExtension_L": "Text value",
  "LogoImageData_L": [BYTE_ARRAY],
  "IsActive": false,
  "Description": "Text value",
  "PickupPostalCode": "Text value",
  "PickupCity": "Text value",
  "PickupStreet": "Text value",
  "CanAdministrateApiKeys": false,
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}

Response

Field name Field type Description
CreatedApiKeyId Int32? Updated api key id. Null if request is not valid
CreatedApiKeyValue Guid? Updated api key value. Null if request is not valid
IsValid Boolean Value of this field is indicating if the request was successful. If value is 'false', see ValidationErrors and ModelErrors fields for more information.
ModelErrors Dictionary with key as String and value as String This dicionary will contain errors regarding request fields. E.g If a value is required but not passed that error will be contained here. Key is the name of the required field and value is something like 'Field xxx is required'
ValidationErrors List of Int32 Values in this list are from CoreValidationExceptionCode enum

JSON example:

{
  "CreatedApiKeyId": 512,
  "CreatedApiKeyValue": 00000000-0000-0000-0000-000000000000,
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

Complex types used in request/response objects

ComplexShipmentColli

Field name Field type Max length Description Is required
ColliWeight Double? / False
Ref1 String 35 Unique Colli identifier should be passed in this field. It is later printed on the shipping label True
Ref2 String 35 / True
Ref3 String 35 / True
BarcodeCustomer String 35 Customer barcode False
RemarkGoods String 150 Description of goods being sent True
ColliDocumentData Byte[] PDF document to be sent with the shipment's colli False
ColliDocumentExtension String 30 Extension of the document. Must be "PDF" if ColliDocumentData is not null False
IsReturnColli Boolean Indicating if colli is return shipment colli. See Shipments with returns False

JSON example:

{
  "ColliWeight": null,
  "Ref1": "Text value",
  "Ref2": "Text value",
  "Ref3": "Text value",
  "BarcodeCustomer": "Text value",
  "RemarkGoods": "Text value",
  "ColliDocumentData": null,
  "ColliDocumentExtension": null,
  "IsReturnColli": false
}

PriceInformationColli

Field name Field type Max length Description Is required
ColliWeight Double / True

JSON example:

{
  "ColliWeight": 0.0
}

AdditionalInfo

Field name Field type Max length Description Is required
DeliveryBefore0830 Boolean / True
DeliveryBefore1030 Boolean / True
SaturdayDelivery Boolean / True

JSON example:

{
  "DeliveryBefore0830": false,
  "DeliveryBefore1030": false,
  "SaturdayDelivery": false
}

ColliInfoForPickupResponse

Field name Field type Max length Description Is required
ColliId Int32 / True
CargoNetColliId String 8 / True
Ref1 String 35 / True
Ref2 String 35 / False
Ref3 String 35 / False
RefInt String 35 / False

JSON example:

{
  "ColliId": 1,
  "CargoNetColliId": "Text value",
  "Ref1": "Text value",
  "Ref2": "Text value",
  "Ref3": "Text value",
  "RefInt": "Text value"
}

ExpectedSenderAddress

Field name Field type Max length Description Is required
PostalCode String 10 / False
City String 25 / False
Street String 70 / False

JSON example:

{
  "PostalCode": "Text value",
  "City": "Text value",
  "Street": "Text value"
}

LabelResponse

Field name Field type Max length Description Is required
PageWidth Double / True
PageHeight Double / True
LabelWidth Double / True
LabelHeight Double / True
TopMargin Double / True
SideMargin Double / True
HorizontalPitch Double / True
VerticalPitch Double / True
MaxHorizontalLabels Int32 / True
MaxVerticalLabels Int32 / True

JSON example:

{
  "PageWidth": 0.0,
  "PageHeight": 0.0,
  "LabelWidth": 0.0,
  "LabelHeight": 0.0,
  "TopMargin": 0.0,
  "SideMargin": 0.0,
  "HorizontalPitch": 0.0,
  "VerticalPitch": 0.0,
  "MaxHorizontalLabels": 1,
  "MaxVerticalLabels": 1
}

PossibleDateTimeForShipment

Field name Field type Max length Description Is required
PickupPostalCode String 30 / True
PickupCity String 30 / True
DeliveryPostalCode String 30 / True
DeliveryCity String 30 / True
AvailablePickupIntervals List of TimeInterval / True
AvailableDeliveryIntervals List of TimeInterval / True
AdditionalInfo AdditionalInfo / True

JSON example:

{
  "PickupPostalCode": "Text value",
  "PickupCity": "Text value",
  "DeliveryPostalCode": "Text value",
  "DeliveryCity": "Text value",
  "AvailablePickupIntervals": [
    {
      "From": "2014-09-08T15:23:38.596659+02:00",
      "To": "2014-09-08T15:23:38.596659+02:00"
    }
  ],
  "AvailableDeliveryIntervals": [
    {
      "From": "2014-09-08T15:23:38.596659+02:00",
      "To": "2014-09-08T15:23:38.596659+02:00"
    }
  ],
  "AdditionalInfo": {
    "DeliveryBefore0830": false,
    "DeliveryBefore1030": false,
    "SaturdayDelivery": false
  }
}

PostalLocationInfo

Field name Field type Max length Description Is required
Name String 30 / True
PostalCode String 30 / True
PickupTimeIntervals List of TimeInterval / True
DeliveryTimeIntervals List of TimeInterval / True

JSON example:

{
  "Name": "Text value",
  "PostalCode": "Text value",
  "PickupTimeIntervals": [
    {
      "From": "2014-09-08T15:23:38.596659+02:00",
      "To": "2014-09-08T15:23:38.596659+02:00"
    }
  ],
  "DeliveryTimeIntervals": [
    {
      "From": "2014-09-08T15:23:38.596659+02:00",
      "To": "2014-09-08T15:23:38.596659+02:00"
    }
  ]
}

PriceInformation

Field name Field type Max length Description Is required
Net Double Price without tax True
Gross Double Price with tax True

JSON example:

{
  "Net": 0.0,
  "Gross": 0.0
}

ResponseColli

Field name Field type Max length Description Is required
ColliId Int32 / True
Status Int32 See ColliStatusEnum for allowed values True
CargoNetColliId String 8 CargoNetId - it will be null if parent shipment is in status Pending or Failed False
BarCode String 16 Barcode - it will be null unless parent shipment was processed False
Ref1 String 35 / True
Ref2 String 35 / False
Ref3 String 35 / False
RefInt String 35 / False
MultifunctionalBarcode String Used in special cases when Shipping API consumer prints own shipping labels and not using API's built-in functionality for shipping label fetching. Code128B specification should be used for first 8 characters and Code128C for the rest. If shipping label is not too small, using Code128B for the entire barcode should suffice (since this generates larger barcode image). False
Services String String representation of services applied to this colli. Used in special cases when Shipping API consumer prints own shipping labels and not using API's built-in functionality for shipping label fetching. False

JSON example:

{
  "ColliId": 1,
  "Status": 1,
  "CargoNetColliId": "Text value",
  "BarCode": "Text value",
  "Ref1": "Text value",
  "Ref2": "Text value",
  "Ref3": "Text value",
  "RefInt": "Text value",
  "MultifunctionalBarcode": "Text value",
  "Services": "Text value"
}

ResponsePostalLocation

Field name Field type Max length Description Is required
Name String 30 / True
PostalCode String 30 / True

JSON example:

{
  "Name": "Text value",
  "PostalCode": "Text value"
}

ResponseParcelShop

Field name Field type Max length Description Is required
Id Int32 / True
Name String / True
Latitude Double / True
Longitude Double / True
Address String / True
PostalCode String / True
City String / True
Description String / True
GlobalLocationNumber String / True
LocationId String / True
WorkingHoursDescription String Human readable plain text describing working hours of this parcel shop True

JSON example:

{
  "Id": 123,
  "Name": "MyShop MS646",
  "Latitude": "32.908017",
  "Longitude": "12.983954",
  "Address": "Some street 22",
  "PostalCode": "99999",
  "City": "MS646",
  "Description": "",
  "GlobalLocationNumber": "MS646",
  "LocationId": "99999999",
  "WorkingHoursDescription": "Work days: 6:30 do 20:30\r\nSaturdays: 7:00 do 14:30"
}

ResponseShipment

Field name Field type Max length Description Is required
ShipmentId Int32 / True
Status Int32 / True
DateCreated DateTime / True
StatusDate DateTime / True
ReturnDocument Boolean / True
CargoNetShipmentId String 30 / True
PriceInformation PriceInformation / True
Collies List of ResponseColli / True
Traces List of ResponseTrace / True
DeliveryCenterAbbreviation String Delivery center for created shipment. Represents routing information. This must be printed if for some reason client creates own shipping labels and not API's built-in functionality for fetching shipping labels. False
TourNumber Int32? Tour number for created shipment. Represents routing information. This must be printed if for some reason client creates own shipping labels and not API's built-in functionality for fetching shipping labels. False

JSON example:

{
  "ShipmentId": 1,
  "Status": 1,
  "DateCreated": "2014-09-08T15:23:38.5976591+02:00",
  "StatusDate": "2014-09-08T15:23:38.5976591+02:00",
  "ReturnDocument": false,
  "CargoNetShipmentId": "Text value",
  "PriceInformation": {
    "Net": 0.0,
    "Gross": 0.0
  },
  "Collies": [
    {
      "ColliId": 1,
      "Status": 1,
      "CargoNetColliId": "Text value",
      "BarCode": "Text value",
      "Ref1": "Text value",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RefInt": "Text value"
    }
  ],
  "Traces": [
    {
      "ParcelNumber": "Text value",
      "ScanDate": "2014-09-08T15:23:38.5976591+02:00",
      "ScanTime": "2014-09-08T15:23:38.5976591+02:00",
      "StatusNumber": 1,
      "StatusDescription": "Text value",
      "CenterName": "Text value",
      "Remark": "Text value"
    }
  ],
  "DeliveryCenterAbbreviation": "ZA",
  "TourNumber": 12
}

ResponseTrace

Field name Field type Max length Description Is required
ParcelNumber String 30 / True
ScanDate DateTime / True
ScanTime DateTime / True
StatusNumber Int32 / True
StatusDescription String 30 / True
CenterName String 30 / True
Remark String 30 / True

JSON example:

{
  "ParcelNumber": "Text value",
  "ScanDate": "2014-09-08T15:23:38.5976591+02:00",
  "ScanTime": "2014-09-08T15:23:38.5976591+02:00",
  "StatusNumber": 1,
  "StatusDescription": "Text value",
  "CenterName": "Text value",
  "Remark": "Text value"
}

TimeInterval

Field name Field type Max length Description Is required
From DateTime / True
To DateTime / True

JSON example:

{
  "From": "2014-09-08T15:23:38.5976591+02:00",
  "To": "2014-09-08T15:23:38.5976591+02:00"
}

Enums (constant values) used in request/response objects

If, in request or response object, field type is one of these enumerations, Int32 value of the enum member should be passed. If a field is marked as nullable (has '?' behind type name), a null value can still be passed. For example, CreateShipmentPlainRequest object has both, a field that takes a nullable ExWorksTypeEnum value and a field that takes ExpressTypeEnum value. When invoking CreateShipmentPlain API method, these values should be one of the Int32 values contained in these enum members, or null for ExWorksTypeEnum field, since it is marked as nullable (not required).

ExWorksTypeEnum

Value (Int32) Name Description
4 ExWorks Consignee pays for the shipping
44 CashPrepaid Shipping fee is prepaid

ExpressTypeEnum

Value (Int32) Name Description
21 T1030 Delivery until 10:30
22 T0830 Delivery until 08:30
100 EoBD Delivery until the end of business day

NotificationTypeEnum

Value (Int32) Name Description
0 None /
1 AutomaticViaEmail /
2 AutomaticViaSms /
3 Both /

ShipmentStatusEnum

Value (Int32) Name Description
1 Pending /
2 Successful /
3 Failed /
4 DataDefined /
5 Canceled /
6 AwaitingPickup /
7 PickupInitiated /
8 PartiallyPrinted /
11 PickupInitiatedWhilePending /

ColliStatusEnum

Value (Int32) Name Description
1 NoPrinting /
2 AwaitingPrint /
3 Printed /
4 MarkedForNoPrint /

CurrencyEnum

Value (Int32) Name Description
0 National /
1 Euro /

BillingUnitEnum

Value (Int32) Name Description
12 LETT Letter
13 SBX Small box
14 MBX Medium box
15 LBX Large box
16 XLBX Extra large box

CoreValidationExceptionCode

Value (Int32) Name Description
10000 InvalidApiKey /
10001 PickupFromAndToDateMismatch /
10002 PickupFromMustBeLesserThanTo /
10003 PickupNotPossibleOnDate /
10004 PickupInvalidInterval /
10005 DeliveryFromMustBeLesserThanTo /
10006 DeliveryInvalidInterval /
10007 ShipmentNotfound /
10008 ConsigneePostalCodeAndCityInvalidCombination /
10009 SenderPostalCodeAndCityInvalidCombination /
10010 NonFailedShipmentWithRef1AndPickupDateAlreadyExists /
10011 UnsupportedBillingUnit /
10012 CountOfBillingUnitsMustBeSet /
10013 ExpectedSenderAddressDoesntMatch /
10014 PickupInvalidPostalCode /
10015 DeliveryInvalidPostalCode /
10016 CutoffTimePassed /
10017 NoActiveLabelLayoutSetting /
10018 CannotUseOexPackaging /
10019 NoShipmentsForPickupFound /
10020 NoDataDefinedShipmentsFound /
10021 DeliveryInvalidExpressType /
10022 InvalidExWorksType /
10023 ExpressDeliveryNotAvailableForCargo /
10024 ColliesOrNumberOfColliesMustBeSent /
10025 ServiceNotAvailableForSenderPostalCode /
10026 ServiceNotAvailableForConsigneePostalCode /
10027 UnsupportedSenderCountryPrefix /
10028 UnsupportedConsigneeCountryPrefix /
10029 BothSenderAndConsigneeCannotContainInternationalCountryPrefixes /
10030 UnsupportedFormatOfShipmentDocument /
10031 UnsupportedFormatOfColliDocument /
10032 NoPostalLocationsFound /
10033 CannotUpdateShipment /
10034 PickupNotYetRequestedForShipment /
10035 PickupNotYetRequestedForColli /
10036 UnsupportedSearchByRefType /
10037 InvalidIBAN /
10038 ColliWithCustomerBarcodeAndPickupDateAlreadyExists /
10039 PickupListDoesNotExist /
10500 InvalidExpressType /
11000 ApiKeyNotAuthorizedToRequestEuroplate /
11001 ShipmentNotValidForEuroplatePrinting /
11002 InvalidShipmentStatusForEuroplatePrinting /
11003 ColliWeightIsGreaterThanMaxAllowedColliWeight /
11004 InsufficientConsigneeData /
11005 ColliWeightIsZero /
15000 ApiKeyNotAuthorizedToAdministrateApiKeys /
15001 PostalCodeAndCityInvalidCombination /
15002 InvalidLogoImageData /
15003 ApiKeyNotFound /
15004 CannotRemoveAdministrationPrivileges /
16000 ApiKeyCannotUseShipmentsWithReturns /
16001 CannotUseParcelShopsIfShipmentContainsPickCollies /
16002 ExpectedReturnShipmentConsigneeDoesntMatch /
16003 PickupAndDeliveryDatesMustBeNullWhenCreatingShipmentWithReturn /
16004 ShipmentWithReturnCannotUseCashOnDeliveryService /
16005 NoActiveLabelLayoutSettingForReturnShipment /
16006 FetchingLabelForColliInReturnShipmentIsNotAllowed /
16007 ColliInReturnShipmentCannotBeMarkedForNoPrint /
16008 CannotGetPickupListForReturnShipmentColli /
16009 EndpointDoesNotSupportShipmentsWithReturns /
16010 ReturnShipmentsCannotBeCancelledDirectly /
20000 UnknownError /
20001 ApiKeyFailedToSerialize /
20002 SystemMaintenance /

Using XML for data exchange

It is possible to use XML structure in Shipping API data exchange. By default, all the responses from Shipping API are JSON formatted. To explicitly request XML response just add a query parameter "response=xml" at the end of API endpoint URL (e.g "http://api.shippingapi.com/api/data/CreateShipmentPlain?response=xml"). When making a GET or POST request using XML consult List of API methods section for the list of objects and their fields. Note that, regardless of format (XML or JSON) used, GET requests are always made passing the parameters in URL query (e.g "http://api.shippingapi.com/api/data/GetShipmentStatusByShipmentId?ApiKey=A75A955B-2C0F-4D22-89DD-1A10717E692E&ShipmentId=1028&response=xml"), while POST requests are passed in the request body as XML or JSON. Examples for Shipping API CreateShipment method request (POST) and response in XML follow:

Request (POST)

<?xml version="1.0" encoding="utf-8"?>
<Request>
  <ApiKey>A75A955B-2C0F-4D22-89DD-1A10717E692E</ApiKey>
  <ConsigneeName>Ivan Horvat</ConsigneeName>
  <ConsigneePostalCode>23000</ConsigneePostalCode>
  <ConsigneeStreet>G. Budislavića 89</ConsigneeStreet>
  <ConsigneeCity>Zadar</ConsigneeCity>
  <SenderName>Marko Marković</SenderName>
  <SenderPostalCode>10000</SenderPostalCode>
  <SenderStreet>Ulica grada Vukovara 123</SenderStreet>
  <SenderCity>Zagreb</SenderCity>
  <ExpressType>100</ExpressType>
  <Collies>
    <Ref1>First colli ref1</Ref1>
  </Collies>
  <Collies>
    <Ref1>Second colli ref1</Ref1>
  </Collies>
</Request>

Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
    <CreatedShipmentId>6992</CreatedShipmentId>
    <Collies>
        <ColliId>12840</ColliId>
        <Status>2</Status>
        <CargoNetColliId>35056994</CargoNetColliId>
        <BarCode>1910013505699414</BarCode>
        <Ref1>First colli ref1</Ref1>
        <Ref2 />
        <Ref3 />
        <RefInt />
    </Collies>
    <Collies>
        <ColliId>12841</ColliId>
        <Status>2</Status>
        <CargoNetColliId>35056995</CargoNetColliId>
        <BarCode>1910013505699513</BarCode>
        <Ref1>Second colli ref1</Ref1>
        <Ref2 />
        <Ref3 />
        <RefInt />
    </Collies>
    <PickupStart>2014-09-18T08:00:00</PickupStart>
    <PickupEnd>2014-09-18T20:00:00</PickupEnd>
    <DeliveryStart>2014-09-19T08:00:00</DeliveryStart>
    <DeliveryEnd>2014-09-19T17:00:00</DeliveryEnd>
    <PriceInformation>
        <Net>0</Net>
        <Gross>0</Gross>
    </PriceInformation>
    <ValidPickupIntervals />
    <ValidDeliveryIntervals />
    <AdditionalInfo />
    <ExpectedSenderAddress />
    <IsValid>true</IsValid>
    <ModelErrors />
    <ValidationErrors />
</Response>

Shipments with returns

When business process dictates a scenario in which it is necessary to deliver something and pick something up on the same address, shipments with returns can be used.

Process is consisted of the following:

  1. API consumer creates shipment defining which collies are to be delivered and which collies are to be picked-up.
  2. System automatically creates two shipments; one from API consumer to the recipient (consignee) and one from recipient (consignee [which becomes sender in this shipment]) back to the API consumer (or third party if allowed by API administrator).
  3. API consumer prints shipping labels for shipment from himself to the recipient (consignee) and among those labels there are shipping labels for the second shipment (from consignee back to the API consumer) that are sent with the original shipment so consignee can use them for return shipment.

There can be two scenarios when using shipments with returns:

  1. API consumer wants something delivered and something returned.
  2. API consumer wants something returned.

These scenarios are basically the same, with one minor difference; first one has collies that need to be delivered + a single colli containing shipping label(s) for return shipment. Second scenario has only single colli with shipping label(s) for return.

Usage

To use shipments with return, API administrator needs to allow that option for API consumer's API key. Once allowed, consumer can create shipment with returns using CreateShipment method as he normally would with a few minor changes:

  1. Sender data in that shipment is address data of pick-up location and consignee data is API consumer's address data (or third party if allowed by API administrator), basically the same as creating a normal pick-up shipment
  2. Shipment needs to have at least one return colli defined (IsReturnColli set to true). Return colli is part of a return shipment, representing something API consumer wants returned. See ComplexShipmentColli.

This results in creation of two shipments:

  1. API consumer -> consignee,
  2. Consignee -> API consumer (or third party if allowed by API administrator)

and response object, besides normal CreateShipment response, contains return shipment data stored in ReturnShipment field.

Using shipments with return has following limitations:

  • Informative price calculation is not supported and PriceInformation field in response is always null.
  • Shipments with returns cannot be updated, only cancelled if their current status allows it.
  • All the actions (getting labels, requesting pick-up, even cancelling) regarding shipments with returns should be performed on delivery shipment (a shipment returned upon creation, not the one contained in ReturnShipment field).
  • Requesting shipment status GetShipmentStatusByShipmentId, GetShipmentStatusByRef1AndPickupDate, GetShipmentStatusByAnyRef can be performed on both delivery and return shipment, they essentially are two different shipments.

JSON examples

Creating shipment with return (first colli is to be delivered, second to be returned (IsReturnColli = true)):

{
  "ShipmentWeight": null,
  "Collies": [
    {
      "ColliWeight": null,
      "Ref1": "Delivery ref1",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RemarkGoods": "Text value",
      "ColliDocumentData": null,
      "IsReturnColli": false
    },
    {
      "ColliWeight": null,
      "Ref1": "Return ref1",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RemarkGoods": "Text value",
      "ColliDocumentData": null,
      "IsReturnColli": true
    }
  ],
  "Ref1": "Text value",
  "Ref2": "Text value",
  "Ref3": "Text value",
  "RemarkGoods": "Text value",
  "CountOfBillingUnits": null,
  "ConsigneeName": "Text value",
  "ConsigneePostalCode": "Text value",
  "ConsigneeStreet": "Text value",
  "ConsigneeCity": "Text value",
  "ConsigneeCountryPrefix": "HR",
  "ConsigneeTelephoneNumber": "Text value",
  "ConsigneeFaxNumber": "Text value",
  "ConsigneeGsmNumber": "Text value",
  "ConsigneeEmailAddress": "Text value",
  "SenderName": "Text value",
  "SenderPostalCode": "Text value",
  "SenderStreet": "Text value",
  "SenderCity": "Text value",
  "SenderCountryPrefix": "HR",
  "SenderTelephoneNumber": "Text value",
  "SenderFaxNumber": "Text value",
  "SenderGsmNumber": "Text value",
  "SenderEmailAddress": "Text value",
  "ExpressType": 100,
  "ExWorksType": null,
  "NotificationType": 3,
  "AllowSaturdayDelivery": false,
  "PickupStart": null,
  "PickupEnd": null,
  "DeliveryStart": null,
  "DeliveryEnd": null,
  "CodAmount": null,
  "CodCurrency": null,
  "InsuranceAmount": null,
  "Currency": null,
  "RemarkDelivery": "Text value",
  "RemarkPickup": "Text value",
  "IsCargo": false,
  "ReturnDocument": false,
  "BillingUnit": null,
  "ShipmentDocumentData": null,
  "ShipmentDocumentExtension": null,
  "ApiKey": "00000000-0000-0000-0000-000000000000"
}


Response to the request above should be something like:


{
  "CreatedShipmentId": 153,
  "Collies": [
    {
      "ColliId": 1,
      "Status": 1,
      "CargoNetColliId": "Text value",
      "BarCode": "Text value",
      "Ref1": "Delivery ref1",
      "Ref2": "Text value",
      "Ref3": "Text value",
      "RefInt": "Text value",
      "ColliDocumentExtension": null,
      "MultifunctionalBarcode": "Text value",
      "Services": "Text value"
    }
  ],
  "PickupStart": "2014-09-08T12:00:00+02:00",
  "PickupEnd": "2014-09-08T118:00:00+02:00",
  "DeliveryStart": "2014-09-09T12:00:00+02:00",
  "DeliveryEnd": "2014-09-09T18:00:00+02:00",
  "PriceInformation": {
    "Net": 100.0,
    "Gross": 150.0
  },
  "ValidPickupIntervals": [
    {
      "From": "2014-09-08T12:00:00+02:00",
      "To": "2014-09-08T18:00:00+02:00"
    }
  ],
  "ValidDeliveryIntervals": [
    {
      "From": "2014-09-09T12:00:00+02:00",
      "To": "2014-09-09T18:00:00+02:00"
    }
  ],
  "AdditionalInfo": {
    "DeliveryBefore0830": false,
    "DeliveryBefore1030": false,
    "SaturdayDelivery": false
  },
  "ExpectedSenderAddress": {
    "PostalCode": "Text value",
    "City": "Text value",
    "Street": "Text value"
  },
  "DeliveryCenterAbbreviation": "ZA",
  "TourNumber": 12,
  "ReturnShipment": {
    "CreatedShipmentId": 17688,
    "Collies": [
      {
        "ColliId": 111226,
        "Status": 3,
        "CargoNetColliId": "Text value",
        "BarCode": "Text value",
        "Ref1": "Return ref1",
        "Ref2": "Text value",
        "Ref3": "Text value",
        "RefInt": null,
        "BarcodeCustomer": null,
        "ColliDocumentExtension": null,
        "MultifunctionalBarcode": "Text value",
        "Services": "Text value"
      }
    ]
  },
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}

Getting shipping labels in separate response fields

If API administrator allows it for certain API key, it is possible to get shipping labels and colli/shipment documents in separate response fields when using GetShippingLabelsForSingleShipment, GetShippingLabelsForAllShipments, GetShippingLabelsForShipments. In that case, response to these API calls looks something like following (note Labels field):

Response

{
  "ShipmentIds": [
    17689
  ],
  "LabelInfo": {
    "PageWidth": 10.0,
    "PageHeight": 14.8,
    "LabelWidth": 10.0,
    "LabelHeight": 14.8,
    "TopMargin": 0.0,
    "SideMargin": 0.15,
    "HorizontalPitch": 10.5,
    "VerticalPitch": 14.8,
    "MaxHorizontalLabels": 1,
    "MaxVerticalLabels": 1
  },
  "NumberOfLabels": 2,
  "PdfDocument": null,
  "InvalidShipmentIds": [],
  "Labels": [
    {
      "ShipmentId": 17689,
      "ShipmentPdfDocuments": [BYTE ARRAY DATA (ommited because it's not human readable)],
      "ColliLabelsAndDocuments": [
        {
          "ColliId": 111227,
          "CargoNetColliId": "64021637",
          "LabelPdfDocument": [BYTE ARRAY DATA (ommited because it's not human readable)],
          "ColliPdfDocument": [BYTE ARRAY DATA (ommited because it's not human readable)]
        },
        {
          "ColliId": 111228,
          "CargoNetColliId": "64021638",
          "LabelPdfDocument": [BYTE ARRAY DATA (ommited because it's not human readable)],
          "ColliPdfDocument": [BYTE ARRAY DATA (ommited because it's not human readable)]
        }
      ]
    }
  ],
  "IsValid": true,
  "ModelErrors": null,
  "ValidationErrors": null
}