Carregar NF no detalhe da venda

Importante:
Este recurso substitui as mensagens automáticas pós venda e não está disponível para as logísticas cross-docking e fulfillment, nas quais o faturamento é obrigatório.
Lembre que se você programou mensagens automáticas notificando o carregamento da NF, deverá cancelar seu envio para evitar moderações, já que Mercado Livre envia uma notificação e um e-mail.

Com essa nova funcionalidade, os vendedores de Mercado Livre podem compartilhar as notas fiscais de 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.

Conteúdos

→Carregar NF no detalhe de venda
    ↳Possíveis erros no carregamento da nota fiscal
→Obter IDs das NF
    ↳Erros obtendo os ids da nota fiscal
→Obter NF
    ↳Possíveis erros para obter notas fiscais
→Remover NF
    ↳Possíveis erros por remover NF
→Solicitar dados de faturamento
    ↳Possíveis erros por requerer dados de faturamento
→Erros gerais


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 defeito 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.

Chamada:

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

Exemplo:

curl -X POST https://api.mercadolibre.com/packs/2000000089077943/fiscal_documents?access_token=$ACCESS_TOKEN
  -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.

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 https://api.mercadolibre.com/packs/$PACK_ID/fiscal_documents?access_token=$ACCES_TOKEN

Exemplo:

curl -X GET https://api.mercadolibre.com/packs/2000000089077943/fiscal_documents?access_token=$ACCESS_TOKEN

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 https://api.mercadolibre.com/packs/$PACK_ID/fiscal_documents/$FISCAL_DOCUMENT_ID?access_token=$ACCESS_TOKEN

Exemplo:

curl -X GET https://api.mercadolibre.com/packs/2000000089077943/fiscal_documents/415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d?access_token=$ACCESS_TOKEN

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 https://api.mercadolibre.com/packs/$PACK_ID/fiscal_documents?access_token=$ACCESS_TOKEN

Exemplo:

curl -X DELETE https://api.mercadolibre.com/packs/2000000089077943/fiscal_documents?access_token=$ACCESS_TOKEN

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

Solicitar dados de faturamento

O recurso /packs/$PACK_ID/fiscal_documents/billing/request_buyer_info objetiva que você possa solicitar somente os dados de faturamento ao comprador. Mediante uma chamada POST, você pode colocar, dentro do campo text, a mensagem com um máximo de até 500 carácteres e deverá respeitar as regras e limitações de sistema de mensagens pós-venda, como evitar utilizar links de redes sociais, linguagem ofensiva, links encurtados e html no corpo da mensagem para evitar futuras moderações.

Chamada:

curl -X POST -d '{
  "text": "Texto para el comprador"

}' 'https://api.mercadolibre.com/packs/$PACK_ID/fiscal_documents/billing/request_buyer_info?access_token=$ACCESS_TOKEN'

Exemplo:

curl -X POST -d '{
  "text":  "¡Hola Comprador!

Por favor, responda el siguiente mensaje con los datos de facturación:
- Nombre completo:
- Número de identificación (DNI, RFC, etc.):
- Dirección completa:

¡Muchas gracias por tu compra!"

}' 'https://api.mercadolibre.com/packs/2000000089077943/fiscal_documents/billing/request_buyer_info?access_token=$ACCESS_TOKEN'

Resposta com Status Code 201:

{
   "message":"The message with id: $MESSAGE_ID was created"
}
Nota:
O recurso enviará os dados pelas mensagens pós-venda. Portanto, quando o comprador responder, o vendedor receberá as informações de cobrança pelos mesmos meios.

Você receberá a resposta do pedido pelo sistema de mensagens quando o comprador responda.


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