Query Fiscal Information for MWH

Introduction

This API aims to provide fiscal data to carriers involved in the transportation process who want to access CT-e and NF-e from Mercado Livre. The carrier, using the hug_id (shipment identifier), can access the endpoint below to retrieve fiscal information, including the download link for the XML of the electronic Invoice (NF-e) and the download link for the XML of the electronic Transport Knowledge Document (CT-e).

Important: OAuth will be used for security.

Request

bash
1GET https://api.mercadolibre.com/dispatches/{hug_id}/fiscal-info?access_token={token}&offset={offset}

Request Parameters

Name
Data Type
Description
Type
hug_idStringShipment identifier
tokenStringAuthentication token
offsetIntegerThis query is paginated. You must specify the page index to retrieve. When offset is not provided, the default value is 0.

How to Obtain the Request Parameters?

In the upper right corner of the transport document provided to the driver at the start of transport, there is a barcode containing the shipment identifier (hug_id). Below this barcode, the hug_id is also printed in plain text, as shown in the figure (highlighted in red).

Response

json
1{
2  "_links": {
3    "base": "https://api.mercadolibre.com/",
4    "context": "",
5    "next": "dispatches/{hug_id}/fiscal-info?offset=50",
6    "self": "dispatches/{hug_id}/fiscal-info?offset=0"
7  },
8  "offset": 0,
9  "id": "{hug_id}",
10  "fiscal_data": [{
11    "invoice": {
12      "document": {
13        "type": "nfe_document",
14        "href": "https://api.mercadolibre.com/dispatches/{hug_id}/invoices/{invoice_id}/download?doctype=xml",
15        "format": "xml"
16      }
17    },
18    "tax": {
19      "cte_key": "{cte_key}",
20      "type": "ICMS",
21      "document": {
22        "type": "cte_document",
23        "href": "https://api.mercadolibre.com/shipments/cte/{cte_key}?doctype=xml",
24        "format": "xml"
25      }
26    }
27  }]
28}

Fiscal Info by Dispatch (MWH/HUG)

In this endpoint, when querying a dispatch 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 dispatch. 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 dispatch contains only 3P packages, there will be no change to the contract. For 3P shipments, the same current workflow applies: the carrier issues its CT-e (Redispatch) 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 dispatch.

json
1{
2  "_links": {
3    "base": "https://api.mercadolibre.com/",
4    "context": "",
5    "next": "dispatches/{hug_id}/fiscal-info?offset=50",
6    "self": "dispatches/{hug_id}/fiscal-info?offset=0"
7  },
8  "offset": 0,
9  "id": "{hug_id}",
10  "fiscal_data": [{
11    "invoice": {
12      "document": {
13        "type": "nfe_document",
14        "href": "https://api.mercadolibre.com/dispatches/{hug_id}/invoices/{invoice_id}/download?doctype=xml",
15        "format": "xml"
16      }
17    },
18    "tax": {
19      "type": "No_Tax",
20      "document": {}
21    }
22  }]
23}

The "fiscal_data" attribute is a list of all fiscal documents (NF-e and CT-e) per package. It should 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.

Note: When the "tax" attribute is not present, it means an error occurred during the processing of the package. In this case, a support ticket must be opened for the appropriate corrections and reprocessing.

Response Fields

Name
Data Type
Description
Type
_linkobjectPagination data
baseStringBase URL
contextStringApplication context
nextStringEndpoint for the next document in the pagination
selfStringEndpoint for the current document in the pagination
offsetintNumber of documents to skip before returning records
IDintDispatch ID
fiscal_dataobjectFiscal data for the dispatch

The _link object controls pagination data for fiscal-info elements, based on the offset field 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.

Fiscal Data Fields

Name
Data Type
Description
Type
invoice / tax dataobjectPagination data
documentobjectFiscal document data (NF-e or CT-e)
typestringDocument type
hrefstringDocument query URL
formatstringDocument format

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": "description",
3  "error": "bad_request",
4  "status": 400,
5  "cause": []
6}
HTTP Code
Content Type
Response Body
Description
200application/xmlXML (example above)Returns XML with shipment data and a list (fiscal_data).
400application/jsonResponse of 400 aboveThere is a problem with the request sent. The message field contains a brief description. The client should not repeat the request without modifying it, as repeated attempts may result in a temporary block.