Query Fiscal Information for Logistics

Introduction

The Logistics Taxes API aims to provide fiscal data to carriers that are part of the transportation process and want to access the CT-e and NF-e from MELI. Given a route ID, this API returns simplified data such as the NF-e Key, CT-e Key, and the respective download links for each XML of each shipment in the route.

Important: OAuth will be used for security.

Request

bash
1GET https://api.mercadolibre.com/routes/12345678/fiscal-info?offset=0&limit=3&access_token=accessToken

Response

json
1{
2  "_links": {
3    "base": "https://api.mercadolibre.com",
4    "context": "",
5    "next": "https://api.mercadolibre.com/routes/12345678/fiscal-info?offset=0&limit=3&access_token=accessToken",
6    "self": "routes/12345678/fiscal-info?offset=0&limit=3&access_token=accessToken"
7  },
8  "limit": 3,
9  "offset": 0,
10  "id": 12345678,
11  "route_type": "last_mile",
12  "entity": [
13    {
14      "ID": "40000000000",
15      "type": "shipment",
16      "fiscal_data": [
17        {
18          "invoice": {
19            "key": "35210000000000000000000000000000000000000000",
20            "document": {
21              "type": "nfe_document",
22              "href": "https://api.mercadolibre.com/shipping-tax-develop/gateway/shipments/40000000000/nfe/35210000000000000000000000000000000000000000?doctype=xml",
23              "format": "xml"
24            }
25          },
26          "tax": {
27            "cte_key": "35211111111111111111111111111111111111111111",
28            "type": "ICMS",
29            "document": {
30              "type": "cte_document",
31              "href": "https://api.mercadolibre.com/shipping-tax-develop/gateway/cte/fiscal/35211111111111111111111111111111111111111111/download?doctype=xml",
32              "format": "xml"
33            }
34          }
35        }
36      ]
37    },
38    {
39      "ID": "41111111111",
40      "type": "shipment",
41      "error": "Fiscal info not found",
42      "fiscal_data": []
43    },
44    {
45      "ID": "42222222222",
46      "type": "shipment",
47      "fiscal_data": [
48        {
49          "invoice": {
50            "key": "41210444444444444444444444444444444444444444",
51            "document": {
52              "type": "nfe_document",
53              "href": "https://api.mercadolibre.com/shipping-tax-develop/gateway/shipments/42222222222/nfe/41210444444444444444444444444444444444444444?doctype=xml",
54              "format": "xml"
55            }
56          },
57          "tax": {
58            "cte_key": "41210555555555555555555555555555555555555555",
59            "type": "ICMS",
60            "document": {
61              "type": "cte_document",
62              "href": "https://api.mercadolibre.com/shipping-tax-develop/gateway/cte/fiscal/41210555555555555555555555555555555555555555/download?doctype=xml",
63              "format": "xml"
64            }
65          }
66        }
67      ]
68    }
69  ]
70}

Fiscal Info by Route

In this endpoint, when querying a route that contains a 1P Seller shipment, CT-e data will not be returned for that shipment — only the Invoice (NF-e). However, it is possible to have both 1P and 3P shipments in the same route. In that case, there will be records with Invoice and CT-e for 3P operations, and records with Invoice only for 1P operations. If the route contains only 3P packages, there will be no change in the contract. For 3P shipments, the same current workflow applies: the Carrier must issue its CT-e linked to the MELI Normal CT-e (Umbrella). For 1P shipments, the Carrier must use the NF-e to issue a Normal CT-e, referencing the NF-e. Both the CT-e download link (when available) and the NF-e link will be included in the response obtained when querying fiscal info by route.

