Query Fiscal Data for Line Haul Routes#

Introduction#

This API serves fiscal data to carriers that are part of Mercado Libre's Middle Mile Line Haul transport.

Important: Make sure you have a valid application and token, and that you are authorized to use this endpoint. OAuth will be used for security.

Query by Route and Facility#

Given a Route ID and a Facility ID, this API returns the Shipments for the route along with the URL to obtain the Shipment details.

bashCopy
1GET https://api.mercadolibre.com/MLB/routes/{RouteID}/facilities/{FacilityID}/fiscal-info?offset=0&limit=3&access_token={token}

Example Request#

bashCopy
1GET https://api.mercadolibre.com/MLB/routes/1234567890/facilities/MELI123/fiscal-info?offset=0&limit=3&access_token=123*******************************123

Example Response#

jsonCopy
1{
2  "limit": 3,
3  "offset": 0,
4  "total_items": 110,
5  "route_id": 12345678,
6  "status": "accepted",
7  "facility_id": "mx001",
8  "route_type": "middle_mile",
9  "items": [
10    {
11      "id": "40000000000",
12      "href": "https://api.mercadolibre.com/MLB/routes/123/shipments/123/fiscal-info"
13    }
14  ]
15}

Response Fields#

Parameter	Type	Description
limit	Int	Defines the number of items per page, with a maximum allowed value of 500
total_items	Int	Total number of shipments in the route
route_id	Int	Route ID
status	String	Route status (accepted, canceled)
facility_id	String	Facility ID
route_type	String	Route type (middle_mile)
items	Array	Array of routes
items.id	String	Shipment ID
items.href	String	URL for shipment details

Shipment Detail Query API#

Given a Shipment ID, this API returns simplified data such as the NF-e Key, CT-e Key, and the corresponding links to download each XML file for each Shipment in the route.

bashCopy
1GET https://api.mercadolibre.com/MLB/routes/{RouteID}/shipments/{ShipmentID}/fiscal-info?access_token=accessToken

Example Request#

bashCopy
1GET https://api.mercadolibre.com/MLB/routes/1234567890/shipments/MELI123/fiscal-info?access_token=123*******************************123

Example Response#

jsonCopy
1{
2  "entity_id": "40000000000",
3  "entity_type": "shipment",
4  "route_id": 123456,
5  "route_type": "middle_mile",
6  "origin": {
7    "facility_id": "BRSP05",
8    "cnpj": "123456789",
9    "ie": "123456789",
10    "name": "Facility 01",
11    "address": {
12      "street_name": "Rua a",
13      "number": "1",
14      "neighborhood": "Bairro",
15      "city": "Cidade",
16      "city_code": "11",
17      "zipcode": "111111111",
18      "state": "SS",
19      "country": "BR",
20      "country_code": "11245"
21    }
22  },
23  "destination": {
24    "facility_id": "BRXSP9",
25    "cnpj": "123456789",
26    "ie": "123456789",
27    "name": "Facility 01",
28    "address": {
29      "street_name": "Rua a",
30      "number": "1",
31      "neighborhood": "Bairro",
32      "city": "Cidade",
33      "city_code": "11",
34      "zipcode": "111111111",
35      "state": "SS",
36      "country": "BR",
37      "country_code": "11245"
38    }
39  },
40  "fiscal_data": [
41    {
42      "invoice": {
43        "type": "nfe_document",
44        "amount": 104.37,
45        "key": "35210000000000000000000000000000000000000000",
46        "href": "https://api.mercadolibre.com/MLB/shipments/40000000000/nfe/35210000000000000000000000000000000000000000?doctype=xml"
47      },
48      "tax": {
49        "type": "ICMS",
50        "key": "35211111111111111111111111111111111111111111",
51        "href": "https://api.mercadolibre.com/MLB/shipments/40000000000/cte/35211111111111111111111111111111111111111111?doctype=xml"
52      }
53    }
54  ]
55}

Response Fields#

Parameter	Type	Description
id	String	Shipment ID
type	String	Shipment type
route_id	Int	Route ID
facility_id	String	Facility ID
origin	Object	Shipment origin
origin.facility_id	String	Origin facility ID
origin.cnpj	String	Origin facility CNPJ
origin.ie	String	Origin facility IE
origin.name	String	Origin facility name
origin.address.street_name	String	Origin facility street name
origin.address.number	String	Origin facility number
origin.address.neighborhood	String	Origin facility neighborhood
origin.address.city	String	Origin facility city
origin.address.city_code	String	Origin facility city code
origin.address.zipcode	String	Origin facility zip code
origin.address.state	String	Origin facility state
origin.address.country	String	Origin facility country
origin.address.country_code	String	Origin facility country code
destination	Object	Shipment destination
destination.facility_id	String	Destination facility ID
destination.cnpj	String	Destination facility CNPJ
destination.ie	String	Destination facility IE
destination.name	String	Destination facility name
destination.address.street_name	String	Destination facility street name
destination.address.number	String	Destination facility number
destination.address.neighborhood	String	Destination facility neighborhood
destination.address.city	String	Destination facility city
destination.address.city_code	String	Destination facility city code
destination.address.zipcode	String	Destination facility zip code
destination.address.state	String	Destination facility state
destination.address.country	String	Destination facility country
destination.address.country_code	String	Destination facility country code
fiscal_data	Object	Shipment fiscal data
fiscal_data.invoice.key	String	Invoice (NF-e) key
fiscal_data.invoice.type	String	Document type (nfe_document, dce_document)
fiscal_data.invoice.href	String	URL to download the NF-e file
fiscal_data.tax.key	String	CT-e key
fiscal_data.tax.type	String	Document type (ICMS or ISS)
fiscal_data.tax.href	String	URL to download the CT-e file

Additional Notes#

The fiscal_data attribute is a list of fiscal documents (i.e., NF-e and CT-e) per package. It always has two attributes for each package: invoice with NF-e related data; and tax with transport fiscal document data.

In tax, there is a type attribute that can take the following values:

• ICMS: Indicates that Mercado Libre issued the umbrella CT-e for this package. It is the Carrier's responsibility to issue the redispatch CT-e, referencing the umbrella CT-e. The XML document can be obtained from the document.href attribute.
• No_Tax: Indicates this is a 1P package. Mercado Libre did not issue any CT-e, and it is the Carrier's responsibility to issue the umbrella CT-e referencing the package NF-e.
• ISS: Indicates transport within the same city, so no CT-e was issued by Mercado Libre, nor should it be issued by the Carrier. There is also another ISS scenario: ISS corresponds to transport within the same city or collection, forwarding or delivery of correspondence, documents, objects, goods or values, taxed by ISS according to LC 116/2003.

Status Code Examples#

If an error occurs, the API will return an HTTP status other than 200, an error message, the error, its cause, and content-type will be application/json.

404 (NOT_FOUND)#

jsonCopy
1{
2  "message": "An error occurred while trying to get route details",
3  "error": "unexpected_error",
4  "status": 404,
5  "cause": [
6    "error_getroute"
7  ]
8}

HTTP Code	Content Type	Response Body	Description
200	application/xml	XML (example above)	When fiscal data is successfully retrieved.
404	application/json	{ "message": "An error occurred while trying to get route details" }	When an incorrect Route ID or Facility ID is provided.