Overview

Introduction

The JiuFang Shipping APIs let you integrate Jiufang and other carrier services into your platform. The APIs provide a unified set of resources for all supported carriers. The APIs follow the principles of the REST architectural style and use HTTP as the underlying protocol. For security, requests use HTTPS. Responses include success or failure messages and any requested resources. Resource objects use JSON formatting.This Document describes access to the APIs and describes the API components.

Account

To use the Jiufang Shipping APIs, you must have a Jiufang account. You can create a free account and access the Sandbox test environment by emailing it01@tofba.com or calling 4007755990. To sign up, use a regularly monitored email, We will send the account information to your mailbox in the form of email.

API Environments

The Jiufang APIs provide the Sandbox and Production environments. Each environment has its own set of base URLs, Note that the base URL is just one part of the API call:

sandbox: http://sandbox.tofba.com/api/

production: http://api.tofba.com/api/

HTTP Request Headers

All API requests require one or more HTTP headers. All requests require the Authorization header, which authenticates the developer to the JiuFang Shipping APIs.

Important: Do not pass a header that you do not intend to use. Instead, omit the header.

Important: Do not pass a header with the NULL value.

Example: Authorization Bearer edEB6SlC8wafnWgAlgqxagATPF0F

API Resources

Rate

DescriptionMethodResource Path
Rate CargoPOST/v3/rate

Shipment

DescriptionMethodResource Path
Create ShipmentPOST/v3/shipment
Void Shipment POST/v3/voidShipment

Pickup & Dropoff

DescriptionMethodResource Path
Schedule PickupPOST/v3/pickup/schedule
Cancel PickupPOST/v3/pickup/cancel
ReSchedule PickupPOST/v3/pickup/reschedule
Schedule DropoffPOST/v3/dropoff

Tracking

OperationMethodEndpoint
Track CargoPOST/v3/tracking

API Responses

All API requests return an HTTP response that includes an HTTP status code, HTTP response headers, and, if applicable, a response body containing JSON-formatted data. The HTTP status code indicates the success or failure of the request. The request body, if present, contains either a resource object (returned by a successful request) or error information (if the request failed).

CodeMessageAdditional Information
200OKThe request is successful.
400Bad RequestPossible causes include a missing parameter, missing value, invalid structure, or malformed request.
401UnauthorizedPossible causes include an expired or invalid.
404Not FoundThe resource does not exist or is temporarily unavailable.
500Internal Server ErrorThere has been an error on the Jiufang servers. IMPORTANT: If you receive this error when creating a shipment, see 500 Internal Server Error.

Error Response

When an error occurs, the system responds with an error code,description that defifine the general problem encountered.

Error Code - A unique numerical value used to identify the error. Error code 1001, for example, is associated with a hard error and indicates the XML document is not well formed.

Error Description - A description of the general problem. For example, “The JSON document is not well formed” is the description associated with Error Code 1001.

Details

1、Rate

HTTP Request

Summary

1、Use this operation to rate a cargo before you create a shipment and print label. 2、Jiufang Delivery.

Request Elements

The table below describes all possible fields in the Rate API.

NameData TypeDescription
SecuritySecurity ObjectRequired.User account and password
ShipFromShipFrom ObjectRequired. Origin address.
ShipToShipTo ObjectRequired. Destination address.
PackagesArray(Package)Required.The package.Each package must contain weight

Response Elements

NameData TypeDescription
ResponseStatusResponseStatus ObjectRequired.Every request has a response status
ErrorError ObjectConditional. Describe the specific cause of the error.
ServiceService ObjectConditional. Optional services

Sample Request

Sample Rate Error Response

Sample Rate Success Response


2、Shipment

2.1、Create

HTTP Request

Summary

This operation creates a Jiufang Delivery label that uses either the Jiufang air transport or Jiufang ocean transport service.

Request Elements

The table below describes all possible fields in the Rate API.

NameData TypeDescription
SecuritySecurity ObjectRequired.User account and password
ShipmentRequestShipmentRequest ObjectRequired.the object structure refer to the Shipment Sample Request

Response Elements

NameData TypeDescription
ResponseStatusResponseStatus ObjectRequired.Every request has a response status
ErrorError ObjectConditional. when create shipment fail. Describe the specific cause of the error.
ShipmentResponseShipmentResponse ObjectConditional. when create shipment success.

Sample Request

Sample Shipment Error Response

Sample Shipment Success Response

Note: ShipmentIdentificationNumber is the Void shipment, Schedule pickup , Dropoff and Tracking API required parameter!Please keep it safe

2.1、Void

HTTP Request

Summary

This operation cancels an unused shipment label.

Sample Request

Sample Shipment Void Error Response

Sample Shipment Void Success Response


3、Pickup

3.1、Schedule

HTTP Request

Summary

This operation will inform our company to pick up the goods from the sender's company.

Request Elements

