Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
Documentación
Obtener Documento fiscal
Contenidos
→Obtener documento fiscal
↳Por invoice id
↳Order id
↳Shipment id
↳Mes
↳Período específico
↳Filtros y CT-e
→Documento fiscal de venta
→Documento fiscal de compra
→Documento fiscal de devolución
→Documento fiscal de full
→Otros
→Tipo de archivo
→Carpeta simple
→Tipos de documentos fiscales
Obtener documento fiscal
En cada cambio de status, enviamos una notificación en el feed, tan pronto como el estado de la nota sea AUTHORIZED. Puedes acceder al XML a través de un GET a invoice, que puedes hacerlo de tres maneras por invoice_id, order_id o shipping_id. El XML estará disponible en el campo "xml_location" con la llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/134608322/invoices/documents/xml/1377978/authorizedPor invoice_id
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/users/134608322/invoices/1377978{
"id": "1377978",
"status": "authorized",
"transaction_status": "authorized",
"issuer": {
"name": "SBC PECAS COMERCIO DE ACESSORIOS AUTOMOTIVOS LTDA - ME",
"identifications": {
"cnpj": "20509470000273",
"crt": "simples",
"ie": "421042391111",
"ie_type": "contribuinte"
},
"phone": {
"area_code": "00",
"number": "26697058"
},
"address": {
"street_name": "Wagner Luiz Bevilaqua",
"street_number": "525",
"complement": null,
"neighborhood": "Leitão",
"city": "Louveira",
"zip_code": "13290000",
"state": "SP",
"country": "BR"
},
"user_id": "134608322",
"brand_name": "SBC Peças"
},
"recipient": {
"name": "José Eduardo Walter",
"identifications": {
"cpf": "96090707791"
},
"phone": {
"area_code": "15",
"number": "997590252"
},
"address": {
"street_name": "Est. Sertão do Cantagalo Km 75",
"street_number": "SN",
"complement": "Pousada Bicho do Mato",
"neighborhood": "Sertão do Cantagalo",
"city": "Gonçalves",
"zip_code": "37680000",
"state": "MG",
"country": "BR"
},
"external_recipient_id": "117211025"
},
"shipment": {
"id": "27691874117",
"site_id": "MLB",
"mode": "me2",
"logistic_type": "fulfillment",
"buyer_cost": 0,
"paid_by": "third_party",
"carrier": {
"name": "MERCADO ENVIOS SERVICOS DE LOGISTICA LTDA.",
"identifications": {
"cnpj": "20121850000317",
"crt": null,
"ie": "421037004110",
"ie_type": "contribuinte"
},
"phone": {
"area_code": "11",
"number": "25434155"
},
"address": {
"street_name": "R WAGNER LUIS BELIVAQUA",
"street_number": "525",
"complement": "PARTE Q",
"neighborhood": "LEITAO",
"city": "Louveira",
"zip_code": "13290000",
"state": "SP",
"country": "Brasil"
}
},
"volumes": [
{
"net_weight": 0.51,
"gross_weight": 0.51
}
],
"fiscal_model_id": null
},
"items": [
{
"id": "134608322_PRODUCTION_1377978_1",
"invoice_id": "1377978",
"seller_id": "134608322",
"external_order_id": "1812965285",
"external_product_id": "MLB711664692",
"external_variant_id": "25609933367",
"attributes": {
"ean": null,
"sku": "55K",
"type": null
},
"product_name": "Jogo Kit Com 4 Lente Lanterna Spacefox 2006 2007 2008 2009 - Cor da lente Transparente, Lado Esquerdo e direito",
"quantity": 1,
"total_amount": 178,
"shipping_buyer_cost": 0,
"discount_amount": null,
"fiscal_data": {
"attributes": {
"ncm": "85122022",
"cest": null,
"origin_type": "reseller",
"origin_detail": "2",
"cfop": "6108",
"measurement_unit": "UN"
},
"messages": [
{
"type": "ITEM",
"content": "Total aproximado de tributos federais, estaduais e municipais: R$75,06"
}
],
"rules": [
{
"name": "IBPT",
"attributes": {
"municipal_tax": 0,
"vibpt": 75.06,
"pibpt": 42.17,
"federal_national_tax": 17.17,
"messages": null,
"federal_imported_tax": 23.52,
"state_tax": 25
}
},
{
"name": "ICMS_SIMPLES",
"attributes": {
"csosn": "102"
}
},
{
"name": "COFINS",
"attributes": {
"vcofins": 0,
"pcofins": 0,
"cst": "99",
"vbc": 178
}
},
{
"name": "PIS",
"attributes": {
"vpis": 0,
"cst": "99",
"vbc": 178,
"ppis": 0
}
}
]
}
}
],
"issued_date": "2018-09-19T19:40:52.008Z",
"invoice_series": "1",
"invoice_number": 1435,
"attributes": {
"cnf": "77058020",
"order_source": "meli",
"invoice_key": "35180920509470000273550010000014351770580200",
"environment_type": "production",
"xml_version": "4.00",
"status_code": 100,
"status_description": "Autorizado o uso da NF-e",
"receipt": "351004982681604",
"receipt_date": "2018-09-19T19:40:53",
"invoice_creation_date": "2018-09-19T19:40:51",
"protocol": "135180640697324",
"invoice_type": "normal",
"emission_type": "normal",
"authorization_date": "2018-09-19T19:40:55",
"cancellation_protocol": null,
"cancellation_date": null,
"cancellation_reason": null,
"cancellation_error_code": null,
"cancellation_error_description": null,
"correction_letter": null,
"reference_invoice": null,
"reference_invoices": null,
"danfe_location": "/users/134608322/invoices/sites/MLB/documents/danfe/1377978",
"xml_location": "/users/134608322/invoices/documents/xml/1377978/authorized",
"include_freight": true
},
"fiscal_data": {
"customer_type": "b2c",
"transaction_type": "sale",
"transaction_type_description": "Venda de mercadoria para consumidor final",
"messages": [
{
"type": "FISCAL",
"content": "Emitido por ME/EPP optante do Simples Nacional."
},
{
"type": "COMPL",
"content": "Valor aproximado dos tributos (IBPT) R$75,06."
}
],
"fiscal_amounts": [
{
"name": "pis",
"attributes": {
"vpis": 0
}
},
{
"name": "ibpt",
"attributes": {
"vtottrib": 75.06
}
},
{
"name": "icms_simples",
"attributes": {
"vbcst": 0,
"vst": 0,
"vicms": 0,
"vbc": 0,
"vicmsdeson": 0
}
},
{
"name": "cofins",
"attributes": {
"vcofins": 0
}
},
{
"name": "discount",
"attributes": {
"amount": 0
}
}
]
},
"amount": 178,
"items_amount": 178,
"errors": [],
"items_quantity": 1
}Por order_id
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/users/134608322/invoices/orders/1812965285Por shipment_id
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/users/134608322/invoices/shipments/27691874117O las notas pueden ser descargadas por mês en formato de .zip de la seguinte manera:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/users/USER_ID/invoices/sites/MLB/batch_request/period/AAAAMMSi usted es vendedor y trabaja en el modelo OL Portaria y necesita implementar un flujo más preciso de auditoría y control sobre la emisión de sus facturas, puedes consultar toda la cadena de facturas existentes y sus respectivos estados.
Los documentos fiscales devueltos en reference_invoices se refieren a los otros documentos vinculados, por ejemplo: documento de transferencia y devolución simbólica para el modelo Fullfilment Portaria. Siempre es posible consultar el estado de cualquier factura a través de los campos status y transaction_status.
En resumen, cada documento fiscal de venta (de vendedor a comprador) está vinculado a un documento de devolución simbólica (de Mercado Libre Fulfillment a Matriz del vendedor), que a su vez está vinculado a un documento fiscal de inbound o envío (de atriz del vendedor a Mercado Libre Fulfillment).
Y aún así, puedes descargar los documentos fiscales en formato .zip, de las siguientes maneras:
Por mes
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/users/USER_ID/invoices/sites/MLB/batch_request/period/AAAAMMPor período específico
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/users/USER_ID/invoices/sites/MLB/batch_request/period/stream?start=AAAAMMDD&end=AAAAMMDDAl realizar la descarga, estaremos segmentando los archivos en carpetas. Nombre de las carpetas: "emitidas_mercado_livre" y "emitidas_outro_erp", siendo que en la carpeta "emitidas_mercado_livre" vem as notas de venda, inbound, etc. e na pasta "emitidas_outro_erp" solamente los documentos importados para las ventas en Colectas.
Ejemplo:
Por filtros y CT-e
Ya podemos utilizar filtros y bajar CT-e si utilizamos la API pasando los parámetros necesarios:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/users/USER_ID/invoices/sites/MLB/batch_request/period/stream?start=AAAAMMDD&end=AAAAMMDD&sale=all&return=all&full=all&others=all&file_types=xml,pdf&simple_folder=falsePara la utilización de los filtros, algunos parámetros son obligatorios: "sale", "return", "full", "others", "fileType" e "simpleFolder". Ahora explicaremos cómo usar cada uno de ellos:
Documento fiscal de venta
- Pasar los filtros de status en el parámetro "sale"
- Pasar el parámetro "caller.type" com el valor "seller" o no pasar el parámetro "caller.type"
Ejemplo: sale=authorized, canceled, forbidden_disablement
Donde:
"authorized": notas autorizadas
"canceled": notas canceladas
"forbidden_disablement": Notas negadas o inutilizadas
** En caso que no quiera filtrar, pasar el valor "all" en ese filtro (sale=all)
Documento fiscal de compra
- Pasar el parámetro "caller.type" con el valor "buyer"
Ejemplo: caller.type=buyer
Donde:
"seller": Notas de venta
"buyer": Notas de compra
** Si no fuera enviado el parámetro "caller.type" serán devueltas las notas de venta ("seller" es el valor default)
Los documentos fiscales de compras son generados y separado por dos accesos "NF-e de compra" y "NF-e de devolución" como la imagen abajo:
Documento fiscal de devolución
Pasar los filtros de status en el parámetro "return"
Ejemplo: return=authorized, canceled
Donde:
"authorized": notas autorizadas
"canceled": notas canceladas
** En caso de no querer filtrar, debes pasar el valor "all" en ese filtro (return=all)
Documento fiscal de Full
Pasar los filtros de "full"
Exemplo: full=inbound,symbolic_inbound_return,removal
Donde:
"inbound": Notas de transferência
"symbolic_inbound_return": retornos simbólicos
"removal": notas de retirada
** En caso de no querer filtrar, debes pasar el valor "all" en ese filtro (full=all)
Otros
Pasar los filtros de "others"
Ejemplo: others=correction_letter, cte
Donde:
"correction_letter": Cartas de corrección
"cte": CT-e
** En caso de no querer filtrar, debes pasar el valor "all" en ese filtro (others=all)
Tipo de archivo
Elige los tipos de archivo que serán descargados en .zip.
Ejemplo: file_types=xml, pdf
** Puedes pasar los dos tipos o elegir uno de ellos, pero el parámetro debe estar completo.
Carpeta simple
Tenemos 2 tipos de segmentación de los archivos en las carpetas:
- simple_folder=true
- simple_folder=false
- SALE: documento fiscal de salida.
- SALE_RETURN: otras salidas - Envío simbólico a depósito temporario.
- SALE_DEVOLUTION: documento fiscal de devolución.
- INBOUND: documento fiscal de entrada - (fulfillment).
- INBOUND_DEVOLUTION: devoluciones de entrada - (fulfillment).
- INBOUND_RETURN: retornos de entrada - (fulfillment).
- INBOUND_SUPPLIER_RETURN: documento fiscal de devolución al proveedor. Cuando el proveedor nos ha enviado una nota errónea, esta nota ayuda a devolver los ítems sobrantes - (fulfillment).
- DEVOLUTION: devolución de productos - (fulfillment / otras logisticas).
- CORRECTION_LETTER: carta de corrección.
- CTE: conocimiento de transporte.
Nombre de las carpetas: "xml" e "pdf", siendo que en la carpeta "xml" vienen solo los archivos .xml y en la carpeta "pdf" solo los archivos .pdf.
Ejemplo:
Nombre de las carpetas: "Emitidas_Mercado_Livre" y "Emitidas_ERP", siendo que dentro de estas aún existen separaciones por tipo de trasacción: "Documento de venta", "Documento de devolución" y "Otros documentos", en las carpetas de tipo de transacción aún tenemos subcarpetas separadas por tipo de archivo: "XML" y "PDF", y status de los documentos.
Ejemplo:
