Shipment

New shipment

This endpoint creates a new shipment.

URL

PROD https://api.skypostal.com/

TEST https://api-test.skypostal.com/

Endpoint

POST /wcf-services/service-shipment.svc/shipment/new-shipment

Request Credentials

Parameters
`user_info`	Object - Required User Info Definition.
`shipment_info`	Object - Required Shipment Info Definition.

Parameters

user_info

Object - Required

User Info Definition.

shipment_info

Object - Required

Shipment Info Definition.

User Info Definition

Parameters
`user_code`	Integer - Required This is the user code provided by Skypostal.
`user_key`	String - Required This is the app key provided by Skypostal.
`app_key`	String - Required This is the app key provided by Skypostal.

Parameters

user_code

Integer - Required

This is the user code provided by Skypostal.

user_key

String - Required

This is the app key provided by Skypostal.

app_key

String - Required

This is the app key provided by Skypostal.

Shipment Info Definition

Parameters
`copa_id`	Integer - Required Client identificator provided by Skypostal.
`box_id`	Integer Box identificator by country provided by Skypostal.
`ssa_copa_id`	Integer Ssa identificator.
`merchant`	Object - Required Entity Definition.
`shipper`	Object - Required for CA and for US instead of point of entry object Entity Definition.
`sender`	Object Entity Definition.
`consignee`	Object - Required Consignee Definition.
`options`	Object - Required Options Definition.
`data`	Object - Required Data Definition.
`pre_defined_label_information`	Object - Available only after agreement, remove from regular call Pre Defined Label Definition.

Remember

user_code, user_key, app_key, copa_id and box_id are generic credentials, make sure to request your own for TEST and PROD environments

Entity Definition

Parameters
`name`	String - Required Entity Name.
`email`	String - Required Entity Email.
`address`	Object - Required Address Definition.
`return_address`	Object Address Definition.
`phone`	List of Objects List of Phones (Phone Definition).

Consignee Definition

Parameters
`first_name`	String - Required First Name.
`last_name`	String - Required Last Name.
`email`	String - Required Consignee Email.
`id_number`	String - Required (BR - CL - PE) Consignee's country Identificator.
`id_search_string`	String Field to search for the id_number. - *BR only
`address`	Object - Required Address Definition.
`phone`	List of Objects - Required (MX - US) List of Phones (Phone Definition).

Address Definition

Parameters
`country_code`	Integer Code of the country.
`country_iso_code`	String - Required 2 characters iso code. (e.g. BR, MX, US, etc.)
`country_name`	String Name of the country.
`state_code`	Integer Code of state.
`state_name`	String Name of the state.
`state_abbreviation`	String - Required if overwriting USA shipment's point_of_entry with Shipper's addresses Abbreviation of the state.
`county_code`	Integer Code of the county.
`county_name`	String Name of the country.
`city_code`	Integer Code of the city, default value 0.
`city_name`	String - Required Name of the city.
`zip_code`	String - Required (AU - BR - CA - MX - US) Send a valid zipcode.
`town_code`	Integer Code of the town, default value 0.
`town_name`	String Name of the town or any city subdivision. (e.g. colonia, comuna, parroquia, pueblo).
`neighborhood`	String Address neighborhood.
`address_01`	String - Required Streets, home number, etc.
`address_02`	String Streets, home number, etc.
`address_03`	String Streets, home number, etc.

Phone Definition

Parameters
`phone_type`	Integer - Required Can be 1 = fixed telephony and 2 = cell phone.
`phone_number`	String - Required Phone Number.
`phone_extension`	String Phone Extension.

Parameters

phone_type

Integer - Required

Can be 1 = fixed telephony and 2 = cell phone.

phone_number

String - Required

Phone Number.

phone_extension

String

Phone Extension.

Options Definition

Parameters
`include_label_data`	Boolean - Required Include label data.
`include_label_zpl`	Boolean - Required Include label zpl.
`zpl_encode_base64`	Boolean Default value true. When true, the ZPL string will be encoded to a Base64 String.
`zpl_label_dpi`	Integer Default value 203. Can choose 203 or 300.
`include_label_image`	Boolean Include label image.
`include_label_image_format`	String - Required if include label image = True Include image format. Default value PNG. You can choose PNG or PDF.
`manifest_type`	String - Required Manifest Type Definition. Value matching any of the list.
`insurance_code`	Integer Insurance code Definition. Value matching any of the list.
`generate_label_default`	Boolean Generate Label Default.
`rate_service_code`	Integer - Required Rate Service Code Definition. Value matching any of the list.
`not_cleared_handling_code`	Integer Not Cleared Handling Code Definition. Value matching any of the list.
`return_if_exists`	Boolean If true service will return the info from a package already created.
`skip_dims_limit_validation`	Boolean If sent as true, max largest dimension limit of 155cm and max package total (LENGTH + GIRTH) limit of 240 cm will be ignored.
`skip_weight_limit_validation`	Boolean If sent as true, max weight of 50kg validation will be ignrored.
`allow_saturday_delivery`	Boolean - *Only for US services Saturday Delivery.
`is_return_shipment`	Boolean - *Only for US services If true, the "return address" from the POE will be used as the consignee address.
`additional_services`	Object Additional Services Definition.
`first_mile_label_options`	Object First Mile Label Options Definition.

Additional Services Definition.

Value	Description
`zipcode_validation`	Integer (0,1) Performs zipcode validation using additional geolocation services.
`id_validation`	Integer (0,1) Performs id validation by Skypostal.
`harmonization_code_validation`	Integer (0,1) Performs harmonization code validation by Skypostal.
`destination_address_validation`	Integer (0,1) Performs additional destination address validations.
`request_signature_on_delivery`	Integer (0,1) If available, requests a signature from the consignee when the shipment is delivered.
`description_translation`	Object Description Translation Definition.
`compliant_shipping_program`	Object - *BR Only Compliant Shipping Program Definition.

Description Translation Definition.

Value	Description
`translate_service`	Integer (0,1) 1 to activate and 0 to deactivate.
`translate_language_source`	String Two digits language code.
`translate_language_target`	String Two digits language target.

Value

Description

translate_service

Integer (0,1)

1 to activate and 0 to deactivate.

translate_language_source

String

Two digits language code.

translate_language_target

String

Two digits language target.

Compliant Shipping Program Definition.

Value	Description
`request_service`	Boolean Parameter to request or avoid the service.
`compliant_sender_code`	String Client's authorized TIN or ECE code, (please inform the complete valid shipper address to be set in the system).
`compliant_sender_authorized_code`	String (Amazon Sellers only) Authorization code to use AMAZON PRC.

Value

Description

request_service

Boolean

Parameter to request or avoid the service.

compliant_sender_code

String

Client's authorized TIN or ECE code, (please inform the complete valid shipper address to be set in the system).

compliant_sender_authorized_code

String (Amazon Sellers only)

Authorization code to use AMAZON PRC.

First Mile Label Options Definition.

When enabled, First mile labels requires Sender.address object:

Value	Description
`generate_first_mile_label`	Boolean, enables first mile label generation.
`rate_service_code`	Rate Service Code Definition. Value matching any of the list ( US Only Services ).
`include_last_mile_label`	Boolean. Default value: true. Returns the data item containing the generated last mile label, check the "Response label types Definition"

Manifest Type Definition.

String value matching any of the following list:

Value	Description
DDU	Customs Unpaid.
DDP	Customs Paid.

Insurance Code Definition.

Integer value matching any of the following list:

Value	Description
0	Follow insurance account rules.
1	Apply insurance.
2	Reject insurance.

Rate Service Code Definition.

General Services - Integer value matching any of the following list:

Value	Description
1	Courier Clearance / Courier Standard Plus.
2	Courier Clearance / Postal Delivery.
3	Postal Clearance / Postal Delivery.
4	Postal Clearance / Courier Standard.
5	Courier Clearance / Advanced.
6	ePacket / epacket.
7	Courier Clearance / Courier Standard.
8	Courier Clearance / Postal Economy.
9	Postal Clearance / Postal Economy.
10	ePacket / Local optimized.
11	Office of Exchange. - *2kg max
12	Postal Clearance/Postal Express.
13	Courier Clearance / Courier Economy.
14	Courier Clearance / Courier Express.

LATAM Only Services - Integer value matching any of the following list:

Value	Description
102	Courier Clearance / Courier Delivery For Credit Cards - AR Only (Restricted to "family_product": "CCS" only).
103	Postal Clearance / Postal Delivery Unregistered - PE Only.

US Only Services - Integer value matching any of the following list:

Value	Description
201	UPS Ground.
202	UPS Next Day Air Saver.
203	UPS 2nd Day Air.
204	UPS Next Day Air.
205	USPS Priority Mail.
206	USPS - Ground Advantage
207	USPS Parcel Select.
208	UPS 2nd Day Air A.M.
209	UPS 3-Day Select.

BR Only Services - Integer value matching any of the following list:

Value	Description
301	Packet Standard.
302	Packet Express.
303	Packet Mini.

CA Only Services - Integer value matching any of the following list:

Value	Description
401	Semi Tracked.
402	Delivery Tracked.

MX Only Services - Integer value matching any of the following list:

Value	Description
501	Courier Clearance / Courier Standard Plus - Supplements - (Restricted to "family_product": "HBS" only).
502	Courier Clearance / Courier Standard - Supplements - (Restricted to "family_product": "HBS" only).
503	Courier Clearance / Courier Lightweight Deferred - (Restricted, max weight of 200 grams).
504	Courier Clearance / Courier Standard Deferred.

Not Cleared Handling Code Definition.

Currently applies only for Packet BR

Value	Description
0	Return to origin.
1	Treat as abandoned - Default when not sent.

Data Definition

Parameters
`external_tracking`	String - Required Main package identifier for the client in SkyPostal's system (min 8 alphanumeric characters).
`reference_date`	String Format YYYY-MM-DD. Reference date of package.
`reference_number_01`	String Reference number 01 of package. Letters, numbers, hyphen "-" and underscore "_" allowed.
`reference_number_02`	String Reference number 02 of package. Letters, numbers, hyphen "-" and underscore "_" allowed.
`reference_number_03`	String Reference number 03 of package. Letters, numbers, hyphen "-" and underscore "_" allowed.
`tax`	Double Tax of package.
`value`	Double Reference total value package.
`discount`	Double Discount of package.
`freight`	Double Freight charged to client.
`currency_iso_code`	String - Required If no send, default USD.
`dimension_01`	Double - Required Dimension 01 of package.
`dimension_02`	Double - Required Dimension 02 of package.
`dimension_03`	Double - Required Dimension 03 of package.
`dimension_unit`	String - Required Can be IN = inches, CM = centimeters and M = Meters.
`weight`	Double - Required Weight of package.
`weight_unit`	String - Required Can be LB = pounds and KG = kilograms.
`has_lithium_battery`	Integer if any item from the shipment contains a lithium battery.
`commercial_invoice`	Object Commercial invoice Definition.
`items`	List of Objects - Required List of Items (Item Definition).
`point_of_entry`	Object - Required for USA services. Can be overwritten by shipper address Point of entry Definition.

Pre Defined Label Definition

Parameters
`provider_info`	Object - Required Provider Info Definition.
`label_info`	Object Label Info Definition.

Parameters

provider_info

Object - Required

Provider Info Definition.

label_info

Object

Label Info Definition.

Commercial invoice Definition

Parameters
`file_url`	String Valid URI for the commercial invoice declaration, must allow public access.

Parameters

file_url

String

Valid URI for the commercial invoice declaration, must allow public access.

Item Definition

Parameters
`ctry_iso_code_origin`	String 2 characters iso code. (e.g. BR, MX, US, etc.)
`skucode`	String Skucode for the product.
`hs_code`	String - Required for packet and etoe services Harmonized system code.
`family_product`	String Family product.
`serial_number`	String Product's serial number.
`imei_number`	String Imei number (in case of cellphone).
`image_url`	String Image URL for the product.
`description`	String - Required Description of package.
`product_brand`	String Product brand.
`product_name`	String Product name.
`product_model`	String Product model.
`quantity`	Integer - Required Quantity of each item type.
`tax`	Double Unit tax value (per item).
`value`	Double - Required Unit price value (per item).
`weight`	Double Unit weight (per item).

Point of Entry Definition

Parameters
`iata_code`	String - Required for US Shipments Point of entry - IATA Code.
`ctry_iso_code`	String - Required for US Shipments Point of Entry - Country Iso Code.

Parameters

iata_code

String - Required for US Shipments

Point of entry - IATA Code.

ctry_iso_code

String - Required for US Shipments

Point of Entry - Country Iso Code.

Provider Info Definition

Parameters
`service_provider_code`	Integer - Required Provider code defined and provided by SP.
`service_type_code`	Integer - Required Service code defined and provided by SP.

Parameters

service_provider_code

Integer - Required

Provider code defined and provided by SP.

service_type_code

Integer - Required

Service code defined and provided by SP.

Label Info Definition

Parameters
`label_tracking_number_01`	String - Required
`label_tracking_number_02`	String
`label_tracking_number_03`	String
`label_additional_info_01`	String
`label_additional_info_02`	String
`label_additional_info_03`	String
`label_additional_info_04`	String
`label_zpl`	String

Response definition

Parameters
`_verify`	When true, indicates the requested label was generated successfully. If false, check the errors object information.
`error`	Returned error codes, if any.
`label_image`	Contains the label image, if requested.
`label_invoice_url`	Invoice display URL.
`label_tracking_number_01`	Country provider tracking 1.
`label_tracking_number_02`	Country provider tracking 2.
`label_tracking_number_03`	Country provider tracking 3.
`label_type`	Response type. Check "Response label types Definition".
`label_url`	Display label URL.
`label_url_pdf`	Label URL PDF.
`label_zpl`	Label ZPL text. Can be base64 encoded if requested.
`skp_tracking`	Unique Skypostal Tracking number.
`trck_nmr_fol`	Unique Skypostal AWB number.

Response label types Definition

Value	Description
1	Last Mile.
2	Return.
3	Redistribution.
4	First Mile.

The command should be run as in the following example:

{
  "user_info":
  {
    "user_code": 123123,
    "user_key": "ok",
    "app_key": "ok"
  },
  "shipment_info":
  {
    "copa_id": 616,
    "box_id": 0,
    "ssa_copa_id": null,
    "merchant":
    {
      "name": "Store Name",
      "email": "store@email.com",
      "address":
      {
        "country_code": null,
        "country_iso_code": null,
        "country_name": null,
        "state_code": null,
        "state_name": null,
        "state_abbreviation": null,
        "county_code": null,
        "county_name": null,
        "city_code": 0,
        "city_name": null,
        "zip_code": null,
        "town_code": null,
        "town_name":"Colonia magistral",
        "neighborhood": null,
        "address_01": null,
        "address_02": null,
        "address_03": null
      },
      "return_address":
      {
        "country_code": null,
        "country_iso_code": null,
        "country_name": null,
        "state_code": null,
        "state_name": null,
        "state_abbreviation": null,
        "county_code": null,
        "county_name": null,
        "city_code": 0,
        "city_name": null,
        "zip_code": null,
        "town_code": null,
        "town_name":"Colonia magistral",        
        "neighborhood": null,
        "address_01": "Address to return the package",
        "address_02": null,
        "address_03": null
      },
      "phone":
      [
        {
          "phone_type": 1,
          "phone_number": "11111111"
        }
      ]
    },
    "shipper":
    {
      "name": null,
      "email": null,
      "address":
      {
        "country_code": null,
        "country_iso_code": null,
        "country_name": null,
        "state_code": null,
        "state_name": null,
        "state_abbreviation": null,
        "county_code": null,
        "county_name": null,
        "city_code": 0,
        "city_name": null,
        "zip_code": null,
        "town_code": null,
        "town_name":"Colonia magistral",        
        "neighborhood": null,
        "address_01": null,
        "address_02": null,
        "address_03": null
      },
      "return_address":
      {
        "country_code": null,
        "country_iso_code": null,
        "country_name": null,
        "state_code": null,
        "state_name": null,
        "state_abbreviation": null,
        "county_code": null,
        "county_name": null,
        "city_code": 0,
        "city_name": null,
        "zip_code": null,
        "town_code": null,
        "town_name":"Colonia magistral",        
        "neighborhood": null,
        "address_01": null,
        "address_02": null,
        "address_03": null
      },
      "phone": []
    },
    "sender":
    {
      "name": "COPA NAME",
      "email": null,
      "address":
      {
        "country_code": null,
        "country_iso_code": null,
        "country_name": null,
        "state_code": null,
        "state_name": null,
        "state_abbreviation": null,
        "county_code": null,
        "county_name": null,
        "city_code": 0,
        "city_name": null,
        "zip_code": null,
        "town_code": null,
        "town_name":"Colonia magistral",        
        "neighborhood": null,
        "address_01": null,
        "address_02": null,
        "address_03": null
      },
      "return_address":
      {
        "country_code": null,
        "country_iso_code": null,
        "country_name": null,
        "state_code": null,
        "state_name": null,
        "state_abbreviation": null,
        "county_code": null,
        "county_name": null,
        "city_code": 0,
        "city_name": null,
        "zip_code": null,
        "town_code": null,
        "town_name":"Colonia magistral",        
        "neighborhood": null,
        "address_01": null,
        "address_02": null,
        "address_03": null
      },
      "phone": []
    },
    "consignee":
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "email1@thesite.com",
      "id_number": "33214569874",
      "id_search_string": "This is a test with a CPF:12345678901 included",
      "address":
      {
        "country_code": null,
        "country_iso_code": "BR",
        "country_name": null,
        "state_code": 0,
        "state_name": null,
        "state_abbreviation": "SP",
        "county_code": null,
        "county_name": null,
        "city_code": 0,
        "city_name": null,
        "zip_code": "02124030",
        "town_code": null,
        "town_name":"Colonia magistral",        
        "neighborhood": null,
        "address_01": "Praza Nippon 43 loja",
        "address_02": "Jardim Japao",
        "address_03": null
      },
      "phone":
      [
        {
          "phone_type": 1,
          "phone_number": "123456789",
          "phone_extension": ""
        },
        {
          "phone_type": 2,
          "phone_number": "12673342655",
          "phone_extension": ""
        }
      ]
    },
    "options":
    {
      "include_label_data": false,
      "include_label_zpl": true,
      "zpl_encode_base64": true,
      "zpl_label_dpi": 203,
      "include_label_image": false,
      "include_label_image_format": "PNG",
      "manifest_type": "DDP",
      "insurance_code": 0,
      "rate_service_code": 6,
      "not_cleared_handling_code":1,
      "generate_label_default": false,
      "return_if_exists" : true,
      "skip_dims_limit_validation": false,
      "skip_weight_limit_validation": false,
      "allow_saturday_delivery": false,
      "is_return_shipment": false,
      "additional_services":
      {
        "zipcode_validation":0,
        "id_validation":0,
        "harmonization_code_validation":0,
        "destination_address_validation":0,
        "request_signature_on_delivery": 0,
        "description_translation":{
          "translate_service":0,
          "translate_language_source":"en",
          "translate_language_target":"es"
        },
        "compliant_shipping_program":{
           "request_service":false,
           "compliant_sender_code":"000",
           "compliant_sender_authorized_code": ""
        }
      },
       "first_mile_label_options":
      {
        "generate_first_mile_label":false,
        "rate_service_code":201,
        "include_last_mile_label":true
      }
    },
    "data":
    {
      "external_tracking": "testbr-222",
      "reference_date": "2019-02-07",
      "reference_number_01": "testbr-222",
      "reference_number_02": "testbr-222",
      "reference_number_03": null,
      "tax": null,
      "value": 40,
      "discount": 0,
      "freight": 34,
      "insurance": 0,
      "currency_iso_code": "USD",
      "dimension_01": 2,
      "dimension_02": 35,
      "dimension_03": 27,
      "dimension_unit": "CM",
      "weight": 1,
      "weight_unit": "KG",
      "has_lithium_battery": 0,
      "commercial_invoice":{
        "file_url":"https://awsfs.publicpdffiles.com/456dfs5df875asdf346sdf/uabhsi6sdf4567sdf654aun.pdf"
      }, 
      "items":
      [
        {
          "ctry_iso_code_origin":"NL",
          "hs_code": "",
          "family_product": "OTR",
          "serial_number": null,
          "imei_number": "",
          "description": "BOOKS",
          "product_brand":"",
          "product_name":"",
          "product_model":"",
          "quantity": 1,
          "tax": null,
          "value": 20,
          "weight": 1
        },
        {
          "ctry_iso_code_origin":null,
          "hs_code": "",
          "family_product": "OTR",
          "serial_number": null,
          "imei_number": "",
          "description": "CLOTHES",
          "product_brand":"",
          "product_name":"",
          "product_model":"",
          "quantity": 1,
          "tax": null,
          "value": 20,
          "weight": 1
        }
      ],
      "point_of_entry":
      {
        "ctry_iso_code":"US",
        "iata_code": "MIA"
      },
    },
    "pre_defined_label_information":{
        "provider_info":{
            "service_provider_code":27,
            "service_type_code":29
        },
        "label_info":{
            "label_tracking_number_01":"SP001073097CO",
            "label_tracking_number_02":"",
            "label_tracking_number_03":null,
            "label_additional_info_01":"",
            "label_additional_info_02":null,
            "label_additional_info_03":null,
            "label_additional_info_04":null,
            "label_zpl":null
        }
    }
  }
}

