Upload invoices

Important:
This resource is available in all sites, except Mercado Livre Brasil.
Remember that if you programmed automatic messages notifying the invoice upload, you must cancel your shipment to avoid moderation, since Mercado Libre sends a notification and an email.
To Mercado Libre Chile, the pack with Full shipping will not use this resource.

With this new feature, Mercado Libre sellers can share their buyers invoices in an orderly way within the purchase-sale process. This way, we facilitate access to the documents avoiding these to be attached in the messaging after sales and improving the purchasing experience. Follow our guide, you will learn to upload, obtain and delete invoices per pack.

Contents

→Upload invoices
→Attach XML file
    ↳Possible errors in uploading an invoice
→Obtain invoices ids
    ↳Errors obtaining the invoices ids
→Obtain invoices
    ↳Errors obtaining the invoices
→Delete invoices
    ↳Possible errors deleting an invoice
→Request billing information
    ↳Possible errors requesting billing data
→General errors


Upload invoices

In order to upload an invoice you must make a POST as form.data with key: type file and fiscal_document value that references the fiscal_document (document file you attach), pack_id (pack ID) and access_token (public token).
To know the pack_id, you must obtain the “pack_id” field in the response of /orders / <order_id>.
If the pack id contains a null value, must take the order id by default, keeping the resource /packs in the API request.

Important:
The file must have a maximum size of 1 MB, be in PDF format and can only be one fiscal_document per pack. Also, in case you need to attach an associated XML and PDF file, you can load the two fiscal_documents as we show you in Attach XML.

Request:

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.pdf'

Example:

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.pdf'

Response:

{
  "ids" : ["415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d"]
}
Note:
The response will return the uploaded fiscal_document ID, that you must save in order to retrieve it.
If you attach a wrong file, you can delete the existing fiscal_document and then upload the correct fiscal_document.

Attach XML file

Currently, you can choose to attach the invoice in associated XML, making the following POST and specifying one of the following formats:

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

Request:

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.pdf'
  -F 'fiscal_document=@/home/user/.../Factura_adjunta.xml'

Example:

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.pdf'
  -F 'fiscal_document=@/home/user/.../Factura_adjunta.xml'

Response:

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

Possible errors in uploading an invoice

The user is not authorized to upload an invoice:

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

The file can not be null or file not found:

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

File type not supported:

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

   ]
}

File exceeds maximum size:

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

More than one file attached:

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

Attach more than one file in a pack of the same type:

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

Attach a file in a pack that already has the maximum number of files previously loaded:

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

Attach a file of a type in a pack that already has a file of that type previously loaded:

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

   ]
}

File attached with empty name:

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

Obtain invoices IDs

In order to obtain the invoice id, you must make a GET request. The response will depend on the role of the user making the query and may be:
Rol vendedor: the id of the invoices you loaded in the pack.
Buyer role: all the ids of the invoices that belong to the pack.

Request:

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

Example:

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

Response:

{
    "pack_id": 2000000089077943,
    "fiscal_documents":[
      {
         "id":"fc76f79d-1599-43ed-8675-569482e2ec21",
         "date":"2020-04-27T23:10:21Z",
         "file_type":"application/pdf"
         "filename":"factura.pdf"
      }
   ]
}
Note:
The response will return the IDS of the loaded fiscal_document, which you must save in order to download, the date it was loaded and the type of file (PDF or XML).
If there are fiscal_documents that were removed, the fiscal_documents ids list may appear empty.

Errors obtaining the invoices ids

The user is not authorized to obtain the invoices ids associated with the pack:

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

If the pack does not have any invoices charged:

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

If the user does not have any invoices loaded by him within the pack:

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

Obtain invoices

To obtain invoices, you must make a GET request with the filename, i.e., the ID´s file. The response will be successful when it returns the file requested.

Request:

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

Example:

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

Errors obtaining the invoices

The user is not authorized to delete the invoices linked to the pack:

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

The fiscal_document requested does not exist:

{
    "message": "The fiscal_document with id: ${ID} does not exist",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

The invoices could not be found in the server, try again in some seconds:

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

Delete invoices

To delete an invoice you must make a DELETE call specifying the pack_id i.e., the pack ID. This way, you will delete the invoices belonging to this pack.

Request:

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

Example:

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

If the seller has only 1 file attached to the PACK_ID, this is the response:

{
  "message" : "The fiscal_document with "id" : 415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d was deleted"
}

If you have more than one file attached (PDF and XML), the response is:

{
  "message" : "The fiscal_documents with the following ids: 415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d,              415460047_4c942945-ae16-46f2-98fa-a772322c7e70 were deleted
}
Note:
In the response you will obtain the deleted fiscal_document ID.

Possible errors deleting an invoice

Deleting a non-existing or already deleted invoices from a pack:

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

User is not authorized to delete the invoices linked to the pack:

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

Request billing information

Important:
This resource will be available from May 15, 2020.

The resource packs /packs/$PACK_ID/fiscal_documents/billing/request_buyer_info is intended so that you can only request the buyer's billing information. By means of a POST request you can place, within the text field, the message with a maximum of up to 500 characters and you must respect the rules and limitations of post sales messaging, such as avoiding using social network links, offensive language, shortened links and html in the body of the message to avoid future moderations.

Request:

curl -X POST -d '{
  "text": "Text to buyer"

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

Example:

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

Por favor responder 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_info?access_token=$ACCESS_TOKEN'

Response with 201 Code Status:

{
   "message":"The message with id: $MESSAGE_ID was created"
}

You will receive the request response by courier when the buyer responds.


Possible errors requesting billing data

The body is empty:

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

Could not retrieve body of request:

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

The user is not authorized to request tax data:

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

If the user can not use the messaging:

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

If the text exceeds the maximum number of characters:

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

If the text is empty:

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

If the text is not valid:

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

General errors

The order id do not be part of a pack:

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

Pack_id empty or non-numeric:

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

Negative pack_id or 0:

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

Access token error

If you make the query without the corresponding ACCESS_TOKEN, you will get the following error:

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

Error for access from unauthorized site

In case you want to use the API from a site where it is not available, you will get the following error:

{
    "message": "Access Denied, this API is not available on your site: MLB",
    "error": "forbidden",
    "status": 403,
    "cause": []
}