Anexar Nota Fiscal

Visão Geral

Disponibilizamos duas formas de anexar Notas Fiscais para um pacote ou pedido, permitindo flexibilidade conforme sua necessidade de integração:

Restrições por país e tipo logístico

• Mercado Livre Chile (MLC): não é permitido o upload de faturas para envios com logística fulfillment.
• Mercado Livre Brasil (MLB): não é permitido o upload de faturas para envios com logística fulfillment, cross_docking, xd_drop_off ou drop_off.

Pré-requisitos

Para utilizar este recurso, você precisará de:

• pack_id: ID do pacote. Obtido através do campo pack_id na resposta de /orders. Se o valor for null, utilize o order_id como identificador, mantendo o recurso /packs na chamada.
• access_token: Token de autenticação válido.

Considerações

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

Enviar Nota Fiscal

Para carregar uma Nota Fiscal, realize uma chamada POST ao endpoint /packs/{pack_id}/fiscal_documents enviando os arquivos como multipart/form-data.

Disponibilizamos duas formas de envio para atender diferentes necessidades de integração:

Enviar apenas XML (DANFE gerado automaticamente)

Utilize esta opção quando quiser que o Mercado Livre gere automaticamente o PDF (DANFE) a partir do seu XML. Ideal para integrações simples.

Critérios do arquivo

• Formato: XML
• Tamanho máximo: 1 MB
• Limite: 1 arquivo por pacote
• O XML deve começar com o cabeçalho <?xml version="1.0" encoding="UTF-8"?> antes do nó <nfeProc>.

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'fiscal_document=@/home/user/.../nota_fiscal.xml' \
  https://api.mercadolibre.com/packs/$PACK_ID/fiscal_documents

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'fiscal_document=@/home/user/.../nota_fiscal.xml' \
  https://api.mercadolibre.com/packs/2000000089077943/fiscal_documents

Resposta:

{
  "ids": ["415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d"]
}

A resposta retorna o ID do documento fiscal carregado. Salve este ID para consultas ou remoções futuras. Caso anexe um arquivo incorreto, você pode removê-lo e carregá-lo novamente.

Enviar PDF + XML (DANFE personalizado)

Utilize esta opção quando você já possui um PDF (DANFE) personalizado e deseja enviá-lo junto com o XML de validação. Ambos os arquivos serão armazenados pelo Mercado Livre.

Formatos aceitos

• application/pdf
• application/xml
• text/xml

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'fiscal_document=@/home/user/.../nota_fiscal.pdf' \
  -F 'fiscal_document=@/home/user/.../nota_fiscal.xml' \
  https://api.mercadolibre.com/packs/$PACK_ID/fiscal_documents

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'fiscal_document=@/home/user/.../nota_fiscal.pdf' \
  -F 'fiscal_document=@/home/user/.../nota_fiscal.xml' \
  https://api.mercadolibre.com/packs/2000000089077943/fiscal_documents

Resposta:

{
  "ids": [
    "415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d",
    "415460047_4c942945-ae16-46f2-98fa-a772322c7e70"
  ]
}

A resposta retorna dois IDs: um para o PDF e outro para o XML. Salve estes IDs para consultas ou remoções futuras.

Consultar Notas Fiscais

Listar IDs das NFs de um pacote

Para obter os IDs das notas fiscais associadas a um pacote, realize uma chamada GET. A resposta varia conforme o papel do usuário:

• Vendedor: retorna os IDs das notas fiscais que ele carregou no pacote.
• Comprador: retorna todos os IDs das notas fiscais do pacote.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
  https://api.mercadolibre.com/packs/$PACK_ID/fiscal_documents

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
  https://api.mercadolibre.com/packs/2000000089077943/fiscal_documents

Resposta:

{
  "pack_id": 2000000089077943,
  "fiscal_documents": [
    {
      "id": "fc76f79d-1599-43ed-8675-569482e2ec21",
      "date": "2020-04-27T23:10:21Z",
      "file_type": "application/xml",
      "filename": "factura.xml"
    },
    {
      "id": "fc76f79d-1599-43ed-8675-569482e2ec21",
      "date": "2020-04-27T23:10:21Z",
      "file_type": "application/pdf",
      "filename": "factura.pdf"
    }
  ]
}

A resposta inclui o ID, data de carregamento, tipo de arquivo e nome do arquivo. Se as notas fiscais foram removidas, a lista pode retornar vazia.

Baixar arquivo específico

Para baixar um arquivo específico da nota fiscal, utilize o ID obtido na listagem:

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
  https://api.mercadolibre.com/packs/$PACK_ID/fiscal_documents/$FISCAL_DOCUMENT_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
  https://api.mercadolibre.com/packs/2000000089077943/fiscal_documents/415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d

Remover Nota Fiscal

Para remover todas as notas fiscais de um pacote, realize uma chamada DELETE especificando o pack_id. Esta operação remove todos os arquivos que você carregou no pacote.

Chamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' \
  https://api.mercadolibre.com/packs/$PACK_ID/fiscal_documents

Exemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' \
  https://api.mercadolibre.com/packs/2000000089077943/fiscal_documents

Resposta:

{
  "message": "The fiscal_documents with the following ids: 415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d, 415460047_4c942945-ae16-46f2-98fa-a772322c7e70 were deleted"
}

Erros

Erros ao enviar Nota Fiscal

Usuário não autorizado:

{
  "message": "Access Denied, you are not authorized.",
  "error": "forbidden",
  "status": 403,
  "cause": []
}

Arquivo vazio ou não encontrado:

{
  "message": "File cannot be empty",
  "error": "bad_request",
  "status": 400,
  "cause": []
}

Tipo de arquivo não permitido:

{
  "message": "File type: $FILE_TYPE is not allowed",
  "error": "bad_request",
  "status": 400,
  "cause": []
}

Arquivo excede o tamanho máximo (1 MB):

{
  "message": "File Not allowed, exceeds maximum size",
  "error": "bad_request",
  "status": 400,
  "cause": []
}

Tentativa de enviar mais de dois arquivos:

{
  "message": "Files Not allowed, you can upload only two files, one of each type",
  "error": "bad_request",
  "status": 400,
  "cause": []
}

Tentativa de enviar arquivos duplicados do mesmo tipo:

{
  "message": "Files Not allowed, you can upload only one file of type: $FILE_TYPE",
  "error": "conflict",
  "status": 409,
  "cause": []
}

Pacote já possui quantidade máxima de arquivos:

{
  "message": "File Not allowed, the max amount of files already exist for the pack: $PACK_ID and seller: $SELLER_ID",
  "error": "conflict",
  "status": 409,
  "cause": []
}

Arquivo do mesmo tipo já existe no pacote:

{
  "message": "File Not allowed, a file already exists for the pack: $PACK_ID and seller: $SELLER_ID of the type: $FILE_TYPE",
  "error": "conflict",
  "status": 409,
  "cause": []
}

Nome do arquivo vazio:

{
  "message": "Filename cannot be empty",
  "error": "bad_request",
  "status": 400,
  "cause": []
}

Usuário utiliza faturador do Mercado Livre (optin):

{
  "message": "Access denied, you must use the NF-e reporting flow",
  "error": "forbidden",
  "status": 403,
  "cause": []
}

XML com formato inválido:

{
  "message": "Input XML is not valid",
  "error": "bad_request",
  "status": 400,
  "cause": []
}

Tipo logístico não permitido (fulfillment, cross_docking, xd_drop_off):

{
  "message": "Access denied, you must use the biller of MercadoLibre",
  "error": "forbidden",
  "status": 403,
  "cause": []
}

Erros ao consultar Nota Fiscal

Usuário não autorizado:

{
  "message": "Access Denied, you are not authorized.",
  "error": "forbidden",
  "status": 403,
  "cause": []
}

Pacote sem nota fiscal:

{
  "message": "The pack_fiscal_document with pack_id: %d does not exist",
  "error": "not_found",
  "status": 404,
  "cause": []
}

Usuário sem notas fiscais carregadas no pacote:

{
  "message": "The pack_fiscal_document with pack_id: %d does not have any fiscal_document attached for the user_id: %d",
  "error": "not_found",
  "status": 404,
  "cause": []
}

Usuário não autorizado para obter arquivo específico:

{
  "message": "Access Denied for user with id: ${ID} to the fiscal_document with id: ${ID}.",
  "error": "forbidden",
  "status": 403,
  "cause": []
}

Arquivo não encontrado no servidor:

{
  "message": "The fiscal_document with id: ${ID} could not be retrieved from storage",
  "error": "not_found",
  "status": 404,
  "cause": []
}

ID do documento vazio:

{
  "message": "Filename cannot be empty",
  "error": "bad_request",
  "status": 400,
  "cause": []
}

Erros ao remover Nota Fiscal

Pacote sem nota fiscal ou já removida:

{
  "message": "Cannot delete. The pack: 2000000089077943 doesn't have a fiscal_document attached",
  "error": "not_found",
  "status": 404,
  "cause": []
}

Usuário não autorizado:

{
  "message": "Access Denied, you are not authorized.",
  "error": "forbidden",
  "status": 403,
  "cause": []
}

Erros gerais

Pack_id inválido (vazio, não numérico, negativo ou zero):

{
  "message": "pack.id must be numeric and not empty",
  "error": "bad_request",
  "status": 400,
  "cause": []
}

{
  "message": "pack.id is invalid",
  "error": "bad_request",
  "status": 400,
  "cause": []
}

Order pertence a um pack:

{
  "message": "The order belong to a pack/purchase",
  "error": "bad_request",
  "status": 400,
  "cause": []
}

Access token ausente:

{
  "message": "access_token was not sent",
  "error": "access_token_not_granted",
  "status": 403,
  "cause": []
}