The table below describes all possible fields in the Rate API.

NameData TypeDescription
SecuritySecurity ObjectRequired.User account and password
PickupScheduleRequestPickupScheduleRequest ObjectRequired.the object structure refer to the Pickup Sample Requests

Response Elements

NameData TypeDescription
ResponseStatusResponseStatus ObjectRequired.every request has a response status
ErrorError ObjectConditional. when create pickup fail. Describe the specific cause of the error.
The object structure refer to the Sample Pickup Error Response
PickupScheduleResponsePickupScheduleResponse ObjectConditional. when create pickup success. The object structure refer to the Sample  Pickup Success Response

Sample Request

Sample Pickup Error Response

Sample Pickup Success Response

Note: The PickupIdentificationNumber is the cancel pickup and reschedule pickup API required parameter!Please keep it safe

3.2、Cancel

HTTP Request

Summary

When you don’t need our company to pick up the goods.You can call this API to cancel pickup.you must use the PickupIdentificationNumber to operating.this Number retuen from Pickup create API Response

Sample Request

Sample Pickup Cancel Error Response

Sample Pickup Cancel Success Response

3.3、ReSchedule

HTTP Request

Summary

When you find that you have cancelled the pickup by mistake, you can re-appoint the pickup through this API.

Sample Request

Sample Pickup ReSchedule Error Response

Sample Pickup ReSchedule Success Response


4、Dropoff

HTTP Request

Summary

This operation is cancelled the goods are picked up by our company.

Request Elements

The table below describes all possible fields in the Rate API.

NameData TypeDescription
SecuritySecurity ObjectRequired.User account and password
DropoffRequestDropoffRequest ObjectRequired.The object structure refer to the Dropoff Sample Requests

Response Elements

NameData TypeDescription
ResponseStatusResponseStatus ObjectRequired.every request has a response status
ErrorError ObjectConditional. when create pickup fail. Describe the specific cause of the error.
The object structure refer to the Sample DropOff Error Response
DropoffResponseDropoffResponse ObjectConditional. when create dropoff success. will return the detailed shipping address.

Sample Request

Sample Dropoff Error Response

Sample Dropoff Success Response


5、Tracking

HTTP Request

Summary

You can track packages through either the Shipping APIs

Response Elements

NameData TypeDescription
ResponseStatusResponseStatus ObjectRequired.every request has a response status
ErrorError ObjectConditional. when create tracking fail. Describe the specific cause of the error.
The object structure refer to the Sample Tracking Error Response
TrackingResponseTrackingResponse ObjectConditional. when create tracking success. The object structure refer to the
Sample  Tracking Success Response

Sample Request

Sample Tracking Error Response

Sample Tracking Success Response

Core Resource Objects

Security

NameData TypeDescription
UsernameStringRequired. username
PasswordStringRequired. password

ShipFrom

NameData TypeDescription
AddressAddress ObjectRequired.
CompanyNameCnStringRequired.The chinese name of the company
CompanyNameEnStringRequired.The english name of the company
AttentionNameStringRequired.The first and last name
PhoneStringRequired.The phone number. Enter the digits with or without spaces or hyphens
EnterpriseCreditCodeStringRequired.The tax identification number.This information can be found via this website http://gsxt.gdgs.gov.cn/

ShipTo

NameData TypeDescription
AddressAddress ObjectRequired.
AttentionNameStringRequired.The first and last name
NameStringRequired.The name of the company
PhoneStringRequired.The phone number. Enter the digits with or without spaces or hyphens

Address

NameData TypeDescription
AddressLineArray[String]Required.Street address or P.O. Box. Include apartment number if applicable. You can specify up to 3 address lines.
PostalCodeStringRequired.The postal code or ZIP code.
For US addresses, use either the 5-digit or 9-digit ZIP code in one of the following formats:
CityStringRequired.The city or town.
StateProvinceCodeStringRequired.The state or province. For a US or Canadian address, use the 2-letter state or province code.
For China,use Full name in Chinese characters.
CountryCodeStringRequired.Two-character country code from the ISO country list. To determine if this field is required.

Weight

NameData TypeDescription
WeightDoubleRequired.The total weight
UnitOfMeasurementUnitOfMeasurement ObjectRequired.Set this KGS

Volume

NameData TypeDescription
VolumeDoubleRequired.The total volume
UnitOfMeasurementUnitOfMeasurement ObjectRequired.Set this CBM

UnitOfMeasurement

NameData TypeDescription
CodeStringRequired.The unit of measurement

Service

NameData TypeDescription
CodeStringRequired.The unit of measurement
TransportationChargeTransportationCharge ObjectRequired. The Service description
DeliveryCommitmentDeliveryCommitment ObjectConditional.Additional introduction about the JiuFang Air freight product.

TransportationCharge

