Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.![circulos azuis em degrade](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevImgs/230801158836-ImgMS--1-.png)
Documentação do
Obter nota fiscal
As notas fiscais possuem vários tipos que definem um tipo de operação. Os tipos de notas são:
- SALE: nota fiscal de saída.
- SALE_RETURN: nota fiscal de saída.
- SALE_DEVOLUTION: nota fiscal de devolução.
- INBOUND: nota fiscal de entrada.
- INBOUND_DEVOLUTION: devolução entrada - (fulfillment).
- INBOUND_RETURN: retorno de entrada - (fulfillment).
- INBOUND_SUPPLIER_RETURN: nota de devolução ao fornecedor. Quando o fornecedor nos enviou uma nota errada essa anota ajuda devolvendo items a mais - (fulfillment)./li>
- DEVOLUTION: devolução de Mercadorias - (fulfillment / outros tipos logísticos).
- CORRECTION_LETTER: carta de correção.
- CTE: conhecimento de transporte.
Tipos de notas fiscais utilizadas no processo de Fulfillment:
- INBOUND: nota fiscal de entrada.
- INBOUND_DEVOLUTION: devolução entrada.
- INBOUND_RETURN: retorno de entrada.
- DEVOLUTION: devolução de Mercadorias.
- SYMBOLIC_INBOUND_RETURN: retornos simbólicos.
A identificação do tipo de operação deve ser consultado diretamente no XML da nota baixada, pelo campo external_id.
A cada mudança de status, uma notificação neste feed é enviada, assim que o status da nota for AUTHORIZED, o XML pode ser acessado através do GET de invoice que pode ser feito de três maneiras, sendo elas, por invoice_id, por order_id ou por shipment_id. O XML será disponibilizado no campo xml_location com a chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/134608322/invoices/documents/xml/1377978/authorized
Por invoice_id
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://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' https://api.mercadolibre.com/users/134608322/invoices/orders/1812965285
Por shipment_id
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/134608322/invoices/shipments/27691874117
Ou ainda as notas podem ser baixadas por mês em formato de .zip assim:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/USER_ID/invoices/sites/MLB/batch_request/period/AAAAMM
Caso você vendedor opere no modelo OL Portaria e necessita implementar um fluxo de auditoria e controle mais apurados sobre a emissão de suas notas fiscais, saiba que você pode sempre que necessário, consultar toda a cadeia de notas fiscais existentes e seus respectivos status.
As notas retornadas em reference_invoices, referem-se às demais notas vinculadas como por exemplo: nota de transferência e retorno simbólico para o modelo Fullfilment Portaria. Sempre é possível consultar o status de qualquer nota fiscal, através dos campos: status e transaction_status.
Em resumo, cada NF-e de venda (vendedor -> comprador) está vinculada à uma NF-e de retorno simbólico (Armazém Mercado Livre -> Matriz Vendedor), que por sua vez, está vinculada à uma NF-e de inbound, ou remessa (Matriz Vendedor -> Armazém Mercado Livre).
E ainda as notas podem ser baixadas em formato de .zip, das seguintes formas:
Por mês
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/USER_ID/invoices/sites/MLB/batch_request/period/AAAAMM
Por período específico
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/USER_ID/invoices/sites/MLB/batch_request/period/stream?start=AAAAMMDD&end=AAAAMMDD
Ao realizar o download, estaremos segmentando os arquivos por pastas. Nome das pastas: emitidas_mercado_livre e emitidas_outro_erp, sendo que na pasta emitidas_mercado_livre vem as notas de venda, inbound, etc. e na pasta emitidas_outro_erp somente as notas importadas para as vendas em Coletas.
Exemplo:
![](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevSite/316609613597-faturamento21.jpg)
Por filtros e CT-e
Já podemos utilizar filtros e baixar CT-e se utilizarmos a API passando os parâmetros necessários:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://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=false
Para utilização dos filtros, alguns parâmetros são obrigatórios: sale, return, full, others, file_types e simple_folder. Agora explicaremos como usar cada um deles:
NF-e de venda
- Passar os filtros de status no parâmetro sale
- Passar o parâmetro caller.type com o valor seller ou não passar o parâmetro caller.type
Exemplo: sale=authorized, canceled, forbidden_disablement
Onde:
authorized: notas autorizadas
canceled: notas canceladas
forbidden_disablement: Notas negadas ou inutilizadas
** Caso não queira filtrar, passar o valor all nesse filtro (sale=all)
NF-e de compra
- Passar o parâmetro caller.type com o valor buyer
Exemplo: caller.type=buyer
Onde:
seller: Notas de venda
buyer: Notas de compra
** Se não for enviado o parâmetro caller.type serão retornadas as notas de venda (seller é o valor default)
As notas de compras são geradas e separadas por dois diretórios NF-e de compra e NF-e de devolução segundo a imagem abaixo:
![](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevSite/287062052456-nf-venda.png)
NF-e de devolução
Passar os filtros de status no parâmetro return
Exemplo: full =inbound, symbolic_inbound_return, removal
Onde:
authorized: notas autorizadas
canceled: notas canceladas
** Caso não queira filtrar, passar o valor all nesse filtro (return=all)
NF-e de Full
Passar os filtros de full
Exemplo: full=inbound, symbolic_inbound_return, removal
Onde:
inbound: Notas de transferência
symbolic_inbound_return: retornos simbólicos
removal: notas de retirada
** Caso não queira filtrar, passar o valor all nesse filtro (full=all)
Process | Description | TYPE |
---|---|---|
INBOUND | Envio de Inventário para Mercado Livre (Full). | inbound. |
INBOUND_POSITIVE_DIFFERENCE | Envio de Inventário para Mercado Livre (Full) - Ajuste Postivo. | inbound |
INBOUND_NEGATIVE_DIFFERENCE | Ajuste negativo de envio de Inventário Seller para Mercado Livre (Full) feito diretamente do fornecedor. | inbound_return |
INBOUND_RETURN | Retorno de mercadoria enviada ao Mercado Livre (Full). | inbound_return |
INBOUND_FROM_SUPPLIER | Envio de Inventário para Mercado Livre (Full) feito diretamente do fornecedor. | symbolic_inbound |
INBOUND_POSITIVE_DIFFERENCE_FROM_SUPPLIER | Ajuste positivo de envio de Inventário para Mercado Livre (Full) feito diretamente do fornecedor. | symbolic_inbound |
INBOUND_NEGATIVE_DIFFERENCE_FROM_SUPPLIER | Ajuste negativo de envio de Inventário para Mercado Livre (Full) feito diretamente do fornecedor. | inbound_return |
SALE | Venda de mercadorias. | symbolic_inbound_return |
SALE_RETURN | Retorno de mercadoria nao entregue. | sale_return |
LOST | Mercado Livre Perdeu Inventário. | symbolic_inbound_return |
REMOVED | Retirada de mercadoria enviada ao Mercado Livre (Full). | inbound_return |
WAREHOUSE_TRANSFER | Redistribuição de Inventário Entre WH Mercado Livre. | symbolic_inbound_return |
WAREHOUSE_TRANSFER_POSITIVE_DIFFERENCE | Redistribuição de Inventário Entre WH Mercado Livre - Ajuste Positivo. | symbolic_inbound_return |
WAREHOUSE_TRANSFER_NEGATIVE_DIFFERENCE | Redistribuição de Inventário Entre WH Mercado Livre - Ajuste Negativo. | symbolic_inbound_return |
WAREHOUSE_TRANSFER_OLSS_TO_OLSS | Redistribuição de Inventário Entre WH Mercado Livre. | symbolic_inbound_return |
WAREHOUSE_TRANSFER_POSITIVE_DIFFERENCE_OLSS_TO_OLSS | Redistribuição de Inventário Entre WH Mercado Livre - Ajuste Positivo. | symbolic_inbound_return |
WAREHOUSE_TRANSFER_NEGATIVE_DIFFERENCE_OLSS_TO_OLSS | Redistribuição de Inventário Entre WH Mercado Livre - Ajuste Negativo. | symbolic_inbound_return |
QUARANTINE_REMOVED | Retorno de mercadoria que chegou ao Mercado Liivre (Full) sem condições de armazenamento ou análogo, foi recebido mas não foi armazenado.. | inbound_return |
ADJUSTMENT | Ajuste positivo efetuado em contagens de inventário. | symbolic_inbound |
DEVOLUTION | Item foi entregue mas comprador resolveu devolver. | devolution |
DISPOSAL | Retorno de produto que foi avariado depois de recebido e armazenado mas nao pode mais ser vendido. | inbound_return |
Outros
Passar os filtros de others
Exemplo: others=correction_letter, cte
Onde:
correction_letter: Cartas de correção
cte: CT-e
** Caso não queira filtrar, passar o valor all nesse filtro (others=all)
Tipo de Arquivo
Escolher os tipos de arquivo que serão baixados no .zip.
Exemplo: file_types=xml, pdf
** Pode passar os dois tipos, ou escolher um deles, mas esse parâmetro deve estar preenchido.
Pasta Simples
Temos 2 tipos de segmentação dos arquivos nas pastas:
- simple_folder=true
Nome das pastas: sxml e spdf, sendo que na pasta sxml vem somente os arquivos .xml e na pasta spdf somente os arquivos .pdf.
Exemplo:
![](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevSite/316609607278-faturamentoxml.jpg)
Nome das pastas: Emitidas_Mercado_Livre e Emitidas_ERP, sendo que dentro destas ainda existem separações por tipo de transação: NF-e de venda, NF-e de devolução e Outros documentos, nas pastas de tipo de transação ainda temos subpastas separando por tipo de arquivo: XML e PDF, e status das notas.
Exemplo:
![](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevSite/316610234796-faturamento20.jpg)
Caso ainda tenha dúvidas sobre tema pedimos a gentileza de entrar em contato através do nosso canal de suporte.
Próxima: Mensagens de adicionais.