Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 31/07/2024

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.

Nota:
O campo com o identificador do processo estará presente em todas as notas fiscais emitidas após a data 01/09/2023.

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:

Nota:
Estes recursos para baixar as NFs, não são somente para Fulfillment, mas sim para todos os tipos de envio em que se use nosso emissor de NFs, como por exemplo Cross Docking (Coletas).

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:





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:



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:



  • simple_folder=false
  • 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:





    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.