Conteúdos

→Obter nota fiscal
    ↳Por invoice id
    ↳Order id
    ↳Shipment id
    ↳Mês
    ↳Período específico
    ↳Filtros e CT-e
→NF-e de venda
→NF-e de compra
→NF-e de devolução
→NF-e de full
→Outros
→Tipo de Arquivo
→Pasta Simples


Obter nota fiscal

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' 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/1812965285

Por shipment_id

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://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' http://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' http://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' http://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' 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=false

Para utilização dos filtros, alguns parâmetros são obrigatórios: "sale", "return", "full", "others", "fileType" e "simpleFolder". 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: return=authorized, canceled

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)

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: "xml" e "pdf", sendo que na pasta "xml" vem somente os arquivos .xml e na pasta "pdf" 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.

ou registre-se para receber as últimas notícias sobre nossa API