The command will return the following format:

{
  "data":
  [
    {
      "_verify": true,
      "trck_nmr_fol": 14763699,
      "skp_tracking": "SK00218568369US",
      "label_tracking_number_01": "1930073823",
      "label_tracking_number_02": "1069375763",
      "label_tracking_number_03": "",
      "label_zpl": "^XA\r\n^MMT\r\n^PW831\r\n^LL1015\r\n^LS0\r\n^FT19,64^A0N,47,57^FH\\^FDWSP Express^FS\r\n^FO266,268^GB0,73,3^FS\r\n",
      "label_image": null,
      "label_url": "http://testlabels.skypostal.com?awb=EXT5-NEWAPI-1004&copa=616&box=575929&prerecept=1",
      "label_type": 1,
      "label_url_pdf": "http://testlabels.skypostal.com?awb=EXT5-NEWAPI-1004&copa=616&box=575929&prerecept=1&return_pdf=1",
      "label_invoice_url": "http://testlabels.skypostal.com/invoice/?awb=EXT5-NEWAPI-1004&copa=616&box=575929&prerecept=1",
      "label_additional_data": 
      {
        "default_label_reason": "Reason why the default label was generated",
        "harmonization_code_validation_success": true,
        "id_validation_success": false,
        "zipcode_validation_success": true
      },
      "label_data":
      {
        "consignee": null,
        "origin": null,
        "destination": null,
        "provider_service_type": null,
        "provider_settings": null,
        "additional_info": null,
        "error": null
      },
      "additional_info": null,
      "error": null
    }
  ],
  "additional_info": null,
  "error": null
}