json
1{
2  "_links": {
3    "base": "https://api.mercadolibre.com",
4    "context": "",
5    "next": "https://api.mercadolibre.com/routes/12345678/fiscal-info?offset=0&limit=3&access_token=accessToken",
6    "self": "routes/12345678/fiscal-info?offset=0&limit=3&access_token=accessToken"
7  },
8  "limit": 3,
9  "offset": 0,
10  "id": 12345678,
11  "route_type": "last_mile",
12  "entity": [
13    {
14      "ID": "40000000000",
15      "type": "shipment",
16      "fiscal_data": [
17        {
18          "invoice": {
19            "key": "35210000000000000000000000000000000000000000",
20            "document": {
21              "type": "nfe_document",
22              "href": "https://api.mercadolibre.com/shipping-tax-develop/gateway/shipments/40000000000/nfe/35210000000000000000000000000000000000000000?doctype=xml",
23              "format": "xml"
24            }
25          }
26        }
27      ]
28    },
29    {
30      "ID": "41111111111",
31      "type": "shipment",
32      "error": "Fiscal info not found",
33      "fiscal_data": []
34    },
35    {
36      "ID": "42222222222",
37      "type": "shipment",
38      "fiscal_data": [
39        {
40          "invoice": {
41            "key": "41210444444444444444444444444444444444444444",
42            "document": {
43              "type": "nfe_document",
44              "href": "https://api.mercadolibre.com/shipping-tax-develop/gateway/shipments/42222222222/nfe/41210444444444444444444444444444444444444444?doctype=xml",
45              "format": "xml"
46            }
47          }
48        }
49      ]
50    }
51  ]
52}

The return is an array per entity/type. If no fiscal data is found for a specific entity, we will return an "error": "Fiscal info not found" and an empty "fiscal_data" struct, as shown in the example above.

Response Fields

Name	Data Type	Description
_link	object	Pagination data
base	String	Base URL
context	String	Application context
next	String	Endpoint for the next document in the pagination
self	String	Endpoint for the current document in the pagination
limit	int	Number of documents per page
offset	int	Number of documents to skip before returning records
id	int	Route ID
route_type	string	Route step: FirstMile, MiddleMile, LastMile
entity	object	Array of objects with fiscal data per order
ID	int	Shipment ID (ShipmentID or InboundShipmentID)
type	string	Shipment type (Shipment or InboundShipment)
Error	string	Error type reported for that entity. E.g.: Fiscal info not found
fiscal_data	object	Fiscal data of a shipment/inbound shipment. Contains two objects: invoice and tax
Invoice	object	Data related to an electronic invoice (NF-e)
tax	object	Data related to a CT-e or ISS
key	string	Fiscal key of the NF-e or CT-e
document	object	Data related to an NF-e or CT-e document
type	string	Document type: nfe_document, ICMS/ISS (CT-e)
href	string	Download link for the NF-e or CT-e file
format	string	Document format: XML or PDF

The _link object controls pagination data for fiscal-info elements, based on the limit and offset fields passed in the request parameters. The next field indicates the endpoint for the next page, and is left empty when no further pagination is needed. The next page URL is formed by: _link.base + _link.context + _link.next + security parameters.

Additional Notes

The fiscal_data attribute is a list of fiscal documents (NF-e and CT-e) per package. It will always contain two attributes for each package: invoice with NF-e related data; and tax with transport fiscal document data. The tax attribute has a type field that can take the following values: ICMS: Indicates that Mercado Livre has issued the umbrella CT-e for this package, and 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 Livre has not issued any CT-e, and it is the Carrier's responsibility to issue the umbrella CT-e referencing the package's NF-e. ISS: Represents transport within the same city, so the CT-e was not issued by Mercado Livre, nor should it be issued by the Carrier. However, there is another situation where ISS applies: transport within the same city or collection, delivery of correspondence, documents, goods, or valuables, taxed under ISS according to LC 116/2003 — in this case neither Mercado Livre nor the Carrier should issue a CT-e.

HTTP 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 the content-type will be application/json.

400 (NOT_OK)

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

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

Query Fiscal Information for Logistics#

Introduction#

Request#

Response#

Fiscal Info by Route#

Response Fields#

Additional Notes#

HTTP Status Code Examples#

400 (NOT_OK)#