NameData TypeDescription
CurrencyCodeStringRequired.The currency code of charge.Three-character currency code from the ISO currency list.
MonetaryValueDoubleRequired.Total freight
ChargeWeightDoubleRequired.Charge weight
ChargeUnitPriceDoubleRequired.Charge unit price

DeliveryCommitment

NameData TypeDescription
MinEstimatedNumberOfDaysintConditional.The minimum number of delivery days.
MaxinEstimatedNumberOfDaysintConditional.The maximum number of delivery days.
AdditionalDetailsStringConditional.These are carrier specific details that may be provided.

Package

NameData TypeDescription
PackageWeightPackageWeight ObjectRequired.Rate and Shipment API.this element is required.
If you want to know more about the object, you can refer to Shipment Sample Request
DimensionsDimensions ObjectRequired.Rate and Shipment API.this element is required.
If you want to know more about the object, you can refer to Shipment Sample Request
BoxMarkBoxMark ObjectConditional.Shipment API this element is required.
If you want to know more about the object, you can refer to Shipment Sample Request
PackageDetailPackageDetail ObjectConditional.Shipment API this element is required.
If you want to know more about the object, you can refer to Shipment Sample Request

Invoice

NameData TypeDescription
ShipmentIdStringRequired.
ReferenceIdStringRequired.
SkuStringRequired. SKU
ProductNameCnStringConditional.the sku chinese product name
ProductNameEnStringRequired. the sku english product name
BrandStringRequired.the sku brand
MaterialStringRequired.the sku material
PurposeStringRequired.the sku purpose
HsCodeStringConditional.the sku hscode
ModelStringRequired.the sku model
AsinStringRequired.the sku asin code
PurchasingPriceDoubleConditional.the sku purchasing price.
NumIntegerRequired.the sku quantity
DeclareValueDoubleRequired.the sku declare value
ImageUrlStringRequired.the sku iamge url.This link must be downloadable

Shipment

NameData TypeDescription
ReferenceNumberReferenceNumber ObjectRequired.the ReferenceNumber must unique
ServiceService ObjectRequired.the Service Code is the rate API response
ShipFromShipFrom ObjectRequired.Origin address.
ShipToShipTo ObjectRequired.Destination address.
ImporterImporter ObjectRequired.Importer information
InvoiceLineTotalInvoiceLineTotal ObjectRequired.invoice total declare value and currency
PackagesArray(Package)Required.Package information
InvoicesArray(Invoice)Required.Invoice information
ShipmentServiceOptionsShipmentServiceOptions ObjectConditional.
LabelFormatLabelFormat ObjectConditional. support URL and BASE64.default:BASE64

Importer

ameData TypeDescription
AddressAddress ObjectRequired.
CompanyNameStringRequired.The name of the company.
AttentionNameStringRequired.The first and last name.
VATStringRequired.VAT number.
EORIStringRequired.EORI number.

InvoiceLineTotal

NameData TypeDescription
CurrencyCodeStringRequired. currency code
MonetaryValueDoubleRequired. total declare value

ShipmentServiceOptions

NameData TypeDescription
PickupBooleanConditional.The Pickup and Dropoff can't be true or false at the same time.
If you set the same value.we will set the value of Pickup to true.set the value of Dropoff to false.
when the Pickup value is true.you should call the Schedule Pickup API.
DropoffBooleanConditional.The Dropoff and Pickup can't be true or false at the same time.
If you set the same value.we will set the value of Pickup to true.set the value of Dropoff to false.
when the Dropoff value is true.you should call the Dropoff API.
ExportLicenceBooleanRequired.
ExportLicenceNumberStringConditional.if the ExportLicence value is true.it's required.

LabelFormat

NameData TypeDescription
CodeStringRequired.You can choose either URLor BASE64. default BASE64.

ShipmentResponse

NameData TypeDescription
ShipmentChargesShipmentCharges ObjectRequired.shipment charges
BillingWeightBillingWeight ObjectRequired.billing weight
ShipmentIdentificationNumberStringRequired.shipment identification number

ShipmentCharges

NameData TypeDescription
TransportationChargesTransportationCharges ObjectRequired.transportation charges
ServiceOptionsChargesServiceOptionsCharges ObjectConditional.service options charges
TotalChargesTotalCharges ObjectRequired.total charges

BillingWeight

NameData TypeDescription
UnitOfMeasurementUnitOfMeasurement ObjectRequired.unit of measurement
WeightDoubleRequired.shipment total charge weight

TransportationCharges/ServiceOptionsCharges/TotalCharges

NameData TypeDescription
CurrencyCodeStringRequired.currency code
MonetaryValueDoubleRequired.total money

DropoffResponse

NameData TypeDescription
AddressAddress ObjectRequired.The JiuFang warehouse Address.
NameStringRequired.Warehouse receiving contact.
PhoneStringRequired.Contact phone number of warehouse consignee.

1、Three-character Currency Code

2、Two-character Country Code