Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.Documentación
Reportes de facturación
Con esta funcionalidad puedes conocer los reportes de la facturación realizada por Mercado Libre Pago para los vendedores. Consultando /billing/monthly/periods puedes obtener información de los últimos 12 períodos. Luego con /documents conseguirás todas las facturas (documentos) de un periodo, y finalmente, con /summary y /details podés acceder al resumen de facturación de un periodo y a sus detalles respectivamente.
Facturación de Mercado Libre y Mercado Pago
Cada uno de los endpoints permite obtener información de facturación tanto de Mercado Libre, como de Mercado Pago. A través del parámetro de query obligatorio group podemos especificar de qué grupo de facturación queremos obtener la información.
Obtener período
Permite obtener información de los períodos de facturación para el grupo de facturación indicado (Mercado Libre o Mercado Pago). Por defecto se devuelven los últimos 6 periodos, con la posibilidad de consultar períodos más antiguos utilizando la paginación de offset y limit.
Llamada para el site MLM:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods
Llamada para los sites MLA, MLB MCO, MLC, MLU, MPE, MLV y MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/monthly/periods
Ejemplo para los sites MLA, MLB MCO, MLC, MLU, MPE, MLV y MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/monthly/periods?group=MP&document_type=BILL&offset=1&limit=2
Respuesta:
{
"offset": 1,
"limit": 2,
"total": 27,
"results": [{
"amount": 30.46000027656555,
"unpaid_amount": 0.0,
"period": {
"date_from": "2020-02-19",
"date_to": "2020-03-18"
},
"key": "2020-03-01"
"expiration_date": "2020-03-24",
"debt_expiration_date": "2020-03-24",
"debt_expiration_date_move_reason": null,
"debt_expiration_date_move_reason_description": null,
"period_status": "CLOSED"
},
{
"amount": 477888.1484375,
"unpaid_amount": 0.0,
"period": {
"date_from": "2020-01-19",
"date_to": "2020-02-18"
},
"expiration_date": "2020-02-24",
"debt_expiration_date": "2020-03-23",
"debt_expiration_date_move_reason": "PAYMENT_ANNULMENT",
"debt_expiration_date_move_reason_description": "Anulación de pago",
"period_status": "CLOSED"
}
]
}
Campos de la respuesta
- amount: monto total del período.
- unpaid_amount: monto total pendiente de pago.
- period: rango de fechas del período.
- date_from: fecha de inicio del período.
- date_to: fecha de fin del período.
Obtener documentos de un período
Permite obtener información de los documentos (Facturas y Notas de crédito) para un período de facturación en particular para el grupo de facturación indicado (Mercado Libre o Mercado Pago).
Llamada para el site MLM:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/documents
Llamada para los sites MLA, MLB, MCO, MLC, MLU, MPE, MLV y MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/documents
Ejemplo para los sites MLA, MLB, MCO, MLC, MLU, MPE, MLV y MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06-01/documents?group=MP&document_type=BILL&limit=1
Respuesta:
{
"offset": 0,
"limit": 1,
"total": 2,
"results": [{
"id": 987654321,
"user_id": 1234,
"document_type": "BILL",
"expiration_date": "2021-06-02",
"associated_document_id": null,
"amount": 3.86,
"unpaid_amount": 0.0,
"document_status": "BILLED",
"site_id": "MLM",
"period": {
"date_from": "2021-05-03",
"date_to": "2021-05-03"
},
"currency_id": "MXN",
"count_details": 1,
"files": [
{
"file_id": "1234_FE_MEPF00869625_pdf",
"reference_number": "MEPF00999999"
},
{
"file_id": "1234_FE_MEPF00869625_xml",
"reference_number": "MEPF00999999"
}
]
}]
}
Filtros opcionales
- document_id: permite buscar por el id de la factura. Ej: document_id=987046992.
- document_type: permite buscar por tipo de documento: Factura o Nota de Crédito. Valores posibles: BILL | CREDIT_NOTE
- offset: permite buscar desde un número de resultado en adelante Ej: offset=100 (devuelve a partir del resultado número 100).
- limit: limita la cantidad de resultados. Por defecto el mínimo es 150. Máximo valor permitido: 1000. Ej: limit=300 (devuelve hasta 300 resultados).
Resumen de facturación
Permite obtener el resumen de cargos y bonificaciones que tuvo el vendedor para un período de tiempo en particular.
Llamada para el site MLM:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/summary
Llamada para los sites MLA, MLB, MCO, MLC, MLU, MPE, MLV y MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/summary
Ejemplo para los sites MLA, MLB, MCO, MLC, MLU, MPE, MLV y MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06-01/summary?group=MP&document_type=BILL
Respuesta:
{
"user": {
"nickname": "TEST"
},
"period": {
"date_from": "2021-05-01",
"date_to": "2021-06-01",
"expiration_date": "2021-06-02"
},
"summary": {
"amount": 545562.37,
"credit_note": 0,
"tax": 0.00,
"bonuses": [{
"label": "Bonificación de MercadoPago",
"amount": 7354.60
},
{
"label": "Bonificación Impuesto a los Ingresos Brutos Cap. Fed.",
"amount": 116.43
},
{
"label": "Bonificación Impuesto al Valor Agregado Régimen General",
"amount": 116.43
}
],
"charges": [{
"label": "Cargo de MercadoPago",
"amount": 524228.80
},
{
"label": "Percepción General IIBB de CABA",
"amount": 13003.72
}, {
"label": "Percepción IVA Régimen General",
"amount": 13003.72
},
{
"label": "Cargo por transferencia de dinero",
"amount": 2913.59
}
]
}
}
Campos de la respuesta
- summary: cargos y bonificaciones que tuvo el vendedor.
- amount: total a pagar dentro del período de facturación consultado. Se forma con la suma de Cargos e Impuestos y resta de las Bonificaciones.
- credit_note: bonificaciones de cargos generados en otros períodos. Las notas de crédito se utilizan para pagar facturas adeudadas.
- tax percepciones generadas por los distintos regímenes impositivos.
- bonuses: reintegro de comisiones por tus ventas y servicios que no se concretaron. Los verás discriminados según el tipo de bonificación.
- label: nombre de la bonificación.
- amount: monto de dicha bonificación.
Llamada para los sites MLA, MLB, MCO, MLC, MLU, MPE, MLV y MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$KEY/summary/details
Ejemplo para los sites MLA, MLB, MCO, MLC, MLU, MPE, MLV y MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2023-10-01/summary/details
{
"user": {
"nickname": "TEST"
},
"period": {
"date_from": "2023-06-19",
"date_to": "2023-07-18",
"expiration_date": "2023-07-24",
"key": "2023-07-01"
},
"bill_includes": {
"total_amount": 171070532.64,
"total_perceptions": 33077380.48,
"bonuses": [
{
"label": "Bonificación cargo por Mercado Envíos",
"amount": 385261.63,
"type": "BXD",
"groupId": 3
},
{
"label": "Bonificación del cargo por venta",
"amount": 6123337.46,
"type": "BXD",
"groupId": 4
},
{
"label": "Bonificación campañas de publicidad - Product Ads",
"amount": 12967.5,
"type": "BXD",
"groupId": 5
},
{
"label": "Bonificación cargo por Mercado Envíos",
"amount": 28132.36,
"type": "BXD",
"groupId": 6
}
],
"charges": [
{
"label": "Campañas de publicidad - Product Ads",
"amount": 48600,
"type": "PADS",
"groupId": 24
},
{
"label": "Percepción impuesto a los IIBB Rég. General de Salta",
"amount": 111.18,
"type": "CXD",
"groupId": 25
},
{
"label": "Percepción impuesto IIBB Com. Electrónico La Pampa",
"amount": 178050.01,
"type": "CXD",
"groupId": 26
},
{
"label": "Percep. gral. impuesto IIBB CABA Mercado Envíos",
"amount": 257364.18,
"type": "CXD",
"groupId": 27
},
{
"label": "Percepción impuesto IIBB CABA",
"amount": 2593731.92,
"type": "CXD",
"groupId": 25
},
{
"label": "Cargo por Mercado Envíos",
"amount": 11195255.36
"type": "CXD",
"groupId": 24
},
{
"label": "Cargo por venta",
"amount": 131285530.48,
"type": "CV",
"groupId": 28
},
]
},
"payment_collected": {
"operation_discount": 136492738.16,
"total_payment": 33353689.85,
"total_credit_note": 1989281,
"total_collected": 171070532.64,
"total_debt": 0.00
},
"errors": []
}
Campos de la respuesta
- user
- nickname: nombre de usuario.
- period
- date_from: fecha comienzo período.
- date_to: fecha fin período.
- expiration_date: fecha de expiración.
- key: fecha del primer día del mes.
- bill_includes
- total_amount: monto total.
- total_perceptions: monto total percepciones.
- bonuses
- label: descripción de la bonificación.
- amount: monto de la bonificación.
- type: tipo de bonificación.
- groupId: grupo de la bonificación.
- charges
- label: descripción del cargo.
- amount: monto del cargo.
- type: tipo de cargo.
- groupId: grupo del cargo.
- payment_collected:
- operation_discount: operaciones descontadas de las ventas.
- total_payment: pagos realizados.
- total_credit_note: total notas de crédito.
- total_collected: total pagado.
- total_debt: total de la deuda.
Las bonificaciones pueden ser por los siguientes conceptos:
- Cargos de venta y envíos: si una venta no se concreta debido a una devolución o por problemas con el correo (como pérdida o daño del producto), te reintegramos la comisión de venta y el cargo de envío.
- Cargos de publicidad: si por error contrataste el servicio o hubo algún problema con el cobro, te reintegramos la diferencia.
- Bonificaciones por Percepciones Impositivas: cuando se devuelve un cargo por venta también se incluye la devolución correspondiente de la percepción impositiva de IVA (ya sea por un articulo nuevo o uno usado) y de Ingresos Brutos. Lo mismo si hubo errores en la aplicación de una percepción.
- charges: diferentes cargos que puede tener el vendedor: comisiones por ventas, costo de publicaciones, percepciones impositivas, cobros de servicios. Por ejemplo: Mercado Envíos, Mercado Shops, etc.
En caso de contratar campañas publicitarias, también aparecerán en los cargos.
Siguiente: Conciliaciones.