Domestic Auth#

Overview#

This endpoint enables carriers to approve domestic shipments (inside one country). It interfaces with the carrier systems to verify that a package has been accepted and to retrieve tracking numbers.

Key Features#

• Idempotency: Sending the same request twice returns the same tracking number
• OAuth 2.0: Secure authentication with bearer tokens
• Performance: Average response time under 1 second
• Scalability: Handles high-volume shipment requests
• Variable Data Length and Carrier Responsibility: Mercado Libre will send data fields with variable lengths, which may change over time. It is the carrier's responsibility to truncate this data as necessary to meet their specific storage requirements.

Mercado Libre is expected to receive a result, based on the "Status Code" section, that reflects whether the authorization was successful. If an error occurs, the system will automatically retry the communication following the retry schema established during the integration process.

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

HTTP Request#

bashCopy
1POST {url}/shipments/{shipment_id}/authorization
2 --header 'Content-Type: application/json'
3 --header 'Authorization: Bearer <access_token>'
4 --data-raw '{
5  "id": 2000005041469149431,
6  "transport_order_id": "ec4beec0-54d8-5066-a82d-3baa11649451",
7  "direction": "forward",
8  "test": false,
9  "carrier_information": { ... },
10  "shipment_information": { ... },
11  "authorization_information": { ... }
12 }'

Authentication#

All requests require OAuth 2.0 Bearer token authentication. Include your access token in the Authorization header:

bashCopy
1Authorization: Bearer YOUR_ACCESS_TOKEN

Request Parameters#

Headers parameters#

Body Parameters#

Root level fields#

These are the top-level fields in the authorization request:

Carrier Information#

Carrier contract and agency details for the shipment:

Agency Object#

Shipment Information#

Container object for sender, receiver, and package details:

Sender & Receiver#

Complete user information for both sender and receiver. All fields are set when the user object exists:

Phone Object#

Identification#

Address Fields#

Complete address information for sender and receiver.

Localization Object#

Used for city, state, country, neighborhood, municipality:

Geolocation Object#

Package Information#

Details about the shipment package:

Items#

Individual items contained in the shipment package:

Dimensions#

Package dimensions and weight specifications:

Requirements (Optional)#

Additional shipment requirements (pickup and delivery schedules and special treatments):

Pickup Object#

Delivery Object#

Schedule Object#

Location Metadata Object#

• Note: Requirements are optional and only included under certain flows

Request Examples#

Complete domestics shipment

jsonCopy
1{
2    "id": "10101033319242",
3    "transport_order_id": "5c81e696e69190a58c13d4de71816b743",
4    "direction": "forward",
5    "carrier_information": {
6        "contract": "contract",
7        "agency": {
8          "id": "id"
9        } 
10    },
11    "shipment_information": {
12        "sender": {
13            "full_name": "John Doe",
14            "first_name": "John",
15            "last_name": "Doe",
16            "phone": {
17                "number": "123456789"
18            },
19            "address": {
20                "address_line": "Route 36 1234",
21                "street_name": "Route 36",
22                "street_number": "1234",
23                "intersection": "intersection",
24                "comment": "comment",
25                "city": {
26                    "id": "TUVDQ1BVRXJ0b3F1aQ",
27                    "name": "Puerto Quito"
28                },
29                "state": {
30                    "id": "EC-P",
31                    "name": "Pichincha"
32                },
33                "country": {
34                    "id": "EC",
35                    "name": "Ecuador"
36                },
37                "neighborhood": {
38                    "name": "Puerto Quito"
39                },
40                "municipality": {},
41                "geolocation": {
42                    "geolocation_type": "GEOMETRIC_CENTER",
43                    "latitude": -0.12345,
44                    "longitude": -78.123456
45                }
46            }
47        },
48        "receiver": {
49            "full_name": "John Doe",
50            "first_name": "John",
51            "last_name": "Doe",
52            "phone": {
53                "number": "123456789"
54            },
55            "address": {
56                "address_line": "Route 1 SN",
57                "street_name": "Route 1",
58                "street_number": "SN",
59                "intersection": "intersection",
60                "comment": "comment",
61                "city": {
62                    "id": "TUVDQ0VMWmMyZWRj",
63                    "name": "El Carmen"
64                },
65                "state": {
66                    "id": "EC-M",
67                    "name": "Manabí"
68                },
69                "country": {
70                    "id": "EC",
71                    "name": "Ecuador"
72                },
73                "neighborhood": {
74                    "name": "El Carmen"
75                },
76                "municipality": {},
77                "geolocation": {
78                    "geolocation_type": "GEOMETRIC_CENTER",
79                    "latitude": -0.123456,
80                    "longitude": -79.123456789
81                }
82            }
83        },
84        "package": {
85            "items": [
86                {
87                    "item_id": "MEC656877602",
88                    "description": "Lamp",
89                    "quantity": 1
90                }
91            ],
92            "dimensions": {
93                "height": 13,
94                "width": 26,
95                "length": 37,
96                "weight": 1100
97            },
98            "amount": 13.5
99        }
100    },
101    "test": false,
102    "keyword": "3bc405c30cadb4e6eefdf0cff899abcf8234d761c9a3ea1b2f510601ae5fc504"
103}

Response#

Successful Response (HTTP 200)#

bashCopy
1HTTP 200 OK
2 --header 'Content-Type: application/json'
3 {
4    "id": "10101033319242",
5    "status":"AUTHORIZED",
6    "status_message":"OK",
7    "tracking_number": "ASDfgh123asd",
8    "authorization_information": {
9        "date": "2001-07-04T12:08:56.235-07:00",
10        "custom_data":{
11            "ruta_1":"RUTA"
12        }
13    }
14}

Authorization information object#

Failed Response (HTTP 400)#

bashCopy
1HTTP 400 Bad Request
2 --header 'Content-Type: application/json'
3 {
4    "error_code": "invalid_user_information.buyer",
5    "status_message":"Missing receiver information",
6    "status": "FAILED"
7}

Error Response (HTTP 500)#

bashCopy
1HTTP 500 Internal Server Error
2 --header 'Content-Type: application/json'
3 {
4    "status_message":"Internal server error",
5    "status": "ERROR"
6}

HTTP Status Codes & Errors#