🚧
Do you have questions about our APIs? If you need help, don’t forget to use our artificial intelligence — it will help you generate examples that fit your specific needs, variations, and the required parameters for using each Hound Express API.
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:

The status: delivered status

Non-delivery status groups

and "everything else"

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

A 'Long' that represents the date when the event that changed the status of the guide occurred.

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:

Format - A byteArray of the data stream that represents the content of the file

Format_fileNamee - The name of the file, including the extension contained in the byteArray "format"

POD - A byteArray of the data stream that represents the content of the file

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.
CurrentStatus
currentStatus

Required
Within this field our API receives the data as a
currentStatus object.
realReceiverPerson
PersonName

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.
format
Byte(array)

Optional
A byteArray of the data stream that represents the content of the file
format_fileName
String
100
Optional
The name of the file, including the extension contained in the byteArray "format"
idType
(object)

Optional
ID document type related to the 'identification' field.

To obtain the possible options see: IdTypes.
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
CurrentStatus
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).
status Integer 5 Required The ID and status should in this field.
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.
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.
PersonName
Field name Type MaxLength Required Comments
givenName String 200 Required Complete name of the person who actually received the delivery.
Idtype
Field name
Type
MaxLength
Required
Comments
id
Integer

Optional
The ID the idType in this field.
value
String
8
Optional
The value the idType is in this field.

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.