Authorizations for International Shipping

Content

Introduction Request Format Request OAuth Format Response Format Status Codes Examples

The following information provides the API details to authorize a shipment with the carrier and get the tracking number and any additional information to generate the label that will be provided to the seller.

All the web services should be HTTP REST. It’s expected that the web service response uses the status codes specification depending if the request was successful or not.

Once a purchase has been performed on the site, Mercado Libre will make a POST request to the carrier as follows

POST /shipments/shipment_id/authorization

Note:

The shipment identifier (shipment_id) is unique at MELI´s side and must be used to validate if there was any previous autorization, taking into account that a retry mechanism is in place just in case an authorization fails.
The shipment identifier could eventually be associated to more than a tracking number but, it must only exist a unique "active" tracking number at the carrier side.
Idempotence: in case of receiving a request with a shipment already authorized, the service must retrieve a response with “HTTP Code” = 200, the same body and tracking number that was retrieved during the original authorization.
A cancelled shipment could be authorized in a future so this case should be taken into account.
Mercado Libre will send data with variable length in all fields which could also change over time so is responsability of the carrier to truncate data according to their storage requirements.

Important:

The Tracking Number of any shipment must only change on “n” authorizations if, and only if, a cancellation was prevously requested.

Depending on whether the authorization was succesfull or not, it is expected that the carrier retrieves a result according to the specified at "Status Code" section. In case of error, the communication will be retried according to the retry schema defined as part of the integration.

Important:

OAuth 2.0 will be used for secure authorizations.

Request Format

Inside the body of the request a JSON will be sent with the following attributes

Name	Data type	Description	Type
id	Long	Unique identifier of the shipment used by Mercado Libre, required to authorize. This ID will later be used to notify the events that occur in the operational flow of the shipment.	Mandatory
transport_order_id	String	Unique identifier for the transport leg	Always present in the request
direction	String	Indicates the direction of shipping. The allowed values are: If the direction is from the seller to the buyer → "foward" If the direction is from the buyer to the seller → "return"	Mandatorio
carrier_information	Node	Contains elements relevant to the carrier.	Mandatory
carrier_information.contract	String	Identifies the contract / service defined by the carrier with which the shipment is to be authorized. For example, home delivery from the XD, shipment to DS agency, etc.	Optional
carrier_information.agency	Node	Contains information related to the destination agency. Mandatory only when it is a shipment to a carrier agency.	Optional
carrier_information.agency.id	String	Id give Mercado Libre to the agency.	Mandatory
shipment_information	Node	It contains all the information that is considered relevant for shipping authorization. Sender, receiver, item, etc. Measurements are in centimeters and weights in grams.	Mandatory
shipment_information.international_information	Node	Contains information related to international shipments	Mandatory. Only for international shipments
shipment_information.international_information.cif	Node	Shipping cost concepts	Optional
shipment_information.international_information.cif.cost	Numeric	Declared value	Optional
shipment_information.international_information.cif.freight	Numeric	Transport cost	Optional
shipment_information.international_information.cif.insurance	Numeric	Insurance cost	Optional
shipment_information.international_information.tax_modality	String	Incoterms (International Commercial Terms). Values: DDP (Delivery Duty Paid) or DDU (Delivered Duty Unpaid)	Mandatory
shipment_information.international_information.destination_address	Node	Receiver address, only applies to international shipments within the Mercado Libre logistics network. The structure is the same as the shipment_information.receiver.address node	Optional
shipment_information.international_information.delivery_to	Nodo	Full name of the person receiving and flag that identifies whether the person receiving is the importer or not.	Opcional
shipment_information.international_information.delivery_to.full_name	String	Full name of the person receiving the package.	Mandatorio
shipment_information.international_information.delivery_to.full_name	Boolean	Indicates whether the person to whom it is delivered is the importer.	Opcional
shipment_information.package	Node	Package related information	Mandatory
shipment_information.package.items	Node	Information related to the items	Mandatory
shipment_information.package.items.item_id	String	Item identification number on Mercadolibre	Mandatory
shipment_information.package.items.description	String	Item description on Mercadlibre	Mandatory
shipment_information.package.items.domain_id	String	Item domain number on Mercado Libre	Optional
shipment_information.package.items.tariff_code	String	Global standard maintained by WCO.	Optional. Only for international shipments
shipment_information.package.items.made_in	String		Optional
shipment_information.package.items.quantity	Numeric	Quantity per item.	Mandatory
shipment_information.package.currency_id	String	Currency (USD)	Mandatory. Only for international shipments
shipment_information.package.amount	Numeric	Amount paid for the package content.	Mandatory
shipment_information.package.description	String	Package content.	Optional
shipment_information.package.dimensions	Node	Package dimensions and weight.
shipment_information.package.dimensions.height	Numeric	Height of the package in centimeters.	Mandatory
shipment_information.package.dimensions.length	Numeric	Length of the package in centimeters.	Mandatory
shipment_information.package.dimensions.width	Numeric	Width of the package in centimeters.	Mandatory
shipment_information.package.dimensions.weight	Numeric	Weight of the package in grams.	Mandatory
shipment_information.receiver	Node	Information related to the receiver	Mandatory
shipment_information.receiver.full_name	String	Full name or company name of the recipient	Mandatory
shipment_information.receiver.first_name	String	First name	Mandatory
shipment_information.receiver.last_name	String	Last name.	Mandatory
shipment_information.receiver.phone	Node	Information related to the receiver's phone data
shipment_information.receiver.phone.number	String	Only numbers	Mandatory
shipment_information.receiver.address	Node	Information related to the receiver's address	Mandatory
shipment_information.receiver.address.street_name	String	Street name	Mandatory
shipment_information.receiver.address.street_number	String	Street number.	Optional
shipment_information.receiver.address.intersection	String	Secondary street.	Mandatory in Ecuador
shipment_information.receiver.address.address_line	String	Contains the street_name and street_number fields data	Mandatory
shipment_information.receiver.address.comment	String	Comments	Optional
shipment_information.receiver.address.zip_code	String	Zip code	Mandatory in Argentina, Brasil, México and Peru. Optional in Colombia, Uruguay, Chile and Ecuador.
shipment_information.receiver.address.city	Node	Destination city	Mandatory
shipment_information.receiver.address.city.id	String	Unique city identifier provided by Mercado Libre.	Mandatory in Colombia, Uruguay, Chile and Ecuador. Optional in Argentina, Brasil, Mexico and Peru
shipment_information.receiver.address.city.name	String	City name	Mandatory
shipment_information.receiver.address.state	Node	State, department or province of destination.	Mandatory
shipment_information.receiver.address.state.id	String	Unique state identifier provided by Mercado Libre. Format ISO 3166.	Mandatory
shipment_information.receiver.address.state.name	String	State name.	Mandatory
shipment_information.receiver.address.country	Node	Destination country.	Mandatory
shipment_information.receiver.address.country.id	String	Unique identifier that Mercado Libre gives the country in ISO 3166 Format.	Mandatory
shipment_information.receiver.address.country.name	String	Country name.	Mandatory
shipment_information.receiver.address.neighborhood	Node	Destination neighborhood.	Optional
shipment_information.receiver.address.neighborhood.id	String	Unique neighborhood identifier.	Optional
shipment_information.receiver.address.neighborhood.name	String	Neighborhood name.	Optional
shipment_information.receiver.address.municipality	Node	Municipality of destination.	Optional
shipment_information.receiver.address.municipality.id	String	Unique municipality identifier.	Optional
shipment_information.receiver.address.municipality.name	String	Municipality name.	Optional
shipment_information.receiver.address.geolocation	Node	Address location.	Optional
shipment_information.receiver.address.geolocation.geolocation_type	String	It can be one of the following values: APPROXIMATE: approximate geolocation. GEOMETRIC_CENTER: locates the center of a region that is used as a reference. RANGE_INTERPOLATED: restricts precision to the midpoint of 2 nearby reference points. ROOFTOP: indicates that the location is exact. UNKNOWN: indicates that the location was not validated.	Mandatory
shipment_information.receiver.address.geolocation.latitude	Numeric	Latitude in number format with 8 decimal places.	Mandatory
shipment_information.receiver.address.geolocation.longitude	Numeric	Longitude of the location in number format with 8 decimal places.	Mandatory
shipment_information.receiver.identification	Node	Receiver Identification	Mandatory for international shipments to Chile and Brazil (MLC and MLB). Optional for other destinations
shipment_information.receiver.identification.type	String	Receiver Identification Type (it may vary depending on the country)	Mandatory for international shipments to Chile and Brazil (MLC and MLB). Optional for other destinations
shipment_information.receiver.identification.number	Numeric	Receiver identification number	Mandatory for international shipments to Chile and Brazil (MLC and MLB). Optional for the other destinations
shipment_information.sender	Node	Sender information	Mandatory
shipment_information.sender.full_name	String	Sender full name or company name	Mandatory
shipment_information.sender.first_name	String	Sender name	Mandatory
shipment_information.sender.last_name	String	Sender last name	Mandatory
shipment_information.sender.phone	Node	Sender phone information	Mandatory
shipment_information.sender.phone.number	String	Only numbers	Mandatory
shipment_information.sender.address	Node	Information related to the sender address	Mandatory
shipment_information.sender.address.street_name	String	Street name.	Mandatory
shipment_information.sender.address.street_number	String	Street number.	Optional
shipment_information.sender.address.intersection	String	Secondary street.	Mandatory in Ecuador
shipment_information.sender.address.address_line	String	Contains the street_name and street_number fields data	Mandatory
shipment_information.sender.address.comment	String		Optional
shipment_information.sender.address.zip_code	String	Zip code.	Mandatory in Argentina, Brasil, México and Peru. Optional in Colombia, Uruguay, Chile and Ecuador.
shipment_information.sender.address.city	Node	Origin city.	Mandatory
shipment_information.sender.address.city.id	String	Unique city identifier provided by Mercado Libre.	Mandatory in Colombia, Uruguay, Chile and Ecuador. Optional in Argentina, Brasil, Mexico and Peru
shipment_information.sender.address.city.name	String	City name.	Mandatory
shipment_information.sender.address.state	Node	State, department or province of origin.	Mandatory
shipment_information.sender.address.state.id	String	Unique state identifier provided by Mercado Libre. Format ISO 3166.	Mandatory
shipment_information.sender.address.state.name	String	State name.	Mandatory
shipment_information.sender.address.country	Node	Origin country.	Mandatory
shipment_information.sender.address.country.id	String	Unique identifier that Mercado Libre gives the country in ISO 3166 Format.	Mandatory
shipment_information.sender.address.country.name	String	Country name.	Mandatory
shipment_information.sender.address.neighborhood	Node	Origin neighborhood	Optional
shipment_information.sender.address.neighborhood.id	String	Unique neighborhood identifier.	Optional
shipment_information.sender.address.neighborhood.name	String	Neighborhood name.	Optional
shipment_information.sender.address.municipality	Node	Municipality of origin.	Optional
shipment_information.sender.address.municipality.id	String	Unique municipality identifier.	Optional
shipment_information.sender.address.municipality.name	String	Municipality name.	Optional
shipment_information.sender.address.geolocation	Node	Address location.	Optional
shipment_information.sender.address.geolocation.geolocation_type	String	It can be one of the following values: APPROXIMATE: approximate geolocation. GEOMETRIC_CENTER: locates the center of a region that is used as a reference. RANGE_INTERPOLATED: restricts precision to the midpoint of 2 nearby reference points. ROOFTOP: indicates that the location is exact. UNKNOWN: indicates that the location was not validated.	Mandatory
shipment_information.sender.address.geolocation.latitude	Numeric	Latitude in number format with 8 decimal places.	Mandatory
shipment_information.sender.address.geolocation.longitude	Numeric	Longitude of the location in number format with 8 decimal places.	Mandatory
shipment_information.sender.address.facility_id	String	Unique facility identifier	Optional
shipment_information.sender.identification	Node	Information related to the sender’s identification.	Always present in the request (Chile and Brazil)
shipment_information.sender.identification.type	String	Sender’s identification type.	Always present in the request (Chile and Brazil)
shipment_information.sender.identification.number	Numeric	Sender’s identification number.	Always present in the request (Chile and Brazil)
test	Boolean	Indicates that the request sent is for testing	Optional
keyword	String	The HASH (SHA256) of a secret word. The value of this parameter can be empty. If a value is present, the Carrier must request the secret word from the receiver of the package.	Optional

Note:

It should be noted that carrier account information must follow this order:

Contract: it is the number that uses the carrier to identify the contract (agreement) of rates established with Mercado Libre. It is being used to know how to define the shipment cost. This is the most used field by carriers.
Account: it is the identifier used by the carrier to differentiate areas of Mercado Libre. For instance Cross Border Trade has a different account id at the carrier side.
User: it is a user name assigned to Mercado Libre's clients.
Password: it is the password associated to the user.

OAuth Request Format

For the authentication mechanism through the generation of a token with OAuth, the following header must be added to the request:

--request  POST 'https://hostname/shipments/{shiment_id}/authorization'
--header 'Authorization: Bearer + TOKEN'
--body 'What is described in each integration is maintained'

Note:

Once the OAuth solution is implemented, the use of username and password in the integrations should be deprecated in favor of the use of the token. The fields to be deprecated are the following:

Field	Type	Description
carrier_information.user	String	Identifies a mail system user assigned to the Mercado Libre customer.
carrier_information.password	String	Identifies the password associated with the system user.

Formato Response

Inside the body, the system will return all the data from the authorization, listed below:

Name	Data type	Description	Type
id	Long	Unique identifier of the shipment used by Mercado Libre, required to authorize. This ID will later be used to notify the events that occur in the operational flow of the shipment.	Mandatory
status	String	Status of the authorization request AUTHORIZED FAILED ERROR	Mandatory
status_message	String	Any relevant detail regarding the authorization status.	Mandatory in case of failure (status = FAILED or status = ERROR).
tracking_number	String	Tracking Number	Mandatory in case the authorization was successfully processed. (status = AUTHORIZED).
authorization_information	Node	Contains any information related to the date and time of the authorization. Also any extra information for the label generation.
authorization_information.date	Date (ISO 8601)	Valid values. In UTC format: 2020-07-04T12:08:56.235Z or in local relative local time: 2020-07-04T12:08:56.235-07:00.	Mandatory in case the authorization was successfully processed. (status = AUTHORIZED).
authorization_information.custom_data	Node	Contains any relevant information for the label generation. There can be as many fields as needed in the key:value format.	Optional
authorization_information.custom_data.key	String\|Long	“Key” refers to the name of the key in the key:value format. The value can be either text or number.	Mandatory

