Fiscal Information Query for Cart V3

Introduction

The Logistics Taxes API aims to serve fiscal data to carriers that are part of the transport and want to access the CT-e and NF-e from MELI. In this endpoint, when querying a 1P Seller shipment, it will not return CT-e data, only Invoice (NF-e). However, it is possible to have both 1P and 3P shipments in the same Cart V3. In this case, there will be records with Invoice and CT-e for 3P operations, and records with only Invoice for 1P operations. If the Cart V3 has only 3P packages, there will be no change to the contract. For 3P shipments, the current workflow is maintained. 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, linking the NF-e. Both the CT-e download link (when available) and the NF-e download link will be in the response obtained when querying the fiscal info by Cart V3 Shipment.

Important: OAuth will be used for security.

Request

bash
1GET https://api.mercadolibre.com/shipments/{ShipmentID}/fiscal-info?offset=0&limit=3&access_token=accessToken

Response

The API returns fiscal data for the requested shipment. Below are examples of the response in different scenarios:

Mixed 1P and 3P Example

json
1{
2  "_links": {
3    "base": "https://api.mercadolibre.com",
4    "context": "",
5    "next": "",
6    "self": "shipments/41570716111/fiscal-info?offset=0&limit=50"
7  },
8  "limit": 50,
9  "offset": 0,
10  "id": 41570716111,
11  "receiver_identification": {
12    "number": "32844571867",
13    "type": "CPF"
14  },
15  "fiscal_data": [
16    {
17      "sender_identification": {
18        "number": "37411383000109",
19        "type": "CNPJ",
20        "state_tax_id": "0037539980010"
21      },
22      "invoice": {
23        "key": "31220837411383000109550030000155146590713514",
24        "number": 15514,
25        "serie": 3,
26        "amount": 54.9,
27        "date": "2022-08-08T14:57:11-03:00",
28        "cfop": 6106,
29        "document": {
30          "type": "nfe_document",
31          "href": "https://api.mercadolibre.com/shipping-tax-develop/gateway/shipments/41570716111/nfe/...",
32          "format": "xml"
33        }
34      },
35      "tax": {
36        "cte_key": "31220820121850002956573000000014471215694142",
37        "type": "ICMS",
38        "document": {
39          "type": "cte_document",
40          "href": "https://api.mercadolibre.com/shipping-tax-develop/gateway/cte/fiscal/.../download?doctype=xml",
41          "format": "xml"
42        }
43      }
44    },
45    {
46      "sender_identification": {
47        "number": "03007331001032",
48        "type": "CNPJ",
49        "state_tax_id": "0038450760305"
50      },
51      "invoice": {
52        "key": "31220803007331001032550010054774626670522538",
53        "number": 5477462,
54        "serie": 1,
55        "amount": 47.35,
56        "date": "2022-08-08T14:56:33-03:00",
57        "cfop": 6108,
58        "document": {
59          "type": "nfe_document",
60          "href": "https://api.mercadolibre.com/shipping-tax-develop/gateway/shipments/41570716111/nfe/...",
61          "format": "xml"
62        }
63      }
64    }
65  ]
66}

1P Only Example

json
1{
2  "_links": {
3    "base": "https://api.mercadolibre.com",
4    "context": "",
5    "next": "",
6    "self": "shipments/41570716111/fiscal-info?offset=0&limit=50"
7  },
8  "limit": 50,
9  "offset": 0,
10  "id": 41570716111,
11  "fiscal_data": [
12    {
13      "sender_identification": { "number": "03007331001032", "type": "CNPJ", "state_tax_id": "0038450760305" },
14      "invoice": {
15        "key": "31220803007331001032550010054774626670522538",
16        "number": 5477462,
17        "serie": 1,
18        "amount": 47.35,
19        "date": "2022-08-08T14:56:33-03:00",
20        "cfop": 6108,
21        "document": { "type": "nfe_document", "href": "...", "format": "xml" }
22      }
23    }
24  ]
25}

3P Only Example

json
1{
2  "_links": {
3    "base": "https://api.mercadolibre.com",
4    "context": "",
5    "next": "",
6    "self": "shipments/41570716111/fiscal-info?offset=0&limit=50"
7  },
8  "limit": 50,
9  "offset": 0,
10  "id": 41570716111,
11  "fiscal_data": [
12    {
13      "sender_identification": { "number": "37411383000109", "type": "CNPJ", "state_tax_id": "0037539980010" },
14      "invoice": {
15        "key": "31220837411383000109550030000155146590713514",
16        "number": 15514,
17        "serie": 3,
18        "amount": 54.9,
19        "date": "2022-08-08T14:57:11-03:00",
20        "cfop": 6106,
21        "document": { "type": "nfe_document", "href": "...", "format": "xml" }
22      },
23      "tax": {
24        "cte_key": "31220820121850002956573000000014471215694142",
25        "type": "ICMS",
26        "document": { "type": "cte_document", "href": "...", "format": "xml" }
27      }
28    }
29  ]
30}

The return is an array per entity/type. If no fiscal data is found for a specific entity, an "error": "Fiscal info not found" will be returned and the "fiscal_data" struct will be empty.

Response Parameters

Parameter	Type	Description
_link	object	Pagination data.
base	String	Base URL.
context	String	Application context.
next	String	Endpoint for the next document in pagination.
self	String	Endpoint for the current document in 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	ID of a shipment. (ShipmentID or InboundShipmentID)
type	string	Type of a shipment. (Shipment or InboundShipment)
Error	string	Type of error reported for that entity. E.g.: Fiscal info not found.
fiscal_data	object	Fiscal data of a shipment/inbound shipment. Contains two objects: the invoice object and the tax object.
Invoice	object	Data related to an Invoice (NF-e).
tax	object	Data related to a CT-e or ISS.
key	string	Fiscal key of the invoice or CT-e.
document	object	Data related to an Invoice or CT-e.
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 provides the endpoint for the next document in pagination and is set to empty when no further pagination is needed. The next page URL is formed by: _link.base + _link.context + _link.next + security parameters.

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)	Successfully retrieved fiscal data.
404	application/json	{"message": "An error occurred while trying to get route details"...}	When an incorrect route ID is passed.

Fiscal Information Query for Cart V3#

Introduction#

Request#

Response#

Mixed 1P and 3P Example#

1P Only Example#

3P Only Example#

Response Parameters#

Status Code Examples#

400 (NOT_OK)#