ChangeOrderStatus

🚧

If you need help don't forget to use our artificial intelligence

https://ia.hound-express.com/app/techhoundchannel

The usage of the service summarizes to sending the user's token as part of the HTTP request headers, and a JSON object in which, depending on the information included, it can contain certain attributes. This means that the deliveryPartner can determine the level of detail according to the information provided.
The service "Change Order Status" allows to receive information in order to update the status of the guide.

📘

We could group the attributes in 3 categories:

1. The status: delivered status
2. Non-delivery status groups
3. and "everything else"

🚧

It's important to notice that the attribute 'date' accepts 2 valid date parameter types:

1. A 'Long' that represents the date when the event that changed the status of the guide occurred.
2. A date 'String' in format "dd/MM/yyyy hh:mm:ss"

If the system does not detect as valid any of these formats, the current date is recorded, and it's not considered as an error itself but rather as a warning. That is why it's important to verify that the sent date corresponds to the one recorded in the system in the tests.

Never forget to check at the service response if there are any errors in the wsErrors array, since it can give you useful information about an error known by the server, which can help you handle the exceptions in the best possible manner.

In HoundExpress we don't contemplate the NON DELIVERY status per se. Instead, the non deliver causes are direct order status. For instance, if the shipment status is "delivery attempt" for the reason "no one to receive", for HoundExpress only exists the status "NO ONE TO RECEIVE" with id: 46 and code: NBROA.

👍

For example:

If the deliveryPartner performs a successful delivery the service request would be similar to:

{
"guide": {
"realReceiverPerson": {
"givenName": "JHON DOE"
},
"currentStatus": {
"longitud": "-99.226",
"latitud": "19.4273",
"date": "1540834812603",
"status": 2,
"observations": "Some observations"
},
"guideNumber": "8010116365329801",
"format": "[123,123,123,123]",
"format_fileName": "IDPicture.jpg",
"POD": "[321,321,321,321]",
"POD_fileName": "digitalSignature.png",
"idType": {
"id": 1,
"value": "123456789"
}
}
}

❗️

A non delivery example:

if the delivery attempt is made but the addressee does not accept the shipment, the service request would be simialr to:

{
"guide": {
"currentStatus": {
"date": "06/04/2019 15:04:50",
"status": 8,
"observations": "Rechazado por el destinatario"
},
"guideNumber": "9001008100001798"
}
}

🗒️

Another example:

If the de delivery attempt is made but at the adress nobody opens the door to receive the shipment, the service request would be simialr to::

{
"guide": {
"currentStatus": {
"longitud": "-99.226",
"latitud": "19.4273",
"date": "1540834812603",
"status": 46,
"observations": "Arrived to the apartments, but the incumbent was not there or did not open the door and the security guard did not receive it"
},
"guideNumber": "8010116365329801",
"format": "[123,123,123,123]",
"format_fileName": "123456789.jpg"
}
}

🗒️

Para otro tipo de eventos, como podrían ser los ocurridos durante el transcurso del envío ("todo lo demás"), la petición sería similar a:

{
"guide": {
"currentStatus": {
"date": "06/04/2019 15:04:50",
"status": 38,
"observations": "Salida retrasada"
},
"guideNumber": "9001008100001798"
}
}

For this reason, it is an important labour between you as a deliveryPartner and HoundExpress the correct mapping amongst the status that both handle.
It is necessary that you hand us previously a list of possible values that you might be using, so that we can homologate them with ours. However, if this list or the received status hasn't been informed to us, our system will handle it as a default status, predefined by HoundExpress.

As said before, in the examples above it is possible to receive the information in different detail levels, depending on the data provided by the deliveryPartner.

If your system is capable of recording the GPS coordinates of the event, you can use the fields:

"longitud": "-##.#########", "latitud": "##.#########"

If your system allows the messenger to type in information about the delivery status or details, you can use the field:

"observations"

📘

Whether the status implies a successful delivery or not, the WS can receive files attached by the fields:

