How to Obtain Shipping Tax Data

Introduction

Carrito V3 (Cart V3) is a sales modality that enables purchasing products from multiple sellers in a single transaction. However, each seller involved will have their own NF-e and, consequently, a CT-e for each. Currently, the carrier Authorization only contains data from a single NF-e linked to the shipment, which does not cover the Cart V3 scenario that involves multiple NF-es.

Motivation

With the possibility of buying several items from different sellers, we have improved the shopping experience where the buyer can satisfy all their expectations in a single shipment. Another possibility is the reduction of costs with taxes paid per shipment, meaning that we will theoretically have multiple shipments in a single consolidated shipment. We will be acting more effectively in the area of CPG (Consumer Packaged Goods) — everyday products that require routine replacement or replenishment, such as food, beverages, clothing, tobacco, makeup, and household products.

Changes

Compared to the previous flow, where the carrier received the invoice information via the authorization and then downloaded the CT-e by shipment_id, the following changes apply:

The shipping authorization request will no longer contain invoice information.
CT-e download will be done based on the CT-e key instead of using the shipment_id.
Two new endpoints: a. Query of the shipment fiscal information b. Download of the CT-e by CT-e key
The fiscal data set has a list of fiscal_data, which enables returning fiscal data per seller involved in the shipment.

Example Authorization Response

json
1{
2  "id": 2030000028238160035,
3  "tracking_number": "07965900009961",
4  "status": "AUTHORIZED",
5  "service_id": 263,
6  "shipment_information": {
7    "sender": {
8      "address": {
9        "zip_code": "07750020",
10        "facility_id": "XD_CAJAMAR",
11        "country": {"id": "BR", "name": "Brasil"},
12        "address_line": "Av. Dr. Antonio Joao Abdalla, 3333",
13        "city": {"id": "QlItU1BDYWphbWFy", "name": "Cajamar"},
14        "street_number": "3333",
15        "state": {"id": "BR-SP", "name": "São Paulo"},
16        "street_name": "Av. Dr. Antonio Joao Abdalla"
17      },
18      "full_name": "AGUINALDO RODRIGUES ELETRONICO - EPP",
19      "id": 29223162
20    },
21    "receiver": {
22      "address": {
23        "zip_code": "51111030",
24        "city": {"id": "TUxCQ1JFQzM2M2M", "name": "Recife"},
25        "state": {"id": "BR-PE", "name": "Pernambuco"},
26        "street_name": "Rua José Aderval Chaves"
27      },
28      "full_name": "Ricardo Costa",
29      "id": 71087276
30    },
31    "invoice_data": {
32      "key": "35200207427215000132550030000864941337802996",
33      "number": "86494",
34      "serie": "3",
35      "amount": 239.9,
36      "cfop": 6102
37    }
38  },
39  "carrier": "jadlog",
40  "logistic": "cross_docking"
41}

Important: OAuth will be used for security.

Request

After receiving the authorization, the carrier with the shipment_id can access the address below and retrieve fiscal information such as the NF-e key (invoice_key) and the CT-e key (cte_key) (remember to add the security token to the request).

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

After the carrier queries the invoice data, they must iterate through all fiscal data and download the XML using the URL found in fiscal_data.tax.document.href (remember to add the security token to the request).

bash
1GET https://api.mercadolibre.com/shipments/cte/{cte_key}?doctype=xml&access_token={access_token}

Response

