Keyword#

Introduction#

To ensure deliveries and reduce contradictory PNRs, it is necessary to implement mechanisms that allow validating the correct delivery of packages. This requires that, before delivering the packages, the system informs the driver that they must request a Keyword from the recipient to verify their identity. To address possible connectivity issues, an additional offline validation mechanism was implemented alongside the Online validation mechanism, to allow normal package delivery even in areas with poor connectivity.

Obtaining the Keyword during shipment authorization

Delivery process

Note: • Not all packages require the Keyword validation process. • To determine if a package requires this process, the value of the "keyword" field in the response sent during the shipment authorization must be checked. The existence of the field with some value implies that validation is mandatory.

Online Validation#

This is the main validation mechanism that must be used. Before delivering the package, the driver must ask the recipient for the Keyword and enter it in the app for validation with Mercado Libre's services.

Valid Keyword entry

Invalid Keyword entry

Important: For security, OAuth will be used.

Request:

bashCopy
1POST 'https://api.mercadolibre.com/shipments/keyword_validation' \
2--header 'Authorization: Bearer {accessToken}'

Request Format#

Within the body, a JSON object will be sent with the fields listed below:

Name	Data Type	Description	Type
keyword	String	Keyword provided by the receiver.	Mandatory
shipments_ids	Long[]	Unique delivery identifier used by Mercado Libre that needs to be validated. In cases where multiple packages are delivered to the same recipient, it is possible to send the list of shipment_id to validate with a single Keyword.	Mandatory
method	String	Indicates whether the call is being made online or offline. Possible values: • online • offline	Optional
driver_id	String	Identifies the driver performing the package delivery.	Optional

Response Format#

When the validation is successful, the POST result will return a 200 code. In these cases, no content will be included in the response body. In cases where the Keyword validation is incorrect, the following information will be included in the response body:

Name	Data Type	Description	Type
message	String	Response message.	Mandatory
error	String	Error code.	Mandatory

Status Codes#

Status	HTTP Code	Description	Action
SUCCESS	200	Validation was successful.	The package can be delivered.
FAILED	400	Validation was not successful.	Attention should be paid to the "error" field in the response body to analyze how to proceed. If the error is "keyword_invalid", a new Keyword must be requested and validated. If the error is "too_many_request", the Keyword can no longer be validated until the next day.
ERROR	500	Any server-side error. In this case, "error" will indicate the cause of the error.	It will be possible to retry until a satisfactory response is obtained according to the defined retry scheme. If it persists, the offline validation process must be performed.

Examples#

Request:

bashCopy
1POST 'https://api.mercadolibre.com/shipments/keyword_validation' \
2--header 'Authorization: Bearer {accessToken}'
3{
4  "keyword": "manzana",
5  "method": "online",
6  "driver_id": "123",
7  "shipments_ids": [10101033319242, 10101053419321]
8}

Response:

SUCCESS (200 OK) When the validation is successful, no content is returned in the response body.

FAILED (400)

jsonCopy
1{
2  "message": "The keyword is invalid",
3  "error": "keyword_invalid"
4}

jsonCopy
1{
2  "message": "Too Many Requests",
3  "error": "too_many_request"
4}

ERROR (5xx)

jsonCopy
1{
2  "message": "Internal Server Error",
3  "error": "unexpected_error"
4}

Offline Validation#

In cases where, due to Internet connection issues, online validation is prevented, a mechanism is available to perform the validation locally.

Important: This requires that a subsequent call be made to the online validation service to reflect the record of the correct validation.

Offline Validation Mechanism#

1. Obtain the Keyword from the shipment Get the value of the "keyword" field from the response sent during the shipment Authorization. If this field is not found, or is empty, this validation should not be performed.

jsonCopy
1{
2  ...
3  "keyword": "3bc405c30cadb4e6eefdf0cff899abcf8234d761c9a3ea1b2f510601ae5fc504"
4  ...
5}

2. Generate the hash of the recipient's Keyword Concatenate the shipment_id and the Keyword provided by the recipient (in lowercase and without accents). Apply the SHA256 algorithm to the above concatenation.

shipment_id = 10101033319242
providedKeyword = "Manzana"
textToEncrypt = shipment_id + WithoutAccentsOrUppercase(providedKeyword)
             --> "10101033319242manzana"
newHash = SHA256(textToEncrypt)
       --> "3bc405c30cadb4e6eefdf0cff899abcf8234d761c9a3ea1b2f510601ae5fc504"

3. Compare both hashes Perform the comparison of the hashes obtained in steps 1 and 2 using a case-insensitive comparison.

4. Repeat the process in case of failure This process can be repeated until the comparison is successful or until the maximum number of allowed retries is reached. If the maximum number of allowed retries is reached, you must not continue trying until the next day.

5. Send information to Mercado Libre All validations performed offline must be communicated to Mercado Libre through the online validation service previously defined.

Some Hash Examples#

Shipment ID	Keyword	Hash
90854907004	galleta	32b962a2a31ab288f49fb695cf87672f08d0da747177f7ddd0e0ad77a7d6d560
66151385909	tierra	abd231310284f7fd6a7e7cf162c37686032c301c6852a2d5fd7f06fd381d12ba
44094201961	moto	e9e810b19511c8d831bba1bae64b9a013857c59caa75acbe31e2e5c439c2d3f5
37312402307	antena	130b7f810e6f28d38c96d7b89f195594d527f4aebebadce63cce397664fd7736
19713911553	silla	f1e7db0987c06540a8613411ce7c78b51d75b41f7d235dee799a0410446c0ad9
52362595220	muro	230b9d48b6556bdf96fea354a762a3c95e9b2b4c1f157e5b824aff7d1916afd2
70095070394	cama	c3b8f6306f596c410e0516de440c43b063829e0a95caa964e1de1ccbf603cc76
0013868181	ventana	224388a465eadfa3cee80b1eb6989a379758715d7dfee78b8933dd73af0287fe
53490772071	foco	092dba39afb9a1d51a456f51825caabbe5b6752369ea0c802b57016148a4446d
83088916183	remera	b2dcac1190371eb12c7e096b80f039183038becf52941f101dfd32c908e01767