Importar Nota Fiscal

Assinatura de notificações

Lembre-se: o desenvolvimento deve estar configurado para receber notificações de "shipments" (envios) através do painel MyApps. Recomendamos a leitura da nossa documentação oficial para entender o fluxo de trabalho com notificações. O recebimento dos alertas será iniciado assim que uma venda for gerada na plataforma e o pagamento devidamente confirmado.

Exemplo de notificação:

{
    "resource": "/shipments/139876",
    "user_id": 1234,
    "topic": "shipments",
    "received": "2011-10-19T16:38:34.425Z",
    "sent" : "2011-10-19T16:40:34.425Z",
}

Status do envio do pedido

Obtenha os detalhes do envio através do shipment_id. Confirmando que o envio tenha status "ready_to_ship" e substatus "invoice_pending", você deverá enviar o XML da nota. Este substatus aplica-se às logísticas drop_off, xd_drop_off, cross_docking e xd_same_day.

Chamada:

curl -H "x-format-new:true" -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID

O substatus invoice_pending ocorre quando a Nota Fiscal Eletrônica (NFe) ainda não foi importada, a Declaração de Conteúdo Eletrônica (DC-e) ainda não foi emitida, ou o Conhecimento de Transporte (CT-e) ainda não foi emitido. Após a importação da nota (ou emissão da DC-e) e emissão do CT-e (gerado pelo Mercado Livre), o status passa a ser "ready_to_ship" e substatus "ready_to_print".

Exemplo:

{
    "date": "2025-07-07T09:45:46.000-04:00",
    "substatus": "invoice_pending",
    "status": "ready_to_ship"
},

Informação fiscal da logística de envio do pedido

A partir do endpoint /shipments, é possível derivar recursos essenciais para a gestão logística de um pedido. O recurso /shipments/billing_info, especificamente, é utilizado para consultar as informações fiscais dos diferentes atores que operam no fluxo de envio, garantindo conformidade e transparência nos detalhes do faturamento.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/billing_info

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/26474580996/billing_info
{
	"receiver": {
		"id": 154808171,
		"document": {
			"id": "CPF",
			"value": "02972404475"
		},
		"additional_documents": []
	},
	"senders": [{
		"id": 168777350,
		"document": {
			"id": "CNPJ",
			"value": "21611372000396"
		},
		"additional_documents": [{
			"id": "IE",
			"value": "421038162111"
		}]
	}],
	"carrier": {
		"document": {
			"id": "CNPJ",
			"value": "20121850000317"
		},
		"additional_documents": []
	}
}

Considerações

• Dentro de cada "additional_documents" pode vir uma lista de outros documentos que podem ser requeridos.
• Em cumprimento a Nota Técnica NT2020.006, o CNPJ que deve ser utilizado como sendo o do intermediador da transação (Mercado Livre) pode ser obtido através do Mercado Livre, no rodapé da página.

Enviar nota fiscal eletrônica

Somente é possível enviar NFe com modelo 55. Ou seja, no momento do upload do arquivo, será analisado o modelo e não poderá ser feito o envio de uma NFC-e, por exemplo.

Com todas informações disponíveis, assim que o status e substatus estiverem confirmados, você deverá enviar o XML da nota:

Chamada:

curl -s -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/xml' -d '<?xml version="1.0" encoding="UTF-8"?>
<nfeProc versao="4.00" xmlns="http://www.portalfiscal.inf.br/nfe">
...
</nfeProc>' "https://api.mercadolibre.com/shipments/{id}/invoice_data/?siteId=$SITE_ID"

Importante:

• Estamos realizando a validação dos XMLs enviados, sendo assim não serão aceitas Notas Fiscais geradas pelo ambiente de homologação da SEFAZ, somente Notas Fiscais válidas.
• Uma vez impressa a etiqueta, não será possível alterar a nota.

total_paid_amount + coupon_amount - transaction_amount - taxes_amount - shipping_cost = acréscimos

Consultar a Nota Fiscal Enviada

Você pode consultar os detalhes da Nota Fiscal Enviada utilizando o recurso:

Chamada:

curl -H GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/invoice_data?siteId=MLB

Exemplo:

curl -H GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/53932058390/invoice_data?siteId=MLB

Exemplo de resposta:

{
    "id": 429348053945853,
    "sender_id": 4258493958,
    "shipment_id": 53932058390,
    "fiscal_key": "35250718128675438943295483011669689451",
    "weight": 81.0,
    "item_title": "Produto Teste",
    "invoice_serie": "2",
    "invoice_number": "00001",
    "invoice_amount": 100.00,
    "status": "approved",
    "invoice_date": "2025-07-07T14:04:21.000-03:00",
    "date_created": "2025-07-07T13:10:12.334-04:00",
    "last_updated": "2025-07-07T13:10:12.334-04:00"
}

Atualizar nota fiscal eletrônica

Caso haja necessidade de atualizar alguma informação dos dados fiscais já enviados, você pode utilizar o recurso para enviar a nota fiscal atualizada:

Chamada:

curl -s -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/xml' -d '<?xml version="1.0" encoding="UTF-8"?>
<nfeProc versao="4.00" xmlns="http://www.portalfiscal.inf.br/nfe">
...
</nfeProc>' "https://api.mercadolibre.com/shipment_invoice/{invoice_id}/?siteId=$SITE_ID"

Referências de código de erro