Performance

Important:

It’s expected that the average request response time is under one second.

Status Codes

Status	HTTP code	Description	Action
AUTHORIZED	200	The authorization was successfully processed.	The shipment was already authorized and won't retry.
FAILED	400	The authorization was not able to be processed due to an error on the request. It’s expected to return status=FAILED with the status_message specifying the error cause.	Depending on the nature of the error, the data will try to be fixed before retrying. Periodic retries could happen.
ERROR	500	Any server side error. In this case status and status_message are optional.	There will be retry attempts to perform the authorization until the authorization is performed successfully.

Example

Request:

POST https://hostName/shipments/26379079680/authorization

{
    "id":10101033319242,
    "transport_order_id": "5c81e696e6d9183ea9190a58c13d4de71816b743",
    "direction":"forward",
    "carrier_information":{
        "contract":"",
    },
    "shipment_information":{
        "sender":{
            "first_name":"PY",
            "last_name":"S.A.",
            "phone":{
                "number":"522175123929",
            },
            "address":{
                "address_line":"Calle 12",
                "street_name":"Calle 12",
                "street_number":"S/N",
                "intersection":"Calle 21",
                "comment":"",
                "zip_code":"1870",
                "city":{
                    "id":"TUxBQ0xBTWF0YW56",
                    "name":"La Matanza"
                    },
                "state":{
                    "id":"AR-B",
                    "name":"Buenos Aires"
                    },
                "country":{
                    "id":"AR",
                    "name":"Argentina"
                    },
                "neighborhood":{
                    "id":null,
                    "name":"Villa Celina"
                    },
                "municipality":{
                    "id":null,
                    "name":"Villa Celina"
                    },
                "geolocation":{
                    "geolocation_type":"ROOFTOP",
                    "latitude":-14.10100206,
                    "longitude":-52.10104811
                    },
                "facility_id":"101010"
            },
            "full_name":"GOLANDS",
            "id":10101098879
        },
        "receiver":{
            "first_name":"MEL",
            "last_name":"PY",
            "phone":{
                "number":"10108508106",
            },
            "address":{
                "address_line":"Calle 23",
                "street_name":"Calle 23",
                "street_number":"S/N",
                "intersection":"Calle 32",
                "comment":"",
                "zip_code":"1625",
                "city":{
                    "id":"TUxBQ0VTQzQ3YTc0",
                    "name":"Escobar"
                    },
                "state":{
                    "id":"AR-B",
                    "name":"Buenos Aires"
                    },
                "country":{
                    "id":"AR",
                    "name":"Argentina"
                    },
                "neighborhood":{
                    "id":null,
                    "name":null
                    },
                "municipality":{
                    "id":null,
                    "name":null
                    },
                "geolocation":{
                    "geolocation_type":"RANGE_INTERPOLATED",
                    "latitude":-32.101012822,
                    "longitude":-52.10102059
                    },
                "delivery_preference":"business"
            },
            "identification":{
                "type":"DNI",
                "number":"1234123",
            },
            "full_name":"Mel py",
            "id":10010389392
        },
        "package":{
            "items":[
                {
                "item_id":"MLA101010618394",
                "description":"Lampara 100w",
                "tariff_code":"LFH80000234",
                "made_in":"United States",
                "quantity":1
                }
            ],
            "description":"MLA101010618394",
            "dimensions":{
                "height":15,
                "width":25,
                "length":70,
                "weight":1900
            },
            "amount":2420,
            "tags":["bulky"],
            "currency_id":"USD"
        },
        "international_information":{
            "tax_modality":"DDP",
            "cif": {
                "cost": 19.75,
                "freight": 3.84,
                "insurance": 0.41
            },
            "destination_address":{
                "address_line":"Calle 23",
                "street_name":"Calle 23",
                "street_number":"S/N",
                "intersection":"Calle 32",
                "comment":"",
                "zip_code":"1625",
                "city":{
                    "id":"TUxBQ0VTQzQ3YTc0",
                    "name":"Escobar"
                    },
                "state":{
                    "id":"AR-B",
                    "name":"Buenos Aires"
                    },
                "country":{
                    "id":"AR",
                    "name":"Argentina"
                    },
                "neighborhood":{
                    "id":null,
                    "name":null
                    },
                "municipality":{
                    "id":null,
                    "name":null
                    },
                "geolocation":{
                    "geolocation_type":"RANGE_INTERPOLATED",
                    "latitude":-32.101012822,
                    "longitude":-52.10102059
                    },
                "delivery_preference":"business"
            },
            "delivery_to": {
              "full_name": "Lorenzo lamas",
              "is_importer_final_receiver": true
            }
        },
    "test":false,
    "keyword": "3bc405c30cadb4e6eefdf0cff899abcf8234d761c9a3ea1b2f510601ae5fc504"
}

Response:

Authorized (HTTP Status Code 200)

{
    "id": "10101033319242",
    "status":"AUTHORIZED",
    "status_message":"OK",
    "tracking_number": "ASDfgh123asd",
    "authorization_information": {
        "date": "2001-07-04T12:08:56.235-07:00",
        "custom_data":{
            "ruta_1":"RUTA"
        }
    }
}

FAIL (HTTP Status Code 400)

{
    "error_code": "invalid_user_information.buyer",
    "status_message":"Missing receiver information",
    "status": "FAILED"
}

FAIL (HTTP Status Code 500)

{
    "status_message":"Internal server error",
    "status": "ERROR"
}