Recursos Cross

Confira os principais recursos das nossas APIs
circulos azuis em degrade

Documentação

Você pode usar esta documentação para as seguintes unidades de negócio:

Última atualização em 01/11/2023

Carregar Nota Fiscal

Importante:
Este recurso substitui as mensagens automáticas de pós venda e deve ser usado apenas para envio de notas fiscais nos pedidos.
Lembre que se você programou mensagens automáticas notificando o carregamento da Nota Fiscal, deverá cancelar seu envio para evitar moderações, já que o Mercado Livre se encarrega de enviar uma notificação e um e-mail ao comprador.

Com essa funcionalidade, os vendedores do Mercado Livre podem compartilhar as Notas Fiscais com seus compradores de forma ordenada dentro do processo de compra e venda. Assim, facilitamos o acesso aos documentos evitando que sejam anexados no sistema de mensagens pós-venda e melhorando a experiência de compra. Siga nosso guia, aprenderá a carregar, obter e remover Notas Fiscais por pacote.

Nota:
Os vendedores do Brasil podem criar cupons de desconto para vendas diretas e/ou de carrinho dentro do canal de Marketplace, saiba como faturar essas vendas.

Carregar NF no detalhe de venda

Para poder realizar o carregamento de uma nota fiscal, você deve realizar um POST como form.data com key: tipo file e value fiscal_document que faz referência ao fiscal_document (arquivo do documento que você anexa), pack_id (ID do pacote) e access_token (token público).
Para conhecer o pack_id, você deverá obter o campo “pack_id” na resposta de /orders/.
No caso que o id do pacote tenha um valor null, você deverá tomar por padrão o order id, mantendo o recurso /packs na chamada a API..

Importante:
- O arquivo deve ter um tamanho máximo 1 MB, estar no formato XML e poderá ser somente um fiscal_document por pacote. A partir do XML associado, Mercado Livre geram o PDF (DANFE) correspondente.
- Recordamos que o padrão para o formato do XML começa com o cabeçalho < ?xml version="1.0" encoding="UTF-8"? > antes do nó < nfeProc >.

Chamada:

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

Exemplo:

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

Resposta:

{
  "ids" : ["415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d"]
}
Nota:
A resposta devolverá o ID do fiscal_document carregado, que você deverá salvar para poder recuperá-lo.
Se você anexar um arquivo errado, pode remover o fiscal_document existente e depois carregá-lo novamente de forma correta.

Anexar arquivo XML

Para anexar uma fatura com XML associado, é só realizar POST e especificar algum dos seguintes formatos:

  • application/pdf
  • application/xml
  • text/xml
  • Chamada:

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

    Exemplo:

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

    Resposta:

    {
      "ids" : ["415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d",
                   "415460047_4c942945-ae16-46f2-98fa-a772322c7e70" ]
    }
    Nota:
    Recomendamos que revise os detalhes de todos os descontos aplicados em uma venda. É possível obter estes detalhes com o recurso /discount.

    Possíveis erros no carregamento da nota fiscal

    O usuário não é autorizado para carregar uma nota fiscal:

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

    O arquivo não pode ser null ou não está sendo achado:

    {
        "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 supera o tamanho máximo:

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

    Anexar mais de um arquivo:

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

    Anexar mais de um arquivo num pacote do mesmo tipo:

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

    Anexar um arquivo num pacote que já tem a quantidade máxima de arquivos carregados previamente:

    {
       "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": []
    }

    Anexar um arquivo de um determinado tipo num pacote que já contém um arquivo desse tipo carregado previamente:

    {
       "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": []
    }

    Anexar arquivo com nome vazio:

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

    Anexar arquivo para pacote com envio fulfillment ou cross-docking:

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

    O usuário fiz optin ao faturamento:

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

    Anexar uma NF com formato inválido:

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

    Obter IDs das NF

    Para poder obter o id das notas fiscais, você tem que fazer uma chamada GET. A resposta vai depender do papel do usuário que fizer a consulta, podendo ser:
    Papel vendedor: os ids das notas fiscais que carregou no pacote.
    Papel comprador: todos os ids das notas fiscais que pertencem ao pack.

    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"
          }
       ]
    }
    Nota:
    A resposta devolverá o(s) IDS dos fiscal_document carregados, que você deverá salvar para poder fazer o descarregamento, a data em que foi carregado e o tipo de arquivo que for (PDF ou XML).
    Se existem fiscal_document que foram removidos, a lista de ids de fiscal_documents pode aparecer vazia.

    Erros obtendo os ids da nota fiscal

    O usuário não possui autorização para obter os ids de notas fiscais associadas ao pacote:

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

    Se o pacote não tem nenhuma nota fiscal carregada:

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

    Se o usuário não tem nenhuma nota fiscal por ele carregada dentro do 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": []
    }

    Obter NF

    Para poder obter notas fiscais, você deve realizar uma chamada GET com o filename, ou seja, o ID do file. A resposta será bem-sucedida quando restitui o arquivo que você pede.

    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

    Possíveis erros para obter notas fiscais

    O usuário não possui autorização para obter a nota fiscal associada ao pacote:

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

    A nota fiscal não pôde ser achada no server, tente novamente dentro de alguns segundos:

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

    Fiscal_document_id (filename) vazio:

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

    Remover NF

    Para remover a nota fiscal, você deve realizar uma chamada DELETE, especificando o pack_id, isto é, o ID do pacote. Assim, você removerá todos os arquivos que tenha carregado 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

    RResposta:

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

    Possíveis erros por remover NF

    Remover uma nota fiscal de um pacote que não existe ou que já foi 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 para remover a nota fiscal associada ao pacote:

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

    Possíveis erros por requerer dados de faturamento

    O body está vazio:

    {
        "message": "The body of the request cannot be empty",
        "error": "internal_server_error",
        "status": 500,
        "cause": []
    }

    O body do request não pôde ser recuperado:

    {
        "message": "Error retrieving the body from the request",
        "error": "internal_server_error",
        "status": 500,
        "cause": []
    }

    O usuário não possui autorização para requerer os dados fiscais:

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

    Se o usuário não pode utilizar o sistema de mensagens:

    {
        "message": "You cannot ask for the billing_info because you are not allowed to use the messaging service",
        "error": "forbidden",
        "status": 403,
        "cause": []
    }

    Se o texto supera a quantidade máxima de carácteres:

    {
        "message": "The text content is too long, max characters allowed are: 500",
        "error": "bad_request",
        "status": 400,
        "cause": []
    }

    Se o texto está vazio:

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

    Se o texto não é válido:

    {
        "message": "You cannot ask for the billing_info because the text is not valid. Check Messaging Post Sale documentation for more information",
        "error": "not_acceptable",
        "status": 406,
        "cause": []
    }

    Erros gerais

    O id do pedido não pertence a um pacote:

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

    Pack_id vazio ou não numérico:

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

    Pack_id negativo ou 0:

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

    Erro por Access token

    No caso que realize a consulta sem o access token correspondente, você obterá o seguinte erro:

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