Reportes de facturación

Con esta funcionalidad puedes conocer los reportes de la facturación realizada por Mercado Libre para los vendedores. Para esto, te recomendamos consultar /billing/period para obtener información de los últimos 12 períodos, luego con /bills conseguirás todas las facturas (documentos) de un periodo, y finalmente, con /summary y /details accedes al resumen de facturación de un periodo y sus detalles respectivamente.

Contenidos

→Reportes de Mercado Pago
→Obtener período
→Obtener documentos de un período
→Resumen de facturación
→Detalle de conciliación
↳Filtros opcionales

Reportes de Mercado Pago

Ahora puedes utilizar el parámetro society=MP en todos los recursos para obtener información de la facturación de Mercado Pago para realizar la conciliación de las facturas. Por defecto, si no lo envías, devolveremos información de la facturación de Mercado Libre.

Ejemplo:

curl -X GET  -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/123456789/billing/period/20190510/details&society=MP

Respuesta:

{
   "paging":{
      "offset":5,
      "limit":150,
      "total":238618
   },
   "results":[
      {
         "concept":"Pago Comisión MercadoPago",
         "id":878787878787,
         "type":"MP",
         "subtype":"CCMP",
         "detail_type":"CHARGE",
         "date_created":"2021-02-01T04:01:01",
         "prepaid":true,
         "amount":1.47,
         "currency_id":"ARS",
         "site_id":"ARS",
         "document":{
            "id":123456789,
            "date_of_expiration":"2021-03-02",
            "society":"MERCADO-PAGO"
         },
         "mp_info":{
            "id":15454547,
            "ref":"53245543",
            "amount":152,
            "detail":"payment",
            "nickname":"nickname"
         }
      }
   ]
}

Nota:

Si envías un society inválido o utilizas society=MP junto con algún de los filtros type, order_id, item_id, date_from y/o date_to, la API retornará los siguientes errores:

Error por society inválido:

{
   "statusCode": 1024,
   "message": "Society parameter is invalid. Possible value: MP"
}

Error por utilizar un filtro no permitido con society=MP:

{
   "statusCode": 1019,
   "message": "Filter type is not allowed to get Mercado-Pago society details"
}

Obtener período

Importante:

El período de facturación puede variar según el usuario. Además, no podrás realizar consultas con usuarios TEST.

Conoce el período para luego consultar el Resumen y Detalle de conciliación.
Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/billing/period

Ejemplo:

curl -X GET  -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/123456789/billing/period

Respuesta:

{
    "period": [
        {
            "paid": "Y",
            "date_from": "2020-02-05T00:00:00.000-04:00",
            "date_to": "2020-03-04T00:00:00.000-04:00",
            "expiration_date": "2020-03-10T00:00:00.000-04:00",
            "period": "20200310",
            "total_amount": 3440,
            "bills": [
                {
                    "id": 1003544720,
                    "status": "A",
                    "expired_date": "2020-03-10T00:00:00.000-04:00",
                    "amount": 3440,
                    "pending_amount": 0,
                    "pay_status": "Y",
                    "period": {
                        "date_from": "2020-02-05T00:00:00.000-04:00",
                        "date_to": "2020-03-04T00:00:00.000-04:00"
                    },
                    "url_invoice": "https://myaccount.mercadolibre.com.uy/billing/v2/api/billing/user/123456789/invoices/349ac13f-b578?type=pdf"
                }
            ]
        },
        {
            "paid": "Y",
            "date_from": "2020-01-05T00:00:00.000-04:00",
            "date_to": "2020-02-04T00:00:00.000-04:00",
            "expiration_date": "2020-02-10T00:00:00.000-04:00",
            "period": "20200210",
            "total_amount": 3440,
            "bills": [
                {
                    "id": 980292894,
                    "status": "A",
                    "expired_date": "2020-02-10T00:00:00.000-04:00",
                    "amount": 3440,
                    "pending_amount": 0,
                    "pay_status": "Y",
                    "period": {
                        "date_from": "2020-01-05T00:00:00.000-04:00",
                        "date_to": "2020-02-04T00:00:00.000-04:00"
                    }
                }
            ]
        },
        {
            "paid": "Y",
            "date_from": "2019-12-05T00:00:00.000-04:00",
            "date_to": "2020-01-04T00:00:00.000-04:00",
            "expiration_date": "2020-01-10T00:00:00.000-04:00",
            "period": "20200110",
            "total_amount": 3180,
            "bills": [
                {
                    "id": 958238325,
                    "status": "A",
                    "expired_date": "2020-01-10T00:00:00.000-04:00",
                    "amount": 3180,
                    "pending_amount": 0,
                    "pay_status": "Y",
                    "period": {
                        "date_from": "2019-12-05T00:00:00.000-04:00",
                        "date_to": "2020-01-04T00:00:00.000-04:00"
                    },
                    "url_invoice": "https://myaccount.mercadolibre.com.uy/billing/v2/api/billing/user/123456789/invoices/36006403-dc10?type=pdf"
                }
            ]
        },
        {
            "paid": "Y",
            "date_from": "2019-11-05T00:00:00.000-04:00",
            "date_to": "2019-12-04T00:00:00.000-04:00",
            "expiration_date": "2019-12-10T00:00:00.000-04:00",
            "period": "20191210",
            "total_amount": 3180,
            "bills": [
                {
                    "id": 935204108,
                    "status": "A",
                    "expired_date": "2019-12-10T00:00:00.000-04:00",
                    "amount": 3180,
                    "pending_amount": 0,
                    "pay_status": "Y",
                    "period": {
                        "date_from": "2019-11-05T00:00:00.000-04:00",
                        "date_to": "2019-12-04T00:00:00.000-04:00"
                    }
                }
            ]
        },
    ]
}

