Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 21/10/2024

Reportes de facturación

Con esta funcionalidad puedes conocer los reportes de la facturación realizada por Mercado Libre y Mercado 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 puedes acceder al resumen de facturación de un período y a sus detalles respectivamente.

Nota:
Todos los endpoints requieren el parámetro group, grupo de facturación para obtener información: ML (Mercado Libre) o MP (Mercado Pago). En caso de no especificarlo, obtienes información de ambos.

Obtener período

Consultar en primer lugar este endpoint es opcional, ya que la key necesaria para consumir el resto de los endpoint es el primer día del mes. Por ejemplo: 2023-06-01.
Te 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 recibes los últimos 6 periodos, con la posibilidad de consultar períodos más antiguos utilizando la paginación de offset y limit (valor máximo: 12).


Parámetro obligatorio

document_type: tipo de documento a obtener. Puede ser Bill o Credit_note.


Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/monthly/periods

Ejemplo:

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.


key: es la fecha del primer día del mes. Para MLA, MLB, MCO, MLC, MLU, MPE, MLV y MCR es el valor utilizado para consumir los endpoints de documents, details y summary.
expiration_date: es la fecha de cierre del período. Se informa siempre que el estado del período se encuentre cerrado. Para el resto de los sites (MLM) es el valor utilizado para consumir los endpoints de documents, details y summary.
debt_expiration_date: es la fecha de vencimiento de la deuda. En el caso que no se mueva la fecha de vencimiento este campo será igual a expiration_date.
debt_expiration_date_move_reason: motivo del cambio de fecha de vencimiento de la deuda. En el caso que no se mueva la fecha de vencimiento este campo será null. Valores posibles: AUTOMATIC_DOCUMENT_CLOSURE_PROCES, RECEIPT_ANNULMENT_PROCESS_UNRECORDED, RECEIPT_ANNULMENT_PROCESS, PERIOD_EXTENDED_BY_ADMIN, PAYMENT_ANNULMENT.
debt_expiration_date_move_reason_description: descripción internacionalizada de debt_expiration_date_move_reason. En el caso que no se mueva la fecha de vencimiento este campo será null.
period_status: indica si el período se encuentra abierto o cerrado. Valores posibles: OPEN, CLOSED.

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


Parámetros opcionales

document_id: buscas por el id de la factura. Ej: document_id=987046992.
document_type: filtras 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).

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/$KEY/documents

Ejemplo:

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

Resumen de facturación

Permite obtener el resumen de cargos y bonificaciones que tuvo el vendedor para un período de tiempo en particular.

Importante:

No recomendamos utilizar este endpoint dentro de un procesamiento batch. Su uso es recomendado de forma secuencial. La información que provee este endpoint no se modifica durante el día, con lo cual un consumo diario por usuario es suficiente.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$KEY/summary/details

Ejemplo:

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.


Errores

Código Tipo Mensaje Solución
206 Partial content An error occurred while retrieving the information. Try again. Sucede cuando faltan algunos datos y la respuesta es incompleta. Aplica a todos los recursos, excepto el download de documento legal y reporte de conciliación en formato XLSX y CSV.
403 ABUSE_PREVENTION_ERROR Bloquea preventivamente una cantidad limitada de request por IP. Evita realizar pegadas repetitivas que no requieran el uso de limit y offset para paginar.

Siguiente: Conciliaciones.