Reportes de facturación

Los siguientes recursos de API te permitirán conocer los resúmenes de facturación de tus ventas en Mercado Libre.

Contenidos

→Obtención de período
→Resumen de facturación
→Detalle de conciliación
↳Filtros opcionales

Obtención de período

Importante:

El período de facturación puede variar según el usuario.
No es posible realizar consultas con usuarios de TEST.

Para conocer el período con el cual realizar la consulta a los recursos de Resumen y Detalle de conciliación, deberás realizar un GET al siguiente recurso:
Llamada:

curl -X GET https://api.mercadolibre.com/users/$USER_ID/billing/period?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X GET  https://api.mercadolibre.com/users/123456789/billing/period?access_token=$ACCESS_TOKEN

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 del recurso

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.

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  https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/summary?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X GET  https://api.mercadolibre.com/users/443033562/billing/period/20190510/summary?access_token=$ACCESS_TOKEN

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
      }
     ]
  }
}

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
      },
    ]
  }
}

Campos del recurso

Summary: acá veremos los Cargos y Bonificaciones que tuvo el vendedor.
amount: Es el 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: Son las bonificaciones de cargos generados en otros períodos. Las notas de crédito se utilizan para pagar facturas adeudadas.
tax: Son las percepciones generadas por los distintos regímenes impositivos.
bonuses: Es el 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: Representan los diferentes cargos que puede tener el vendedor: comisiones por ventas, costo de publicaciones, percepciones impositivas , cobros de servicios (Ejemplo: Mercado Envíos, Mercado Shops, etc)
En caso de contratar campañas publicitarias, también aparecen aquí.

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. Para eso deberás hacer un GET al recurso Details.
Además podrás utilizar filtros que te permitirán acotar y hacer más específica tu búsqueda.

Nota:

En el caso de que la respuesta tenga más de 10.000 registros, debes utilizar los siguientes filtros para acotar los resultados, ya que el recurso devuelve hasta dicha cantidad. En caso de superar este límite, la respuesta será un error 500.

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.
Ej: limit=300 (devuelve hasta 300 resultados)

Llamada:

curl -X GET https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/details?access_token=$ACCESS_TOKEN&$FILTROS_OPCIONALES

Ejemplo:

curl -X GET https://api.mercadolibre.com/users/443033562/billing/period/20190510/details?access_token=$ACCESS_TOKEN

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 del recurso

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.
eshop: cargos de eShop.
mshops: cargos de Mercado Shops.
mclics: cargos relacionados a publicidad.
becommerce: es por el uso de la plataforma de beCommerce en Brasil.
credits: cargos por los productos de Mercado Crédito.
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.

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.