Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Última atualização em 25/03/2024
Relatórios de faturamento
Faturamento do Mercado Livre e Mercado Pago
Cada um dos endpoints permite obter informação de faturamento tanto do Mercado Livre, como do Mercado Pago. Através do parâmetro de query obrigatório group podemos especificar de que grupo de faturamento queremos obter a informação.
Obter período
Permite obter informação dos períodos de facturamento para o grupo de facturamento indicado (Mercado Livre ou Mercado Pago). Por padrão devolvemos os últimos 6 períodos, com a possibilidade de consultar períodos mais antigos utilizando a paginação de offset e limit.
Chamada para os sites MLM:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periodsChamada para os sites MLA, MLB MCO, MLC, MLU, MPE, MLV e MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/monthly/periodsExemplo para os sites MLA, MLB MCO, MLC, MLU, MPE, MLV e 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=2Resposta:
{
"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 da resposta
- amount: valor total do período.
- unpaid_amount: valor total pendente de pagamento.
- period: range de datas do período.
- date_from: data de início do período.
- date_to: data de fim do período.
Obter documentos de um período
Permite obter informação de documentos (faturas e notas de crédito) para um período de faturamento em particular para o grupo de faturamento indicado (Mercado Livre ou Mercado Pago).
Chamada para os sites MLM:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/documentsChamada para os sites MLA, MLC, MLU, MPE, MLV e MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/documentsExemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e 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=1Resposta:
{
"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 opcionais
- document_id: permite buscar pelo ID da fatura. Ex: document_id=987046992
- document_type: permite buscar por tipo de documento: Fatura ou Nota de Crédito. Valores possíveis: BILL | CREDIT_NOTE
- offset: permite buscar desde um número de resultado adiante. Ex: offset=100 (devolve a partir do resultado número 100).
- limit: limita a quantidade de resultados. Por padrão o mínimo é 150. Máximo valor permitido: 1000. Ex: limit=300 (devolve até 300 resultados).
Resumo de faturamento
Permite obter o resumo de comissões e bonificações que teve o vendedor para um período de tempo em particular.
Chamada para os sites MLM:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/summaryChamada para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/summaryExemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06 -012/summary?group=MP&document_type=BILLResposta:
{
"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 da resposta
- summary: cobranças e bonificações que o vendedor teve.
- amount: total a pagar dentro do período de faturamento consultado. É formado pela soma de Cobranças e Impostos subtraindo as Bonificações.
- credit_note: bonificações de cobranças geradas em outros períodos. As notas de crédito são utilizadas para pagar faturas de dívidas.
- tax: percepções geradas por distintos regimes tributários (Argentina).
- bonuses: eembolso de comissões por suas vendas e serviços que não se concretizaram. Você vai vê-los discriminados segundo o tipo de bonificação.
- label: nome da bonificação.
- amount: valor desta bonificação.
Chamada para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'https://api.mercadolibre.com/billing/integration/periods/key/$KEY/summary/detailsExemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e 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 da resposta
- user
- nickname: nome do usuário.
- period
- date_from: data de início do período.
- date_to: data do fim do período.
- expiration_date: data de expiração.
- key: data do primeiro dia do mês.
- bill_includes
- total_amount: valor total.
- total_perceptions: valor total dos pagamentos.
- bonuses
- label: descrição da bonificação.
- amount: valor da bonificação.
- type: tipo de bonificação.
- groupId: grupo da bonificação.
- charges
- label: descrição da cobrança
- amount: valor da cobrança.
- type: tipo de cobrança.
- groupId: grupo da cobrança.
- payment_collected:
- operation_discount: operações descontadas das vendas.
- total_payment: pagamentos realizados.
- total_credit_note: total de notas de crédito.
- total_collected: total pago.
- total_debt: total da dívida.
As bonificações podem ser pelos seguintes conceitos:
- Cobranças de venda e envios: se uma venda não se concretiza devido a uma devolução ou por problemas no transporte (como perda ou dano do produto), reembolsaremos a comissão de venda e a cobrança do envio.
- Cobranças de publicidade: se por erro for contratado o serviço ou houve algum problema com o pagamento, reembolsaremos a diferença.
- Bonificações por Percepções Tributárias: quando se devolve uma cobrança por venda também se inclui a devolução correspondente da percepção tributária de IVA (já seja por um anúncio de novo ou usado) e da renda bruta. O mesmo se houver erros na aplicação de uma percepção.
- charges: diferentes cobranças que pode ter o vendedor: comissões por vendas, custo de publicações, percepções tributárias, pagamento de serviços. Por exemplo: Mercado Envios, Mercado Shops, etc.
No caso de contratar campanhas publicitárias, também aparecerão nas cobranças.