1. Format - A byteArray of the data stream that represents the content of the file
2. Format_fileNamee - The name of the file, including the extension contained in the byteArray "format"
3. POD - A byteArray of the data stream that represents the content of the file
4. POD_fileName - The name of the file, including the extension of the byteArray "POD"

It is recommended to use the "POD" fields for the status of successful deliveries and include into them file reports that support the delivery, such as document or signature digitalizations.
On the other hand, we suggest you to use the "format" fields to attach files that support the alerted status such as pictures of facades, or the physical state of the shipments to show any damages, etc.

Name	Description
Service name	changeOrderStatus
EndPoint	https://ws_pods.hound-express.com/Sabueso/ws/deliveryServices/changeOrderStatus
Headers	https://apis-hound-express.readme.io/docs/the-headers-request
Method	POST
Parameters	JsonObject see: The guide object

📘

Request

To carry out the consumption of the service for change Order Status it is necessary to send a json object of the guide type and it requires the filling of the following fields:

GUIDE

Field name	Type	MaxLength	Required	Comments
guideNumber	String	30	Required	It is the guideNumber assigned to the shipment order on the HoundExpress system.
GuideStatus	currentStatus	-	Required	Within this field our API receives the data as a GuideStatus object.
realReceiverPerson	String	9	Required	In case that the received status corresponds to a deliver, the name of the person who actually received it is specified in this field as a PersonName object.
POD	Byte(array)	-	Optional	In case that the received status corresponds to a deliver, this field which accepts a byteArray allows to attach a file that proves the deliver. If this field is included in the request, the response will include a file in this same format and field.
POD_B64	String	blob	Optional	In case that the received status corresponds to a deliver, this field which accepts a base-64 encoded file allows to attach a file that proves the deliver. If this field is included in the request, the response will include a file in this same format and field. You can either send this field or send the field POD within the request, depending on which format would you like to receive the file. This means thay you only need to send one of these two fields.
POD_fileName	String	100	Optional	If you have sent a value in POD, you should include in this field the name and extension of the attached file.
observations	String	100	Optional	If your or your messenger would like to add comments or annotations about the delivery status, you can do it in this field.

Optional fields must be completely omitted in case their sent value is intentionally empty. See an example here

Child objects

The guide object contains sub-objects of which the filling of the following values is required

GuideStatus

Field name	Type	MaxLength	Required	Comments
code	String	8	Required	It is a unique identifier of the status (it will be used to homologate with the default status from HoundExpress).
description	String	500	Required	It allows you to provide additional information about the received status.
observations	String	500	Optional	Yo may use this field in case there is any operative insturction to consider.
time	String	20	Optional	Time at which the event happened, in format "hh:mm:ss".
date	String	20	Optional	Date at which the event occurred, in format "dd-MM-yyyy". For this field you can choose to send a 'Long' which represents the complete timestamp instead of sending them separately (in the corresponding fields), according to the standard (number of milliseconds since the Unix Epoch, the beginning of January 1, 1970). In case the 'date' or 'time' field don't meet the requisites, the system assings the current timestamp by default, so you may want to check the correct setting of this value in your development stage.
longitud	String	30	Optional	It specifies the longitude coordinate where the event occurred.
latitud	String	30	Optional	It specifies the latitude coordinate where the event occurred.
type	String	5	Optional	It groups the status. For instance, wether they belong to the transfer, the delivery, movements within warehouses, etc.

PersonName

Field name	Type	MaxLength	Required	Comments
givenName	String	200	Required	Complete name of the person who actually received the delivery.
nickName	String	50	Optional	If known, this field contains the relationship between the receiver and the addressee.
identification	String	20	Optional	Invoice of the ID document presented by the person who received the service.
idType	Integer	9	Optional	ID document type related to the 'identification' field. To obtain the possible options see: IdTypes.

Response

When the consumption is done, the API will return an object with the following characteristics

👍

Successful response

Guide

The service will return the guide object originally received with the fields filled in just as they were received, except for those that were used to send the information about attached files, which are sanitized to avoid unnnecesary data.