Campos de la respuesta

paid: campo que indica si se pagó la factura.
date_from: es la fecha de inicio de dicho documento.
date_to: es la fecha de último día.
expiration_date: es la fecha de vencimiento de dicho documento.
period: número de periodo a utilizar en los siguientes recursos.
total_amount: monto total de todos los documentos de ese período.
bills: devuelve una lista con todos los documentos existentes en el período buscado.

id: identificador del documento.
status: estado del documento, si está activo o inactivo.
expired_date: fecha de expiración del documento.
amount: monto de la cabecera del documento.
pending_amount: monto restante a pagar.
pay_status: si el documento se encuentra pago o impago (Y o N).
period: período en el cual entran los cargos de los mismos.

date_from: fecha de creación del primer cargo del período.
date_to: fecha de creación del último cargo del período.

url_invoice: URL de la factura legal generada.

Notas:

- El campo paid puede no aparecer para todas las cuentas. Este recurso devuelve como máximo los últimos 12 períodos.
- El campo url_invoice puede no aparecer si es que al momento de la consulta, no existe una factura legal para ese documento.

Obtener documentos de un período

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/bills?$FI LTROS_OPCIONALES

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/443033562/period/20210101/bills?offset=150

Respuesta:

{
   "paging":{
      "offset":150,
      "limit":150,
      "total":238618
   },
   "results":[
      {
         "id":1003544720,
         "expired_date":"2020-03-10T00:00:00.000-04:00",
         "amount":3440,
         "pending_amount":0,
         "pay_status":"Y",
         "period":{
            "date_from":"2020-02-05T00:00:00.000-04:00",
            "date_to":"2020-03-04T00:00:00.000-04:00"
         }
      }
   ]
}

Filtros disponibles

document_id: Permite buscar por el id de la factura. Ej: document_id=987046992
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

Para conocer un resumen de los cargos y compensaciones que tuviste como vendedor dentro de un período de tiempo, debes hacer un GET al recurso /summary.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/summary

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/443033562/billing/period/20190510/summary

Respuesta:

{
  "user": {
    "nickname": "TESTING123"
  },
  "period": {
    "date_from": "2019-04-05T00:00:00.000-04:00",
    "date_to": "2019-05-04T00:00:00.000-04:00",
    "date_of_expiration": "2019-05-10T00:00:00.000-04:00"
  },
  "summary": {
    "amount": 4141767.47,
    "credit_note": 43111.7,
    "tax": 492483.66,
    "bonuses": [
      {
        "label": "Bonificación del cargo por venta",
        "amount": 71007.49
      },
    ],
    "charges": [
      {
        "label": "Cargo por venta",
        "amount": 2784300.73
      },
      {
        "label": "Cargo por Mercado Envíos",
        "amount": 605717.77
      },
       {
        "label": "Percepción IIBB Com. Electrónico",
        "amount": 15529.9
      }
     ]
  }
}

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.

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.

Detalle de conciliación

El detalle de conciliación es un reporte donde podrás conciliar tus facturas de Mercado Libre y Mercado Envíos con los cargos de las ventas que realizaste.

Nota:

Si consultas con un offset superior a 10.000, te recomendamos utilizar los siguientes filtros y acotar los resultados, evitando respuestas demoradas.

Filtros opcionales disponibles

date_sort
asc: ordena los resultados de manera ascendente (valor por default)
desc: ordena los resultados de manera descendente
Ej: date_sort=asc

date_from y date_to: Deben ser utilizados juntos y permite buscar dentro de un rango de fechas. También podés utilizar horas. Recuerda que el rango de fecha siempre debe estar dentro de las fechas de inicio y fin del período
Formatos posibles: yyyy-MM-dd o yyyy-MM-ddThh:mm:ss.sss.
Ej: Sólo fecha: date_from=2019-05-09&date_to=2019-05-15
Fecha y hora: date_from=2019-05-09T00:00:00.000&date_to=2019-05-15T00:00:00.000.

