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' 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:

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, 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)

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.

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.