json
1{
2  "_links": {
3    "base": "https://api.mercadolibre.com/",
4    "context": "",
5    "next": "/shipments/28243789533/fiscal-info?offset=0&limit=30",
6    "self": "/shipments/28243789533/fiscal-info?offset=0&limit=30"
7  },
8  "limit": 30,
9  "offset": 0,
10  "shipment_id": 28238160035,
11  "receiver_identification": {
12    "number": "03410211489",
13    "state_tax_id": null,
14    "type": "CPF"
15  },
16  "fiscal_data": [
17    {
18      "tax": {
19        "cte_key": "35191220121850000821571060095350571655690068",
20        "tax_type": "ICMS",
21        "document": {
22          "type": "cte_document",
23          "href": "https://api.mercadolibre.com/shipments/cte/35191220121850000821571060095350571655690068?doctype=xml",
24          "format": "xml"
25        }
26      },
27      "invoice": {
28        "key": "35200207427215000132550030000864941337802996",
29        "number": "86494",
30        "serie": "3",
31        "amount": 239.9,
32        "date": "2020-02-02T00:00:00.000-04:00",
33        "cfop": 6102
34      },
35      "sender_identification": {
36        "number": "14605717000171",
37        "state_tax_id": "241067120110",
38        "type": "CNPJ"
39      }
40    },
41    {
42      "tax": {
43        "cte_key": "35191220121850000821571060095350571655690068",
44        "tax_type": "ICMS",
45        "document": {
46          "type": "cte_document",
47          "href": "https://api.mercadolibre.com/shipments/cte/35191220121850000821571060095350571655690068?doctype=xml",
48          "format": "xml"
49        }
50      },
51      "invoice": {
52        "key": "35200207427215000132550030000864941337802996",
53        "number": "86494",
54        "serie": "3",
55        "amount": 239.9,
56        "date": "2020-02-02T00:00:00.000-04:00",
57        "cfop": 6102
58      },
59      "sender_identification": {
60        "number": "14605717000172",
61        "state_tax_id": "241067120220",
62        "type": "CNPJ"
63      },
64      "tax_type": "ICMS"
65    }
66  ]
67}

CT-e XML Response

xml
1<?xml version="1.0" encoding="UTF-8"?>
2<cteProc xmlns="http://www.portalfiscal.inf.br/cte" versao="3.00">
3  <CTe>
4    ... XML omitted
5  </CTe>
6  <protCTe versao="3.00">
7    <infProt>
8      <tpAmb>1</tpAmb>
9      <verAplic>SP-CTe-26-02-2018</verAplic>
10      <chCTe>35180420121850000155570010054409561830177379</chCTe>
11      <dhRecbto>2018-04-26T11:54:20-03:00</dhRecbto>
12      <nProt>135181188883185</nProt>
13      <digVal>Dudrm+WP0Jrv1D3dMHaJtoK0ibo=</digVal>
14      <cStat>100</cStat>
15      <xMotivo>Autorizado o uso do CT-e</xMotivo>
16    </infProt>
17  </protCTe>
18</cteProc>

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

Pagination Fields (_links)

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
shipment_id	Int	Order ID
receiver_identification	Object	Buyer data
number	String	Document number
state_tax_id	String	State Tax ID (IE)
type	String	Document type
fiscal_data	Object	Order fiscal data

The _link object is responsible for controlling the pagination data of the fiscal-info elements, which is based on the offset field passed in the request parameters. The next field is responsible for informing the endpoint of the next document in the pagination, and it is set to an empty value when no further pagination is needed. The next page URL is formed by _link.base + _link.context + _link.next + security parameters.

Fiscal Data Fields

Parameter	Type	Description
sender_identification	Object	Seller data
number	String	Document number
type	String	State Tax ID (IE)
state_tax_id	String	Document type
invoice	Object	Invoice data
key	String	NF-e key
number	Int	NF-e number
serie	Int	Series
amount	Float	Total value
date	Date	Issue date
cfop	Int	CFOP
tax	Object	Fiscal data
type	String	Fiscal taxation type (ISS or ICMS)
cte_key	String	CT-e key
document	Object	Fiscal document data
type	String	Document type
href	String	Document query URL
format	String	Document format

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
200	application/json	JSON (example above)	Returns a JSON with shipment data and a list (fiscal_data).
400	application/json	400 Response above	There is a problem with the request sent; the message field contains a brief description. The client should not repeat this request without modifying it; repeated insistence may result in temporary blocking.

How to Obtain Shipping Tax Data#

Introduction#

Motivation#

Changes#

Example Authorization Response#

Request#

Response#

CT-e XML Response#

Pagination Fields (_links)#

Fiscal Data Fields#

Status Code Examples#

400 (NOT_OK)#