det_id: permite buscar un id de detalle específico
Ej: det_id=8398490328

det_type
charge: trae solamente cargos
bonus: trae solamente bonificaciones
Ej: det_type=charge

subtypes: permite filtrar por subtipos de detalles. Se pueden definir varios separados por coma.
Ej: subtypes=CV,BV

not_subtypes: permite excluir de la búsqueda los subtipos de detalles indicados. Se pueden definir varios separados por coma.
Ej: not_subtypes=CXD,BXD

type: permite buscar por el market del detalle.
Ej: type=SHIPPING

order_id: permite buscar por el id de la order.
Ej: order_id=2294412230

item_id: permite buscar por el id de la publicación.
Ej: item_id=724159812

document_id: permite buscar por el id de la factura.
Ej: document_id=987046992

offset: permite buscar desde un número de resultado en adelante
Ej: offset=100 (devuelve a partir del resultado nro 100)

limit: limita la cantidad de resultados. Por defecto el mínimo es 150 y el máximo valor permitido: 1000.
Ej: limit=300 (devuelve hasta 300 resultados)

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/details&$FILTROS_OPCIONALES

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/443033562/billing/period/20190510/details

Respuesta:

{
    "paging": {
        "total": 2679,
        "offset": 0,
        "limit": 150
    },
    "results": [
        {
            "concept": "Cargo por Mercado Envíos",
            "id": 5782869395,
            "type": "SHIPPING",
            "subtype": "CFF",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 68.4,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290642081
            },
            "detail_type": "CHARGE",
            "mp_op_id": 28226734621
        },
        {
            "concept": "Cargo por venta",
            "id": 5782859370,
            "type": "CORE",
            "subtype": "CV",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 272.87,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290642081,
                "item_id": 725366950
            },
            "detail_type": "CHARGE",
            "mp_op_id": 5801583834
        },
        {
            "concept": "Cargo por Mercado Envíos",
            "id": 5782887632,
            "type": "SHIPPING",
            "subtype": "CFF",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 50.8,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290649986
            },
            "detail_type": "CHARGE",
            "mp_op_id": 28226824168
        },
        {
            "concept": "Cargo por venta",
            "id": 5782887634,
            "type": "CORE",
            "subtype": "CV",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 285.87,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290649986,
                "item_id": 620189246
            },
            "detail_type": "CHARGE",
            "mp_op_id": 5801916351
        },
        {
            "concept": "Cargo por Mercado Envíos",
            "id": 5782897217,
            "type": "SHIPPING",
            "subtype": "CFF",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 68.4,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290651588
            },
            "detail_type": "CHARGE",
            "mp_op_id": 28226713276
        },
]

Campos de la respuesta

concept: son todas las ventas y operaciones que realizaste durante tu período de facturación.

type: es la unidad de negocio al que pertenece el cargo.

core: son principalmente comisiones por venta, pero también contempla la compra de productos y la comisión por garantía. En Ecuador y Costa Rica, también es por publicar en el marketplace.
mp: cargos y percepciones generadas por Mercado Pago.
shipping: cargos relacionados a envíos.
taxes: impuestos nacionales y provinciales de Mercado Libre (Argentina).
eshop: cargos de eShop.
mshops: cargos de Mercado Shops.
mclics: cargos relacionados a publicidad.
becommerce: es por el uso de la plataforma de beCommerce (Brasil).
credits: cargos por los productos de Mercado Crédito (Argentina, Brasil y México).
classified: son los cargos por los paquetes de publicaciones y por la publicación en categorías de clasificados de un usuario normal. También son los cargos por showroom.
mango: cargos por el uso de la plataforma Mango (Argentina).

subtype: es el subtipo de concepto que te permitirá identificar mejor cada operación. Hay 1100 subtypes para distinguir cargos, subscripciones, paquetes, percepciones, bonificaciones, anulaciones, servicios, etc.

date: es la fecha de la transacción.

prepaid:

true: el cargo es debitado automáticamente a través de Mercado Pago.
false: el cargo NO es debitado automáticamente.

amount: monto del detalle.

currency_id: identificador de la moneda de acuerdo al site_id.

site_id: sitio donde se generó el detalle.

document:

id: número de identificación del documento.
date_of_expiration: es la fecha de vencimiento de dicho documento.
society: hace referencia a la entidad que emite los documentos.

order:

id: número de identificación de la orden vinculada al concepto.
item_id: número de identificación del producto comprometido en la orden.

detail_type: indica si es cargo (charge) o bonificación (bonus).

mp_op_id: es el número de operación de Mercado Pago.